Notes

Please review the SDK Overview for information on how the SDK connects the mobile app with the Campaign Manager.

Android Studio v1.4.1 When this guide was created the process to import libraries in Android Studio had some bugs.

Messangi is currently used as a local library, so the setup is a bit more tedious than it will be in future releases.

Downloads

Configuration

Create or Open Project in Android Studio
Add Messangi Library

Video

  1. Download Messangi Library
  2. Go to File > New > New Module
  3. Select “Import JAR/AAR Package” then “next”
  4. Click the button “…” next to the “file name” field. Select the file messangiSDK.aar from the directory you downloaded it and click “Finish”
  5. Wait Gradle synchronize.
Add Dependencies

Video

  1. Go to “Open Module Settings”
  2. Select the project and go to the tab “Dependencies”
  3. If MessangiSDK is not a dependency, add it by clicking on “+”, select “module” and “MessangiSDK”.
  4. Currently you have to manually add dependencies for MessangiSDK, the Gradle will not automatically add it. Go to “Gradle Scripts” > “build.gradle(Module:—projectName—)”
  5. Add the lines below in the section dependencies before the line “compile project(‘:messangisdk’)”
        compile 'com.google.android.gms:play-services:8.1.0'
        compile 'org.altbeacon:android-beacon-library:2.3.5'
        compile 'commons-codec:commons-codec:1.10'
        compile 'com.google.code.gson:gson:2.3.1'
    
Manifest

1. Open AndroidManifest.xml and add the following lines:

  <permission
      android:name="${applicationId}.permission.C2D_MESSAGE"
      android:protectionLevel="signature" />
  <uses-permission
      android:name="${applicationId}.permission.C2D_MESSAGE" />

Please note that you should have an applicationId in the gradle defaultConfig (this is added automatically in Android Studio)

2. If you are using a broadcast receiver to receive push notifications while your application is not running, you must register to receive the com.ogangi.messangi.android.sdk.PUSH_NOTIFICATION action (Optional)

  <receiver
    android:name="com.ogangi.messangi.android.demo.SimpleNotificationReceiver"
    android:enabled="true">
    <intent-filter>
      <action android:name="com.ogangi.messangi.android.sdk.PUSH_NOTIFICATION" />
    </intent-filter>
  </receiver>
Add Interaction with MessangiSDK

1. Open MainActivity.java and add this imports import

  <code>
    import com.ogangi.messangi.android.sdk.*;
  </code>

2. Implement MessangiListener in MainActivity:

  <code>
    public class MainActivity extends Activity implements MessangiListener {
      ...
    }
  </code>

3. Once the initialization process has been completed the SDK will call the postInit() method of all the MessangiListeners that were registered. Use that method to complete your application’s launch process:

    @Override
    public void postInit() {
        runOnUiThread(new Runnable() {
            public void run() {
                // Initialize your application
                ...
            }
        });
    }

4. Add this methods onGeofenceUpdate, onBeaconUpdate ,updateFencesStatus, onLocationChange and pushReceived, to interact with Messangi.

    @Override
    public void onLocationChange(Location location) {
        // Use this method to handle any change in location.
    }
    @Override
    public void updateFencesStatus(List<Geofence> geofences, int geofenceEvent, Location location) {
        // Use this method to handle any changes in the Geofences status. This is an
        // informational method that can be used to update any maps or other views
        // showing the geofences. The location parameter contains the triger location
    }
    @Override
    public void pushReceived(MessageVO messageVO) {
        // This method will be called every time the user receives a push notification
        // via Messangi.
        // Use this method to display the content of the notification.
    }
    @Override
    public void onGeofenceUpdate(String type, String geoFenceID) {
        // This method will be called every time the user receive a Geofence
        // create, update or delete event.
        // NOT when arrive a Notification of geofence Enter or Exit .
    }
    @Override
    public void onBeaconUpdate(String type, String beaconID) {
        // This method will be called every time the user receive a Beacon
        // create, update or delete event.
        // NOT when arrive a Notification of beacon Enter or Exit .
    }
Configure Messangi SDK

1. Modify the method onCreate, adding Messangi credentials.

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // Messangi Credentials
        Messangi.getInstance().setAppName(**App Name**);
        Messangi.getInstance().setClientId(**Client ID**);
        Messangi.getInstance().setApiClientPrivateKey(**Private Key**);
        // GCM Credentials
        Messangi.getInstance().setGcmApiKey(**Google Cloud Messaging API Key**);
        Messangi.getInstance().setGcmProjectId(**Project ID**);
        // Subscription manager
        Messangi.getInstance().setSubscriptionURL(**SubscriptionURL**);
        Messangi.getInstance().setSubscriptionInstanceId(**SubscriptionInstanceId**);
        Messangi.getInstance().init(this);
        Messangi.getInstance().addMessangiListener(this);
        Messangi.getInstance().registerDialog(this, this);
        //Rest of your code
        //..
    }

Add the parameters provided by Ogangi: App Name, Client ID and Private Key. To receive push notifications, you must also add Google Cloud Messaging API Key and Project ID, if you use Subscription List then you should also add SubscriptionURL and SubscriptionInstanceId.

Messangi can take care of the entire registration process calling Messangi.getInstance().registerDialog(this, this), if you want to manage your own login window then do not add that line.

2. (Optional) Use the Android Lifecycle onStart, onResume and onPause to handle MessangiService

    @Override
    protected void onStart() {
        super.onStart();
        Messangi.getInstance().init(this);
    }
    @Override
        protected void onPause() {
        Messangi.getInstance().unBindService();
        super.onPause();
    }
    @Override
    protected void onResume() {
        super.onResume();
        Messangi.getInstance().bindService();
    }

You could invoke the startService, unbindService and bindService methods elsewhere, but we recommend these.

logEvent Facility

Events can be generated in the Analytics platform via the logEvent facility. You only need to provide the EVENT_TYPE and EXTRA_INFO. Please refer to Data Structure, Events, Location, Aggregation and Dashboard for more information:

Messangi.getInstance().logEvent(this, "EVENT_TYPE", "EXTRA_INFO");

Please refer to Analytics Overview for more information on events and dashboards.

Version

Version of the guide 1.0