react-native-shortcut-custom v0.4.13

React Native Shortcut Custom Plugin Documentation

Introduction

This plugin allows you to create and manage Android shortcuts and perform actions like updating contacts, fetching contacts, and initiating direct calls from your React Native application.

The plugin supports the following functionalities:

1. Add pinned shortcuts
2. Add dynamic shortcuts
3. Remove all shortcuts
4. Fetch available asset icons
5. Update contact information
6. Fetch contacts by ID
7. Fetch all contacts
8. Initiate direct calls

Available Methods

addShortcutToScreen

Creates a pinned shortcut on the home screen with a custom icon and a specific phone number.

Parameters:

• shortcutDetails (object):
  • phoneNumber (string): Phone number for the shortcut action.
  • shortLabel (string): Short label for the shortcut.
  • longLabel (string): Long label for the shortcut.
  • iconName (string): Name of the icon from assets.

Example:

await addShortcutToScreen({
  phoneNumber: '1234567890',
  shortLabel: 'Call John',
  longLabel: 'Call John Doe directly',
  iconName: 'phone_icon.png',
});

addDynamicShortcut

Adds a dynamic shortcut that appears in the long-press menu of the app icon.

Parameters:

• shortcutDetails (object):
  • id (string): Unique identifier for the shortcut.
  • shortLabel (string): Short label for the shortcut.
  • longLabel (string): Long label for the shortcut.
  • url (string): URL or deep link for the shortcut action.

Example:

await addDynamicShortcut({
  id: 'dynamic_shortcut_1',
  shortLabel: 'Open Google',
  longLabel: 'Access Google',
  url: 'https://www.google.com',
});

removeAllDynamicShortcuts

Removes all dynamic shortcuts.

Example:

await removeAllDynamicShortcuts();

removeAllShortcuts

Removes all pinned and dynamic shortcuts.

Example:

await removeAllShortcuts();

getAssetIcons

Fetches the list of available icons from the assets folder.

Example:

const icons = await getAssetIcons();
console.log(icons); // ['icon1.png', 'icon2.png']

updateContact

Updates an existing contact with the provided details.

Parameters:

• contactDetails (object): Contact details to update. Must include recordID and rawContactID.

Example:

await updateContact({
  recordID: '123',
  rawContactID: '456',
  givenName: 'John',
  familyName: 'Doe',
  phoneNumbers: [{ label: 'mobile', number: '1234567890' }],
});

getContactById

Fetches a contact by its recordID.

Example:

const contact = await getContactById({ recordID: '123' });
console.log(contact);

getAllContacts

Fetches all contacts from the device.

Example:

const contacts = await getAllContacts();
console.log(contacts);

addDirectCallShortcut

Initiates a direct call to a given phone number. For standard phone numbers, the call is made directly. For emergency numbers (3-4 digits), the dialer screen will open.

Parameters:

• shortcutDetails (object):
  • phoneNumber (string): Phone number to call.

Example:

await addDirectCallShortcut({ phoneNumber: '42999339947' }); // Direct call
await addDirectCallShortcut({ phoneNumber: '190' }); // Opens the dialer for emergency numbers

⚠️ Important Note About Direct Calls

When using the plugin to make direct calls, please be aware of the following behavior:

• Standard phone numbers (e.g., mobile or landline): The call is made directly without showing the dialer screen.
• Short numbers (e.g., emergency services like 911, 190, 192): The dialer screen will always open, even if the CALL_PHONE permission is granted.

Why Does This Happen?

Android enforces this behavior for safety and security reasons to prevent accidental calls to emergency services. It is not possible to bypass this restriction.

Summary Table

Conclusion

This plugin provides an easy way to manage Android shortcuts and perform advanced actions like direct calls and contact management. Use it to improve your app's user experience with quick actions and powerful features.

Happy coding!

🙌 Contributing

We welcome contributions! Please read our contributing guide to learn how to get started.

📄 License

MIT

Made with ❤️ using create-react-native-library