React SDK
This page gives you all of the documentation needed to integrate the 2mee React ( 0.63.4) SDK . This page will be updated with any changes or new features added to the SDK.
Last updated
This page gives you all of the documentation needed to integrate the 2mee React ( 0.63.4) SDK . This page will be updated with any changes or new features added to the SDK.
Last updated
This document will guide you through the example Appear2meeReact app provided in the React SDK giving you guidance on how to display Instant Human Messages on Android and iPhone devices. The guide will also show you how to display standard text and rich media messages.
This document will refer to the sample Appear2meeReact App supplied within the Appear2mee React SDK.
If you need to download the Appear2mee React SDK use this link https://www.2mee.com/SDK/Appear2meeReactSDK.zip. You may need open this link in a new tab, or just copy and paste the link.
Messages are sent from the 2mee Exchange using push notifications. The notification includes the url/s of files that are required to display the notification. These files must be downloaded by the device in order to present the notification. If the message file is not available in the time allotted by iOS/Android a fallback text is “posted” as the notification. This fallback text is included in the notification and is set by your exchange user.
iOS 3D Touch is a pressure-sensitive feature that uses capacitive sensors integrated into the smartphone's display to sense the pressure of a touch. A 3D Touch on a notification will bring up an extended view of the notification. Appear2mee messages use a Content Extension to display this extended view. Since iOS 12.1.1 haptic touch does the same thing. Haptic touch measures the spreading touch of your finger pad as you press harder on the screen and gives a feedback vibration.
If the user does a 3D Touch on a notifications, the Appear2mee SDK will display the full message in an extended view (Content Extension). The in app view will only be shown, if the user does a light (normal) touch on the notification.
This guide assumes you have a degree of familiarity with React Native. If not you are recommended to look at the React Native web resources starting at the main react native site.
If you have an existing app you are adding the Appear2mee functionality to you yo will have to adapt the instruction to your need. The Appear2mee system is designed to operate separately from an existing apps layout with dialogs appearing on top of the existing layout. However where you need to interact with your users responses to notifications some customisation will be required.
If you do not have an existing react native app create one,
This will create a skeleton app with iOS and android apps. If you already have an existing React Native app, change to the root directory.
Next add the react-native-appear2mee. This module is hosted on bitbucket so the npm calls might be different to what you expect.
Android 12
Or if you use expo
Android 11
The module react-native-appear2mee depends on the zo0r/react-native-push-notification for android notifications, and the react-native-push-notification-ios/push-notification-ios for iOS notifications. This allows you to integrate other push notification providers you might be using as well as the 2mee Exchange.
After the package is installed note any peer dependencies that are not already in your app that need to be installed, and install these as well (react-native-push-notification and push-notification-ios)
Then run the react pod install command to link the package to iOS. Android seems to autolink.
At this stage both the android and iOS apps may compile, build and run (android may need firebase installed), but in any case they are not ready to receive notifications as both systems need different customisations to allow then to register for and receive notification.
Both the android and iOS share the same javascript App definition. In the Example app there are two “Apps”. The simplest possible integration is in AppSimpleSimple.js which adds an appear2mee notification listener to the simple app generated by npx react-native init. A navigation based app is provided in AppNavigation.js, which provides controls and view that show Appear2mee features, such as tags, userID, and message permissions.
The selected app can changed by editing the root index.js file in the example project. We will use the AppSimpleSample.js to explain the setup, look in the example project for more details! The AppSimpleSample.js adds the following code to import required functionality.
The Appear2mee SDK handles the display of notification dialogs and views. Your app however is left to handle the user response to the notification. The responses are returned as events. There are two events, Appear2mee.notificationAccepted which is send when a user “accepts” the notification and a Appear2mee.notificationDismissed if the notification is instead dismissed. Both of these events also return a dictionary of key values pairs. These are always strings. The keyValues are set at the 2mee Exchange by the sender of the push notification an so are custom to your app. How a sender sets and how you respond to these is custom to your app.
Appear2meeEmitter.addListener(Appear2mee.notificationAccepted,
(keyValues) => {
if (!keyValues) {
keyValues = {};
}
console.log("Notification Accepted:" + JSON.stringify(keyValues));
});
Appear2meeEmitter.addListener(Appear2mee.notificationDismissed,
(keyValues) => {
if (!keyValues) {
keyValues = {};
}
console.log("Notification Dismissed:” +
JSON.stringify(keyValues));
});
In the simple sample the values are printed to the console. The navigation example sends the values to a “toast” to be displayed on screen.
This is the minimum customisation of the javascript part of the apps. Integration, more fully, with the Appear2mee functionality can be seen in the AppNavigation.js file in the sample app. Note the apps are not completed yet as further native customisation in both iOS and android is required.
The iOS app needs a number of project customisations, capabilities and extensions.
The app requires a service extension, and a content extension. These components are linked together using an App Group, that allows files downloaded by the service extension, or the main app, to be shared with each of the components. This sharing allows files that have been downloaded in the main app or the service extension, to be use in the content extension to display the notification or to display the message in the app itself, if it was not displayed in the content extension.
A 2mee message app needs a number of capabilities set to work correctly. It firstly requires the push notification capability. Push notifications also require the app to do background processing, so that capability must also be selected too.
The main app, service extension, and content notification all require app group capabilities.
App groups are a way of sharing data between different apps and app services. App groups are defined in the your App Groups in Certificates, Identifiers and Profiles section of the Apple Developer Portal. App groups can also be created within Xcode itself in the Capabilities section of the project using the + button.
Your App, the Content extension, and the Service Extension must use the same group. The name of this group is passed to the Appear2mee SDK in custom code (shown below) in both the App and Service Extension and allows data and files to be passed from the Service Extension to the App and Content Extension. The demo app uses the Appear2meeConstants.h file to pass the share group name.
In order to link the App to the exchange it needs a Client ID and a secret key. These are generated in the 2mee Exchange (the same exchange Client ID and secret key are used in the android version).
Important: In order for the 2mee Exchange to connect to the App on a iOS device a production push certificate in p12 format is required by the exchange. See the 2mee Exchange Docs for details of accessing the exchange keys and how to upload the p12 certificate.
As the developer you will probably have to provide the push certificate. To generate a p12 certificate you need to access the Apple Developer Certificates, Identifiers & Profiles page, under iOS App ID Settings. Once you have generated and downloaded the certificate, import it to the Key Chain app on your mac, and then export in p12 format (with a password).
Android has its own push notification requirements which are covered later, below.
In any 2mee message app a connection to the 2mee Exchange is required. The exchange client id and secret key are generated on the 2mee exchange for each app administered on the exchange. If you are doing the exchange setup as well, see the 2mee Exchange Docs. The init method [RNAppear2mee initWithID:clientKey:usingAppGroup:] is used allow the app to communicate with the exchange and uses the app group to share files and data with extensions. This method is used in the Application Delegate, but there are a number of other changes in the AppDelegate as well, to allow push notifications.
First, since the app group is used by all three executables (the app, content extension and service extension) it is recommended the a .h file is used to store the value in the project file directory where it can easily be access.
Then in the existing AppDelegate.m file a number of changes are required. The easiest was to make those changes is to copy and paste from the example application provided.
First a number of imports are required,
And the AppDelegate is required to implement the UNUserNotificationCenterDelegate protocol.
In the AppDelegate application: didFinishLaunchingWithOptions: method the Appear2mee system is initialised and the AppDelegate is made assigned to the delegate of the user notification center.
The app delegate also need to implement the UNUserNotificationCenterDelegate protocol methods. See the example app to cut and paste these methods, they forward the calls to the RNAppear2mee and or the PushNotificationIOS framework.
A 2mee message app requires a service extension to process the push notification and also a content extension to display notifications when accessed by 3d touch. Each of these separate processes must be able to share the downloaded files. This is why the common app group is required. Files are written and read from a common shared area.
A service extension is used for mutable content remote push notification handling. The 2mee Exchange sends push notifications with a payload of data, which can include a urls of message content. The service extension attempts to download these files and optionally create an image attachment that is displayed in the notification. The Appear2mee SDK also copies files to a shared data area so the the app itself can access the messages to. To copy the file the Services Extension and App must use App Groups as discussed above.
The entry point to a service extension is the didReceiveNotificationRequest:request withContentHandler: method. To support the Appear2mee SDK the request.identifier must be stored. If the notification request has been sent from the 2mee Exchange, the [Appear2mee handleAppear2meeNotification:request:withContentHandler:usingAppGroup] class method will handle any file downloads and return true. If it is not a 2mee Exchange notification the method immediately returns false and the developer is free to handle the notification as required.
As the service extension is only allowed a limited amount of time, the download might not be completed, which means that thehandleAppear2meeNotification method can be timeout asynchronously by a system call to serviceExtensionTimeWillExpire. The download tasks used by this method need to be canceled and the request.identifier stored earlier is used by the [Appear2mee cancelDownloadForRequest:] method to identify which download tasks should be canceled.
All the code required for the service extension can be found in the iOS example app. It is recommended that this is copied to your own app.
The Service Extension must be linked to the Appear2mee XCFramework, The framework can be found in the project or within the RNAppear2mee folder within the Pdds project. It should be dragged to the frameworks and libraries section, it does not need to be embedded.
Important: Xcode can, when generating a service target, set the deployment target to higher than iOS 10. Normally you would want your service extension to work from iOS 10. Unless you test your app on a device with iOS 10 you could easily miss this error.
In order to link the library, the path to the framework must also be set in the service extension build settings. This is the path to the Appear2meeFramework folder in the node_modules.
The Service Extension target capabilities must include an App Group with the same group as used for the main app and shared in the Appear2meeConstants.h, so that the same file area is used to store and share common data and files.
Notifications that display complex content can use the default iOS display given when the user uses 3d touch (hard press). However, we can customise the way our notification content is displayed, using a notification extension. This allow us to display and play a face message (or image/animation/video) within the notification and stop/restart the message by touching the face/video. A content extension target should be generated in Xcode, then there are a number of steps required to adapt the extension for 2mee messages, but the sample app gives a fully working example that can be transfer easily to your own app. The content extension when running uses files that have been downloaded by the service extension or the app itself and stored in an App Group. The content extension, like the service extension and app, must be given access to this shared area. Using the shared files not only allows 2mee messages to be displayed in the app itself, if required, but also seems to be more reliable than using attachments, which can occasionally fail.
After the target is created the info.plist NSExtension entry should be edited. The UNNotificationExtensionCategory MUST be appear2meeNotificationCategory. This is the category that the service extension will direct all 2mee messages towards. Also, to enable user touch capabilities UNNotificationExtensionUserInteractionEnabled entry must be added, if not present, and set to YES. Lastly the UNNotificationExtensionInitialContentSizeRatio should be set to 0.6.
A content extension created by Xcode contains a storyboard. It is recommended that you replace that with the one in the sample project. The sample project storyboard contains a background image (UIImageView) and a custom UIView of type Appear2meeContentView. This view as able to display all the different types of content sent by the 2mee exchange, face messages, images, animations and videos.
The Content Extension is a separate process from the app and service extension, and uses a NotificationViewController. The code itself is very small as the real work is done in the Appear2meeContentView class that is a type of UIView in the storybook file. The entry point is the didReceiveNotification:] method. In this an instance of Appear2meeContentView is given the notification to display along with the NotificationViewController instance and the common App Group. Access to NotificationViewController which is an instance of UIViewController<UNNotificationContentExtension> allows the contentView to set the title on the “accept” action button or removed that button if a message has expired (in iOS 12).
Responses to the content extension notification are send to the UNNotificationContentExtension protocol didReceiveNotificationResponse:completionHandler:], and are passed the the contentView to process.
The Content Extension must be linked to the Appear2mee XCFramework. See the service extension section to see where to find the Appear2mee xcframework in the project, drag it in to Linked Frameworks section of the content extension target.
Important: Xcode can, when generating a content target, set the deployment target to higher than iOS 10. Normally you would want your content extension to work from iOS 10. Unless you test your app on a device with iOS 10 you could easily miss this error.
In order to link the library, the path to the framework must also be set in the in the content extension build settings, in the same way as the service extension. This is the path to the Appear2meeFramework folder in the node_modules.
The Content Extension target capabilities must include an App Group with the same group as used for the main app and shared in the Appear2meeConstants.h, so that the same file area is used to store and share common data and files.
☑ | Appear2mee SDK Check List |
App | |
☐ | Required Capabilities: Push Notification |
☐ | Required Capabilities: Background Modes, Remote Notifications |
☐ | Required Capabilities:App Groups, Create App Group and Assign |
☐ | Add App Group to Appear2meeContants.h, to share with Extensions |
☐ | Exchange Keys, ClientID and Key. Add to Appear2meeContants.h |
☐ | Appear2mee initWithID in application:didFinishLaunchingWithOptions |
Service Extension | |
☐ | Create a Service Extension (Note: there is only one per App) |
☐ | Required Capabilities:App Groups, Assign same group as App. |
☐ | Handle the Notification Request |
☐ | Handle the Time Will Expire method |
☐ | Link the Appear2mee XCFramework as library. |
Content Extension | |
☐ | Create a Content Extension (Note: there can be many per App). |
☐ | Required Capabilities:App Groups, Assign same group as App. |
☐ | Info.plist: Set UNNotificationExtensionCategory to appear2meeNotificationCategory |
☐ | Info.plist: Set UNNotificationExtensionInitialContentSizeRatio to 0.6 |
☐ | Info.plist: Set UNNotificationExtensionUserInteractionEnabled to YES |
☐ | Copy Demo MainInterface.storyboard to new Content Extension. |
☐ | Copy Demo NotificationViewController to new Content Extension. |
☐ | Link the Appear2mee XCFramework as library. |
The android customisation requires a number of important changes to the AndroidManifest.xml. These “activate” the services to receive push notifications and download media files required by these notifications. Refer to the sample android app in the android directory.
In android, messages are sent from the 2mee Exchange using push notifications. The notification includes the url/s of files that are required to display the notification. These files must be downloaded by the device in order to present the notification. When the firebase push notification is received an attempt is made to download any required files. If the message file cannot be downloaded a fallback text is “posted” as the notification. This fallback text is included in the notification and is set by your exchange user.
These messages are displayed initially as notification and in app as “dialogs”. Touching video/image notifications will give a larger view of the image/video. A video or sound can be paused/restarted by tapping on the middle of the image/video. Tapping on outside the middle will “accept” the message, and tapping on the X in at the top right corner will dismiss the large view, returning to the dialog.
Face messages appear within the app in developer selected positions dependant on the face type, see below for details. A touch on the face itself will “accept” the message a swipe anywhere else will dismiss the message. A double tap on the face will pause/restart the message.
A 2mee enabled message app uses a number of components that are included in the SDK but must be given permission to be used in the AndroidManifest.xml file. These are the Appear2meeNotificationActivity that is called when a notification is selected. An internal JobService that downloads files. A broadcast receiver that is used to trigger the local notification at the correct time. Lastly the firebase messaging service that handles both incoming firebase notifications and deviceToken events to trigger sending the deviceToken to the 2mee Exchange.
The appear2mee SDK itself comes as an aar module. This aar module is distributed with the react-native-appear2mee. It is a dependency of both react-native-appear2mee and the app itself. The aar does not need to be dependency of app directly as it is available via the the react-native-appear2mee module. The activities and services within the SDK can still (and must) be included in the app AndroidManifest. Note that, Android Studio is unable to “see” them and will colour them red, but when running the app will find them.
Note: The Appear2meeNotificationActivity uses an openGL View. Apps by default allow openGL views, but if you app has hardwareAccelerated set to false, you will need to set it to true either for the whole app or just the Appear2meeNotificationActivity activity, in your AndroidManifest.xml.
There are also a number of permissions that need to be included in the manifest.
See the demo app to copy paste to your app.
To use android api 31 as a target you will need to upgrade your gradle version to 7.x. This and the build tools for android 12 (api 31) use java 11. However as react-native (as of 0.67.3) is not fully able to handle Java 11, you will need to use compile options in your app gradle build file. Also the lint fails in the 0.67.3 version of react so you may also need to stop the abort on fail.
In order to link the App to the exchange it needs a Client ID and a secret key. These are generated in the 2mee Exchange (the same exchange Client ID and secret key are used in the iOS version).
In order for the 2mee Exchange to connect to the App on the device the firebase cloud messaging server key, and firebase cloud messenger sender id (project number in google-services.json) are required by the exchange. The exchange uses the server key to authorise sending push notifications and the sender id/project number is used to check that deviceTokens registered on the exchange are for the same project as the server key. See the 2mee Exchange Docs for details of how to add the server key and senderid. The project server key are found in your firebase settings for your project.
The Appear2mee SDK needs to be setup in the Application class. This is to ensure that SDK is setup when a notification is opened. React Native Android apps create a MainApplication class where the appear2mee initialisation should be performed.
The default notification icons are 2mee png icons. To replace these icons you will need to name at least one image in your res/mipmap*** resources appear2mee_notification_icon, for the notification icon. The status bar notification icon (which is normally white on transparent) is called appear2mee_notification_icon_small and should be included in your drawables. See an android icon maker to make this status bar icon.
The FirebaseMessagingService is used to both handle device tokens registration on the 2mee Exchange and also receiving then forwarding firebase messages. If you have not used the FirebaseMessagingService before you should read the documentation at https://firebase.google.com/docs/reference/android/com/google/firebase/messaging/FirebaseMessagingService.
Pay close attention to the manifest requirements and gradle build settings. A time of writing was classpath('com.google.gms:google-services:X.X.X'), added to the root build file check for latest version.
Also add the google services plugin, to the app gradle build file.
If you are not familiar with firebase then you should read the requirements for android setup at https://firebase.google.com/docs/android/setup. If you are setting up a new project you will need to add the google-services.json to your project. This is found in your firebase project settings.
The Appear2mee SDK uses the react-native-push-notification module, it has a simple overload of the RNPushNotificationListenerService the Appear2meeListenerService. The Appear2mee service will forward any messages that are not from the 2mee Exchange to the RNPushNotificationListenerService, so all your other notification will be handled as before. It is imported to remove/or not add the RNPushNotificationListenerService to AndroidManifest.
Apps that target Android 6.0 (API level 23) or higher are automatically enabled for Auto Backup. React native android apps be default (at the time of writing) set the android:allowBackup=“false”. If your app does require backup, steps must be taken to avoid backing up the device connection to the 2mee exchange. Some of the Appear2mee SDK app data should not be backed up. It includes the device token and device specific data connecting the device to the 2mee Exchange. If a new device uses a backup it can lead to two devices connected to the same device entry and potentially a clash of settings. The userID and tags are stored in a different sharepref, and will be backed up, as these are “actual” in app user preferences.
In order to avoid backing up incorrect data your app should use the option to define which preferences are backed up.
In resources a file res/xml/my_backup_rules.xml defines which data to exclude from backup.
This file and the application options should be included in your project.
☑ | Appear2mee SDK Check List |
App | |
☐ | Download firebase project google-services.json and settings |
☐ | Get Exchange Keys, ClientID and Key, for Appear2mee init. |
☐ | Appear2mee Services and Activities in AndroidManifest |
☐ | Required permissions in AndroidMainifest |
☐ | Add auto backup options to AndroidManifest, and exclude file to Resources |
☐ | Add appear2mee_notification_icon to resources (mipmap) |
☐ | Add appear2mee_notification_icon_small to resources (drawables) |
After completing the App setup and the service and content extensions, for iOS and google services and init for Android, the apps will be functional. There are other options that you might need to setup within the app.
Many apps are linked to a separate system and have some kind of user identity. The SDK allows the app to store a userID. The 2mee exchange can return reports based on a user supplied userID. This id should be a string and can be supplied after the init of the Appear2mee SDK using the react native method NativeModules.RNAppear2mee.registerUserID, which takes a string as an userID argument. If a userID is not supplied the device token is used as the userID. In the demo app AppNavigation.js there is a button [userID] that can be used to open a text dialog to input a userID. Normally the user ID will, if it is set at all, will come from a custom server backend associated with the app.
In order to customise face messages to an individual user, a tag system is used. This allows the developer to send tags to the exchange that are indicative of the content to be sent to a particular user. The 2mee Exchange uses the tags set to a corresponding deviceToken to determine which messages a device should be sent.
Tags can be set using internal logic, for example game level, previous activity etc. Alternatively tags can be sent to an individual device, by a custom scheme of the developers choosing, and should then be forward to the exchange via the tags system.
Tags are represented as a dictionary, and are stored using the NativeModules.RNAppear2mee. registerTags function. The tags that have already been stored can be retrieved using the NativeModules.RNAppear2mee.tags function. Which provides a callback with a dictionary of existing tags. For example,
Note that tags dictionary is saved as a whole, so you should call the tags function and add any new/delete any tag, then register the tags dictionary. That is to add a new tag, the original tags dictionary must be extended, then registered.
The Appear2mee SDK has a limited number of settings to change the appearance of notifications and the default text that appears in notifications. These customisations are set using a dictionary of values.
Default text are shown above. The “Play” option is only shown in iOS 11 or below, as touch in notifications was not available till iOS 12. The “OK” will be overridden by the payload sent by the exchange but only in iOS 12 and above.
The position of face messages can be altered, standard faces, without shoulders or torso can be displayed in any corner or the centre of the screen. If displayed in the centre of the screen a background is used. The color of this background is another of the defaults. By default it is white. But, of course can be set to clear or any other color. The position of face messages with shoulders or torso is restricted to bottom left or right corners. This is because these formats have a bottom edge which looks better against the edge of the screen. If there are issues in your screen layout centre can also be used.
In app notifications are displayed in a dialog. When displayed the screen is faded by a background view with a color. The default uses transparency so that the context can still be seen. The defaults can be changed as shown below. Colors are converted to a string using an Appear2mee helper method [Appear2mee rgba:]
The color of the face background when displayed in the centre of the screen can also be changed.
Notifications sounds are built into the SDK. But can be changed if required.
iOS Content Extension notifications background images are built into the SDK. But can be changed if required. Note that replacements backgrounds must be stored in the content extension bundle, not the app bundle, to be found.
The 2mee Exchange has an option to open an external webpage when a notification has been accepted. The default action is to not call the accept action, and to start the external browser with the address given. Where this default action is not wanted the setting Appear2mee.openExternalURLAutomatically should be set to “false”. It is then up to the developer to handle the key “__openExternalURL”.
The defaults are set using the Appear2mee.configure class method. These defaults are not stored so should always be set on app startup.
Appear2mee.configure(appear2meeDefaultSettings);
The developer may choose to allow users of the app to not receive messages form the exchange. Other permissions control the download of files (rich messages) or to receive them only when they are connected via WiFi. When file downloads are not permitted the messages are still received but the text uses the fallback text message configured at the exchange. The default setting are to allow messages with no restriction on the method of download.
Note: Once set permissions are stored by the Appear2mee SDK so that when the app is restarted the same permissions are set.
Note: The SDK will not restrict the use of WiFi for other tasks, in particular communications to the exchange will use 3G/4G networks. However these communication are small packets of data, normally in the region of a few tens of bytes.
The NativeModules.RNAppear2mee class has a number of methods for retrieving setting and setting them. The retrievals return a boolean in a callback method and setting use a boolean argument.
The function servicePermission is used to set whether the 2mee exchange should send any messages to the device. Of course the device has to report this state to the exchange before it can take effect. Alerts that are in transit or queued will still arrive and will be displayed.
The function hasServicePermission is used to determine services permission State.
The RNAppear2mee function downloadPermission is used to set whether rich message content is download.
This method does not stop the alerts, but alerts will use a fallback text from the exchange.
The RNAppear2mee function hasDownloadPermission is used to determine if permission is given for downloads.
The RNAppear2mee function wifiOnlyPermission is used to set the Wifi permission. The default is false, that is any method of download is permitted.
The function hasWifiOnlyPermission is used to determine the state of WifiOnly permission.
In iOS, the media player sounds can heard even when the hardware mute switch is selected to mute. By default messages sound will play when the mute switch is silencing notification sounds. The RNAppear2mee function soundOnMutePermission allows the default setting to be changed.
The state of the mute setting can be found using the hasSoundOnMutePermission method.
NOTE: The soundOnMutePermission is a global setting. That is it will affect any of your apps media, and any of your apps setting can override this setting too.
The permission toggles the AVAudioSession category between AVAudioSessionCategoryPlayback and AVAudioSessionCategoryAmbient.
Two of the buttons simulate receiving a push notification, they actually send local notifications. They do not test the service extension or the firebase setup in Android, as that needs a push notification to be triggered.
