Mobile SDK

Overview

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. We will also make this SDK available in other platforms in the mid term. Keep in mind that we try to keep both SDK 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.


How it works

The SDK handles all the complexities behind push notifications and LBSs, exposing a very simple interface to your mobile application. 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.


Registration

The first time the SDK enabled app is run it will register the device with the Campaign Manager. What this does is associate the Unique Device ID (the IDFA for iOS or the deviceID for Android) with the mobile number after it has been confirmed via SMS. The Campaign Manager maintains a mapping of mobile numbers to Unique Device IDs that will be updated if the user moves his number to a different device. When sending a broadcast or any other campaign the Campaign Manager translates the mobile number into the Unique ID and delivers the notification.

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.