The Mobile SDK is the communication layer between your application and the Campaign Manager, it handles all the incoming messages and notifies about geographical events with the smartphone.

We have two versions for this SDK, covering two of the most populars smartphone's operating systems: Android and iOS. Keep in mind that we try to keep both SDKs as similar as each OS allow us.

The SDK will help the developer to integrate easily with the Campaign Manager by providing a simple API to interact with the tool.

The first time a SDK enabled app is run it will register the device with the Campaign Manager. This process stores the Unique Device ID (self generated by SDK) with the User ID (mobile number, email address or otherwise you consider) in the internal database. The Campaign Manager maintains a mapping of User IDs to Unique Device IDs that will be updated if the user moves his User ID to a different device. When sending a broadcast or any other campaign, the Campaign Manager translates the User ID into the Unique ID and delivers the notification for every device registered with such User ID.

The registration process works with the following steps:

1. The device app must ask for subscription to Google / Apple Push network
2. Google / Apple push network generates the unique token for device
3. The device app must then use the push token assigned and a deviceId (auto generated by SDK) to register such device in the platform
4. Messangi platform answers with successfull registration of the device
5. Using a user id (email, mobile number or otherwise), registered using SDK methods, the user can be registered associated with device id
6. Messangi platform answers with successfull registration of the user

If the app developer has decided not to use mobile numbers then the Unique Device ID can be used via the REST API to deliver push notifications to single users. Even if the users do not register their mobile numbers with the SDK they will still be able to receive Geopush, beacon and geofence related messages.

The SDK handles all the complexities behind push notifications and Location Based Services, exposing a very simple interface to your mobile application. You might send push notifications either directly or triggered by LBS.

Messangi Push Notifications work slightly different than common app pushes.

1. First you use Campaign Manager (GUI or API) to order the push notifications delivery to a list of recipients
2. This signal is sent to Google / Apple push network
3. Then that network tells to devices that some information is available for them from Messangi
4. Once those devices get the signal push they ask directly to Messangi Platform for pending messages
5. Finally the platform answers with the full message sent and any other message queued.

This communication diagram shows the overall process:

New Geofences or iBeacons are delivered silently to your app, and the SDK starts listening for them automatically using the internal iOS or Android mechanisms. Once an event is raised (the user entered a Geofence, an iBeacon is detected, etc) the SDK notifies the backend platform via the REST API and an internal trigger is fired. This trigger may launch an existing campaign in which case a response is sent as a Messangi Push Notification to your mobile app. Your app will receive the full content of the Push Notification after it’s been completely retrieved from the server. Geofences or iBeacons created using either the Campaign Manager or the REST API are delivered automatically to all your users and are managed internally by the SDK.

Please note that Geofences and iBeacons are handled as Campaign Triggers internally by the SDK. This means that when a Geofence is triggered a call to the REST API will always be made, and depending on the campaign configuration the Campaign Manager will send a Push Notification, trigger a callback or activate a new campaign. Take a look at the following diagram:

Step by step behaviour

1. The user enters a Geofence or iBeacon region. This will internally fire a silent trigger to the REST API.
2. The REST API will handle the trigger in two ways:
   • (2a) A callback is made to an external platform (if a callback is configured)
   • (2b) A callback is made to the Campaign Manager
3. Depending on the Campaign Manager configuration a campaign is activated and a message is delivered to the mobile app via the campaign channel. A campaign may decide not to send a notification to the user but just capture the trigger as an event for analysis or use in a future campaign.

When the Mobile SDK receives a push notification it also checks for any pending messages that may have been delivered but that were not received as traditional Push Notifications (the phone was turned off, it did not have any connectivity or Apple’s or Google’s platform jut did not deliver it). Those messages are retrieved automatically and are handled to your app using the same delegate or listener. From your app’s point of view everything arrives from a single entry point, whether Apple or Google delivered the Push Notification immediately or the Messangi SDK found pending messages in the platform. A metadata field is present on all messages received by your application indicating the trigger that fired the campaign (an iBeacon, Geofence, etc).

All the messages received by the SDK are stored in the Inbox DB, from where they can be retrieved at any point in time.