iOS SDK
This page gives you all of the documentation needed to integrate the 2mee iOS 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 iOS SDK. This page will be updated with any changes or new features added to the SDK.
Last updated
Integration of the Appear2mee SDK into a Simple iOS App
This document will guide you through the example iOS Appear2meeSimple app provided in the 2mee iOS SDK showing how Facee Messaging and rich text integration is achieved. This document refers to the sample Appear2meeSimple App. The sample code can be downloaded from https://www.2mee.com/SDK/Appear2meeSDKiOS.zip. Copy the link into a separate tab if it does not go to the page.
Messages are sent from the 2mee Platform 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 push is scheduled, rather than send “now”, a content-available (silent) notification is sent first with the urls required, to give two opportunities of downloading the files. The main alert push notification will also attempt to download any files that are not already available. If the message file is not available in the time allotted by iOS a fallback text is “posted” as the notification. This fallback text is set by your platform user in the 2mee Exchange.
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.
A 2mee enabled message app uses a number of components. The app itself, 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, and in the main app to display the message if it was not displayed in the content extension.
The App, Service and Content Extension all use the Appear2mee.framework. The easier way to install the framework is via cocoa pods. It can be a bit tricky to get pods to link con- tents and service extensions with the same dynamic library so is recommended you use the pattern below. For more detail on use cocoa pods see https://guides.cocoapods.org/.
By placing the pod ‘Appear2meeSDK' outside the targets it becomes common to all target. Where an individual target requires more pods they can be added inside the specific target. Note also that the Appear2meeSDK pod needs to use source 'https://bitbucket.org/2meeltd/appear2mee-specs.git' to find the pod spec file and that because we have added a source we need to add back the default source ‘https://github.com/CocoaPods/Specs.git'.
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.
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 Bridge2Mee SDK in both the App and Service Extension and allows data and files to be passed from the Service Extension to the App. The demo app uses the Appear2meeConstants.h file to pass the share group name.
In order to link the App to the 2mee platform it needs a Client ID and a secret key. These are generated in the 2mee platform. In order for the platform to connect to the App on the device a production push certificate in p12 format is required by the platform. See the 2mee Platform Docs for details of accessing the platform 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).
In any 2mee face message app a connection to the 2mee Platform is required. The Platform client id and secret key are generated on the 2mee Platform for each app administered. If you are doing the Platform setup as well, see the 2mee Platform Docs. The init method [Appear2mee initWithID:clientKey: serverIP:usingAppGroup:] is used allow the app to communicate with the platform and uses the app group to share files and data with extensions.
Note: All Appear2mee methods are class methods.
A 2mee message app also requires at least a service extension to process the push notification and preferably 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. A common share group is used for this purpose. Files are written and read from a common shared area. The app group is generated by the developer within Xcode. In the example app this name is defined in the Appear2meeConstants.h file and is included in each of the separate targets code.
In the demo app we also set a BOOL USE_NOTIFICATION_CENTER_WHEN_ACTIVE to select how notifications are dealt with when the app is in the foreground. In that app we use an NSSwitch to change this value if required.
To allow notifications the app user needs to give permission for notifications, this is done in the [self requestPermissionForNotifications] method.
Important: If permission is not granted for notifications the app cannot receive messages from the platform.
An iOS app requests notification permission using the UNUserNotificationCenter. iOS 12 has introduced a new option of provisional authorisation. In this mode the user will receive notifications without sound in the notification centre. These notifications allow the user to decide when the access the notification how to treat all notifications from your app. It is up to you the developer if you want to use this method, or for the user to have a dialog box presented asking for notification permission. Calling the UNUserNotificationCenter requestAuthorizationWithOptions: completionHandler: method requests permission. If permission is granted the Appear2mee class method addAppear2meeNotificationCategory should be called to setup UNNotificationCategory for Appear2mee notifications. If the app has other UNNotificationCategory to set, it should do those first, as the addAppear2meeNotificationCategory adds Appear2mee categories to the existing set.
If permission is granted then iOS will call, sometime in the future, the - (void)application: didRegisterForRemoteNotificationsWithDeviceToken: method. In this method the deviceToken needs to be sent to the 2mee Platform using the [Appear2mee registerDeviceToken] method. In the example app we also log the device token as a string in the format iOS requires to send a push notification. Later we will see that we can use this to send test notifications without using the 2mee Platform.
Anytime the - (void)application: didRegisterForRemoteNotificationsWithDeviceToken: method is called by iOS the [Appear2mee registerDeviceToken:] class method should be called, as deviceTokens can be changed or invalidate and the 2mee Platform needs to have the latest version even it it appears to the app that it is unchanged. This is particularly important in development as multiple installs of production and development versions can lead to tokens being invalidated and then revalidated at a future install.
Notifications are sent by the 2mee Platform to your app. Your app needs to process these notifications using a service extension, which will be discussed later. After the service extension has processed the push notification they can be passed to the main app, if it is active. If the app it is not active, but is in the background, or not launched, notifications are sent to the notification center. When the user has responded to a notification in the notification center the app receives the notification response.
Receiving Notifications when in Foreground
When the application is in the foreground the app can choose to display incoming notifications in the notification center or directly within the app. It is recommended that you direct these notifications to the notification center, to avoid the user being surprised by a popup dialog. In the sample app a switch within the app controls this behaviour.
The hander checks if the notification comes from the Platform, using the call method [Appear2mee isAppear2meeNotification], which will return true if the payload matches a 2mee Platform payload. The recommended step is just to then return the completion handler with the presentation options. If however you wish to display the notification in the app the class method [Appear2mee displayNotification: withAcceptAction: withDismissAction:] should be called with the notification and blocks to be executed if the user accepts or dismisses the dialog that will be presented. These blocks will be called with a dictionary of key/values that were attached to the notification in the 2mee Platform. Typically they can be used to perform some action based on the values present. For example, move to a page on the app {“page”:”sports/mens/shorts”}.
When the user interacts with the notification it can be dismissed or “accepted”. These actions can causes the app to come into the foreground if the notification was accepted or process in the background, where the notification was dismissed. The notification response calls the UNUserNotificationCenterDelegate method userNotificationCenter: didReceiveNotificationResponse:withCompletionHandler:, Typically this delegate is the ApplicationDelegate, in the sample at this is where it is implemented. This method is used to direct the response of the app to the notification action.
The Appear2mee SDK is able to handle the notification response using the [Appear2mee didReceiveNotificationResponse:withAcceptAction: withDismissAction:] returning true if the notification response was from a 2mee notification and false, if some other notification type that needs to be handled differently. This method handles the various possible responses to 2mee notification.
If the user has shown the notification using 3d touch then the response for the notification category will be an accept or dismiss action and the appropriate dismiss for accept action block will be called. If however the user has dismissed the notification with a swipe delete or a tap outside to face area, the dismiss action block is called. A face message will also be dismissed when it ends playing after the kAppear2meeFaceAlertDismissTime, which defaults to 5 seconds. If the notification was touched to accept, then the user has not seen the full message, even a text message may have been truncated, and a dialog will be shown with the message. Images/Animations/Videos are shown with a simple popup dialog with dismiss and accept buttons. A face message is shown with a popover where a swipe action or tap outside the face will be a dismiss and a touch on the face will be an accept. These “dialog” responses will call the appropriate dismiss or accept action block.
Note: Notifications can be cleared in the notification center, in which case the app does not get any response.
The class method [Appear2mee didReceiveNotificationResponse:withAcceptAction: withDismissAction:] is called with the notification response and the blocks to be executed if the user has/does accept or dismiss the notification. These blocks will be called with a dictionary of key/values that were attached to the notification in the 2mee Platform. Typically they can be used to perform some action based on the values present. For example, move to a page on the app {“page”:”sports/mens/shorts”}.
In order to customise the actions taken to a UUNotificationResponse the response object can be tested to see if it is indeed an Appear2mee message then actions can be performed before calling the Appear2mee didReceiveNotificationResponse: withAcceptAction: withDismissAction: method. For example provide a custom overlay. It is also possible to customise the action based on any key value pair that the 2mee Exchange has attached to the message.
The 2mee Platform can also send silent notification, these too have to be processed by the Appear2mee SDK. Silent push notifications are handled in the app delegate application:didReceiveRemoteNotification:fetchCompletionHandler. Not all notifications may relate to 2mee messages. The class method [Appear2mee didReceiveRemoteNotification:fetchCompletionHandler:] should be called to determine if the Appear2mee SDK has handled the incoming notification. If it is not a Appear2mee related notification the method will return false and pass control back, to allow the developer to handle the notification. If the method returns true the notification has been fully processed and the fetchCompletionHandler has already been called with thew appropriate argument.
The App must be linked to the Appear2mee Framework as an embedded binary.
A service extension is used for mutable content remote push notification handling. The 2mee Platform 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 that 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 Platform, the [Appear2mee handleAppear2meeNotification:request:withContentHandler:usingAppGroup] class method will handle any file downloads and return true. If it is not a Platform 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.
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 to adapting 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 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 too. 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 platform, 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 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 to the contentView to process.
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.
After completing the App setup and the service and content extensions the app 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 platform 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 class method [Appear2mee registerUserID:]. If a userID is not supplied the device token is used as the userID. In the demo app there is a button [userID] that can be used to open a text dialog to input a userID.
In order to customise face messages to an individual user, a tag system is used. This allows the developer to send tags to the platform that are indicative of the content to be sent to a particular user. The 2mee platform 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 platform via the tags system.
Tags are represented as a dictionary, and are stored using the Appear2mee class method, registerTags:. The tags that have already been stored can be retrieved using the Appear2mee class method, tags; For example,
Note that tags dictionary is saved as a whole. To add a new tag, the original tags dictionary must be extended, then registered.
The SDK also allows the "pulling" of named messages from the 2mee Exchange. Currently only holocapsule messages (these are face videos) can be displayed in app. In order to retrieve a message the Appear2mee getMessage: method is used. A callback is called when the message is ready to display or has failed. If the message item is not null it can then be displayed.
The displayMessage method uses the same callbacks actions for "accept" and "dismiss" as notifications.
The 2mee Exchange can send notifications based on the users last recorded location. In order to send the device location to the exchange some setup is required, if this is not done no location data is sent.
In the application project info section the setting NSLocationAlwaysAndWhenInUseUsageDescription and NSLocationWhenInUseUsageDescription are required. If these two fields are completed the Appear2mee will automatically ask the users for location permissions and use the level of permission the user gives. Without these setting location data will not be available to sent to the 2mee exchange.
The Appear2mee SDK has a limited number of settings to change the appearance of notifications and the default text that appears notification. These notifications 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 platform 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.
The colour of the face background when displayed in the centre of the screen can also be changed.
A face notification will automatically dismiss with a delay of kAppear2meeFaceAlertDismissTime, after play is finished. If a negative value is used the will not be dismissed automatically.
Notifications sounds are built into the SDK. But can be changed if required.
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 defaults are set using the [Appear2mee defaultSettings:] class method. These defaults are not stored so should always be set on app startup.
[Appear2mee defaultSettings:appear2meeDefaultSettings];
The developer may choose to allow users of the app to not receive messages form the platform. 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 platform. 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 itself to using only WiFi for other tasks, in particular communications to the platform will use 3G/4G networks. However these communication are small packets of data, normally in the region of a few tens of bytes.
The Appear2mee class method servicePermission is used to set whether the 2mee platform should send any messages to the device. Of course the device has to report this state to the platform before it can take effect. Alerts that are in transit or queued will still arrive and will be displayed.
+ (void) servicePermission: (BOOL) allowService;
The Appear2mee class method,
(BOOL) hasServicePermission;
is used to determine services permission State.
The Appear2mee class method downloadPermission is used to set whether rich message content is download.
(void) downloadPermission: (BOOL) allowDownload;
This method does not stop the alerts, but alerts will use a fallback text from the platform.
The Appear2mee class method,
+(BOOL) hasDownloadPermission;
is used to determine if permission is given for downloads.
The class method,
(void) WifiOnlyPermission: (BOOL) onlyWifi;
is used to set the Wifi permission. The default is false, that is any method of download is permitted. The method
(BOOL) 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 method soundOnMutePermission: allows the default setting to be changed.
(void) soundOnMutePermission: (BOOL) allowSound;
The state of the mute setting can be found using the hasSoundOnMutePermission method.
+ (BOOL) hasSoundOnMutePermission;
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.
The Appear2mee SDK can be used with multiple notification service providers. The method of doing this can be found in the document above but are summerised here as well.
Requesting permission, the SDK provides a method for adding the addAppear2meeNotificationCategory. This method should be used after any other categories have been added, as some other provider my not keep existing categories when they set their own categories.
Responding to notifications in the foreground, The method isAppear2meeNotification: will return true if the notification is from the 2mee Exchange.
Similarly handling silent notifications uses a method didReceiveRemoteNotification: fetchCompletionHandler: which will return false if the notification is not from the 2mee Exchange and can then be handled by other providers.
When notification responses are received the SDK again has a method didReceiveNotificationResponse: withAcceptAction:withDismissAction:, which will detect a 2mee Exchange notification and will return false if another notification provider has send the notification.
The Appear2mee service extension integration has method handleAppear2meeNotificationContent: request:withContentHandler:usingAppGroup: that will return false if the notification is not from the 2mee Exchange, allowing mutable notifications from other providers to be handled.
The content extension is dedicated to the Appear2mee SDK and 2mee Exchange notification content. Other providers will or can use a different content notification extension that is triggered by the service extension code of the other provider.
App | |
☐ | Create/Modify Pod File. |
☐ | 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 |
☐ | Platform Keys, ClientID and Key. Add to Appear2meeContants.h |
☐ | Request Notification Permission method, addAppear2meeNotificationCategory. |
☐ | Register deviceToken method |
☐ | Handle Notifications when App is in foreground |
☐ | Respond to notifications responses |
☐ | Handle Silent Notifications |
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 |
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 UNNotificationExtensionCategoryto 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. |
