diff --git a/README.md b/README.md index be5170d..9122fb0 100644 --- a/README.md +++ b/README.md @@ -1,79 +1,39 @@ -react-native home screen quick actions -====================================== +# React Native Quick Actions Support for the new 3D Touch home screen quick actions for your React Native apps! -Please note that on Android if `android:launchMode` is set to default value `standard` in AndroidManifest.xml, the app will be re-created each time when app is being brought back from background and it won't receive `quickActionShortcut` event from DeviceEventEmitter, instead `popInitialAction` will be receiving the app shortcut event. +**This project currently supports iOS 9+ and Android 7** -__This project currently supports iOS 9+ and Android 7__ - -![](http://i.imgur.com/holmBPD.png) - -## Supported React Native Versions - -| React Native version(s) | Supporting react-native-quick-actions version(s) | -|-------------------------|--------------------------------------------------| -| < v0.40 | v0.1.5 | -| v0.40+ | v0.2.0+ | +![](/assets/example.png) ## Installing -First cd into your project's directory and grab the latest version of this code: - -```bash -$ yarn add --dev react-native-quick-actions -``` - -Then link quick actions to your project: - ```bash +$ yarn add react-native-quick-actions $ react-native link react-native-quick-actions ``` -### iOS +### Additional steps on iOS -Add the following lines to your `AppDelegate.m` file: - -```obj-c -#import "RNQuickActionManager.h" - -// @implementation AppDelegate - -- (void)application:(UIApplication *)application performActionForShortcutItem:(UIApplicationShortcutItem *)shortcutItem completionHandler:(void (^)(BOOL succeeded)) completionHandler { - [RNQuickActionManager onQuickActionPress:shortcutItem completionHandler:completionHandler]; -} - -// @end -``` +Add the following lines to your `AppDelegate.m` file: -### Android +```obj-c +#import "RNQuickActionManager.h" -Add the following lines in your main Application +// @implementation AppDelegate -``` -import com.reactNativeQuickActions.AppShortcutsPackage; - -protected List getPackages() { - return Arrays.asList( - ... - new AppShortcutsPackage() - ); +- (void)application:(UIApplication *)application performActionForShortcutItem:(UIApplicationShortcutItem *)shortcutItem completionHandler:(void (^)(BOOL succeeded)) completionHandler { + [RNQuickActionManager onQuickActionPress:shortcutItem completionHandler:completionHandler]; } + +// @end ``` ## Usage -Now let's see how you can use this library to trigger shortcut actions in your react native app. - ### Adding static quick actions - iOS only -This part is pretty easy. There are a [bunch of -tutorials](https://littlebitesofcocoa.com/79) and -[docs](https://developer.apple.com/library/prerelease/ios/samplecode/ApplicationShortcuts/Introduction/Intro.html#//apple_ref/doc/uid/TP40016545) out there that -go over all your options, but here is the quick and dirty version: - -Add these entries into to your `Info.plist` file and replace the generic stuff -(Action Title, .action, etc): +Add these entries into to your `Info.plist` file and replace the generic stuff (Action Title, .action, etc): ```xml UIApplicationShortcutItems @@ -91,77 +51,87 @@ Add these entries into to your `Info.plist` file and replace the generic stuff A full list of available icons can be found here: - + ### Adding dynamic quick actions -In order to add / remove dynamic actions during application lifecycle, you need to require `react-native-quick-actions` and call either `setShortcutItems` or `clearShortcutItems` (useful when user is logging out). +In order to add / remove dynamic actions during application lifecycle, you need to import `react-native-quick-actions` and call either `setShortcutItems` to set actions or `clearShortcutItems` to clear. ```js -var QuickActions = require('react-native-quick-actions'); +import QuickActions from "react-native-quick-actions"; -// Add few actions QuickActions.setShortcutItems([ { type: "Orders", // Required title: "See your orders", // Optional, if empty, `type` will be used instead subtitle: "See orders you've made", - icon: "Compose", // Pass any of UIApplicationShortcutIconType + icon: "Compose", // Icons instructions below userInfo: { - url: "app://orders" // provide custom data, like in-app url you want to open + url: "app://orders" // Provide any custom data like deep linking URL } } ]); +``` -// Clear them all +To clear actions: + +```js QuickActions.clearShortcutItems(); ``` -In order to specify icon for your shortcut item, either include `UIApplicationShortcutIconType`, e.g. for `UIApplicationShortcutIconTypeCompose` go with `Compose` or define your asset name if you want to use image from a template (e.g. `my-custom-icon` if that's the name of image in `Images.xcassets`. Remember not to name your custom icons the same as any system icons otherwise system ones will be loaded instead). +#### Icons -Full list of available icons has been already listed in the previous section. +##### iOS -For Android icons, names must contain only lowercase a-z, 0-9, or underscore. So `guide_icon.png` would be acceptable but `guide-icon.png` would not be. Place your icons in res/drawable folder and set them when you create your shortcuts in setShortcutItems in the following way -```js -{ - ... - icon: "guide_icon", - ... -} -``` -### Listening for quick actions in your javascript code +On iOS you can use the default icons provided by Apple, they're listed here: https://developer.apple.com/design/human-interface-guidelines/ios/icons-and-images/system-icons/#quick-action-icons + +You can also use custom icons creating new Image set inside Image.xcassets on XCode. You'll need to define the 1x, 2x and 3x sizes. + +![](/assets/ios.png) + +##### Android + +On Android you'll need to create an image file (use PNG) inside `android/app/src/main/res/drawable`. + +Name the image with underscores, don't use hyphens. + +### Listening for quick actions First, you'll need to make sure `DeviceEventEmitter` is added to the list of -requires for React. +requires for React Native. ```js -var React = require('react-native'); -var { - //....things you need plus.... - DeviceEventEmitter -} = React; - +import { DeviceEventEmitter } from "react-native"; ``` Use `DeviceEventEmitter` to listen for `quickActionShortcut` messages. ```js -var subscription = DeviceEventEmitter.addListener( - 'quickActionShortcut', function(data) { - console.log(data.title); - console.log(data.type); - console.log(data.userInfo); - }); +DeviceEventEmitter.addListener("quickActionShortcut", data => { + console.log(data.title); + console.log(data.type); + console.log(data.userInfo); +}); ``` To get any actions sent when the app is cold-launched using the following code: ```js -var QuickActions = require('react-native-quick-actions'); +import QuickActions from "react-native-quick-actions"; -QuickActions.popInitialAction().then(doSomethingWithTheAction).catch(console.error) +function doSomethingWithTheAction(data) { + console.log(data.title); + console.log(data.type); + console.log(data.userInfo); +} + +QuickActions.popInitialAction() + .then(doSomethingWithTheAction) + .catch(console.error); ``` +Please note that on Android if android:launchMode is set to default value standard in AndroidManifest.xml, the app will be re-created each time when app is being brought back from background and it won't receive quickActionShortcut event from DeviceEventEmitter, instead popInitialAction will be receiving the app shortcut event. + ### Check if 3D Touch is supported The following function will alert you if the user's device supports 3D Touch. Please @@ -169,14 +139,13 @@ note this project currently only supports iOS 9+ which means this code will not work on iOS devices running versions < 9.0. ```js -var QuickActions = require('react-native-quick-actions'); +import QuickActions from "react-native-quick-actions"; -QuickActions.isSupported(function(error, supported) { +QuickActions.isSupported((error, supported) => { if (!supported) { - console.log('Device does not support 3D Touch or 3D Touch is disabled.'); + console.log("Device does not support 3D Touch or 3D Touch is disabled."); } }); - ``` ## License diff --git a/assets/example.png b/assets/example.png new file mode 100644 index 0000000..d318ca4 Binary files /dev/null and b/assets/example.png differ diff --git a/assets/ios.png b/assets/ios.png new file mode 100644 index 0000000..ffac825 Binary files /dev/null and b/assets/ios.png differ