===== Android Studio Integration Manual ======

=== Notes ===

Please review the [[sdkoverview|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 ===

  *  [[http://developer.android.com/sdk/index.html|Android Studio]]
  *  [[http://ogangi.com/~jtorres/AndroidStudioGuide/messangisdk.aar|MessangiSDK]]

=== Configuration ===

== Create or Open Project in Android Studio ==

== Add Messangi Library == 
[[http://ogangi.com/~jtorres/AndroidStudioGuide/vid/addModule.mp4|Video]]
  - Download Messangi Library
  - Go to File > New > New Module
  - Select "Import JAR/AAR Package" then "next"
  - Click the button "..." next to the "file name" field. Select the file **messangiSDK.aar** from the directory you downloaded it and click “Finish”
  - Wait Gradle synchronize.

== Add Dependencies == 
[[http://ogangi.com/~jtorres/AndroidStudioGuide/vid/addDependencies.mp4|Video]]
  - Go to “Open Module Settings”
  - Select the project and go to the tab “Dependencies”
  - If MessangiSDK is not a dependency, add it by clicking on “+”, select “module” and “MessangiSDK”.
  - Currently you have to manually add dependencies for MessangiSDK, the Gradle will not automatically add it. Go to “Gradle Scripts” > “build.gradle(Module:—projectName—)”
  - Add the lines below in the section dependencies before the line “compile project(‘:messangisdk’)”
   
    <code>
        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'
    </code>

== Manifest ==

1. Open **AndroidManifest.xml** and add the following lines:
  
<code>
  <permission
      android:name="${applicationId}.permission.C2D_MESSAGE"
      android:protectionLevel="signature" />
  <uses-permission
      android:name="${applicationId}.permission.C2D_MESSAGE" />
</code>

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)

<code>
  <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>
</code>

== 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:

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

4. Add this methods **onGeofenceUpdate**, **onBeaconUpdate** ,**updateFencesStatus**, **onLocationChange** and **pushReceived**, to interact with Messangi.
<code>
    @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 .
    }
</code>

== Configure Messangi SDK ==
1. Modify the method **onCreate**, adding **Messangi** credentials.
<code>
    @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
        //..
    }
</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

<code>
    @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();
    }
</code>

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:
\\ \\ 

<code>
Messangi.getInstance().logEvent(this, "EVENT_TYPE", "EXTRA_INFO");
</code>

Please refer to [[Analytics Overview]] for more information on events and dashboards.
=== Version ===
Version of the guide 1.0