Install the SDK

Welcome to the mTraction Android PhoneGap SDK Integration Section. Our SDK provides developers the flexibility to choose and integrate one or more components based on their requirements.

Download the latest Android Phonegap SDK from the link below:

 mTraction Android Phonegap SDK

Note: Please refer to the Android SDK Phonegap Change log for details about the changes/upgrades on the latest SDK version from previous versions.

Phonegap SDK  should contain the following files:

  1. MTractionSDK.jar : This is the SDK library for integration in the application.
  2. MTractionSingleInstallReceiver.java : This file is provided to extend/implement the base class of the MTractionDownloadTracker.java
  3. MTractionMultipleInstallReceivers.java: This file is provided to listen more than one receiver at a time.
  4. MTractionPushReceiver.java
  5. MTractionApplication.java
  6. MTractionSDKTracker.java
  7. mTractionData.js
  8. mTractionTracker.js

The step-by-step integration process has been described in detail in the coming sections.

  1. Basic Integration Settings
  2. Installs Tracking
  3. App Session Tracking (Optional)
  4. In App Events Integration (Optional)
  5. CRM Integration - Android SDK

1. Basic Integration Settings

    

  1. Add the MTractionSDK.jar to your project’s lib folder as shown in the image below. 

    2. 

  2. 

     Add the MTractionSDKTracker.java, MTractionApplication.java,MTractionSingleInstallReceiver.java to your project’s src/”application package name” folder as shown in the image below.
    

    

    3. 

  3. 

     Followed by adding the www/js/mTractionData.js,mTractionTracker.js, to your project’s assets/www/js folder as shown in image.
    

    

    4. 

  4. 

    Followed by adding the feature tag to your project’s res/xml/config.xml file as shown in image.
    

    

    <feature name="MTractionSDKTracker">
   <param name="android-package" value="package name.MTractionSDKTracker" />
</feature>
    

    Followed by adding the script tag to your project’s www/index.html file.
    

    <script type="text/javascript" src="js/mTractionData.js"></script>
<script type="text/javascript" src="js/mTractionTracker.js"></script>


    

    

    5. 

  5. Open the AndroidManifest.xml file in your project and add the following: 
    Permission to access Internet and Network State. 
    <uses-permission android:name=”android.permission.INTERNET” />
<uses-permission android:name=”android.permission.ACCESS_NETWORK_STATE”/>
    It is optional permission if IMEI number is required. 
    Permission to Phone State 
    android:name=”android.permission.READ_PHONE_STATE” />;
    

    6. 

  6. Put the following lines of code in the first place your app run. We Recommend to place it in the onCreate() method of your application class. Either use MTractionApplication.java. and specify the MTractionApplication class name in your AndroidManifest.xml.

    <MTractionDownloadTracker mTractionDownloadTracker=new MTractionDownloadTracker();
mTractionDownloadTracker.trackDownload(getApplicationContext(),null);/>
    

    7. 

  7. To enable “DEBUG” logs, the following setting should be enabled. * Please ensure that the “mt_DebugMode” should be set to “false” before going live. 
    <application>
// Other Settings
<meta-data
android:name=” mt_DebugMode ”
android:value=”true” />
</application>
         

    8. 

  8. Add google-play-services_lib dependency project into your project Properties. 
    For Example : 
    

    9. 

  9. Add google_play_services_version in Project’s Manifest file inside application tag.. 
    <application>
// Other Settings
<meta-data
android:name=”com.google.android.gms.version”
android:value=”@integer/google_play_services_version” />
</application>
         

    10. 

2. Installs Tracking
    

  1. Open the AndroidManifest.xml file in your project and add the following RECEIVER settings. . 
    <receiver android:name=”.MTractionSingleInstallReceiver” android:exported=”true”>
<intent-filter>
<action android:name=”com.android.vending.INSTALL_REFERRER” />
</intent-filter>
</receiver>
         

    2. 

  2. Do the following settings in the AndroidManifest.xml under the Application section. The App_Token is provided to you as a part of the Application Registration process on the mTraction Platform. 
    <application>
// Other Settings
<meta-data
android:name=”appToken”
android:value=”App_Token”/>
</application>
         

    3. 

3. App Session Tracking (Optional)
Note: App Session implementation is optional for your Application. However, for Active Sessions and Session duration related data - this needs to be configured in your Application. Also note that this can generate a lot of traffic and hence cost if the request is large.
The Standard Solution is supported by most of the applications and works in a manner that lets the SDK listen to and track the various state changes that happens inside the Application (For example: App moving to foreground/background). Please follow the below steps:                                                                                                                                                                    
    

  1. If you don't have a custom Application class, then keep MTractionApplication.java in src folder of your application and specify the name in your AndroidManifest.xml as follows. 
    <application>
 android:name=".MTractionApplication">
     
    2. 

  2. Add google_play_services_version in Project’s Manifest file inside Application tag.  Import the MTractionActivityLifecycleCallbacks package. 
    import com.mtraction.mtractioninapptracker.MTractionActivityLifecycleCallbacks;
         

    3. 

  3. Register MTractionActivityLifecycleCallbacks. 

    public void onCreate()
{
 super.onCreate();
 registerActivityLifecycleCallbacks(
          new MTractionActivityLifecycleCallbacks(this));
}
    

    4. 


4. In App Events (Optional) 



    

  • At this stage, you might be interested in implementing certain In App events that needs to be tracked in order to measure your Application’s User Engagement after being installed. We have provided a list of generic events that you may need to implement depending on its necessity to your Application. Please follow the documentation (with examples) to implement them on your Application: Generic In App Events Setup

    • 

  • We have also provided sets of predefined In App events along with their respective keys setup (with example usage) based on the Industry or Vertical your Application is associated with. Please refer to the link to the various Vertical based Events integration guides: Vertical Specific Events Setup Guides

    • 



5. CRM Integration - Android SDK
    

  • 
Configure Push Notification:

    Call getNotificationData() method in your index.html/js. This method register the callback functionality for getting “Push Notification” data(when app is in background). 
    Note: We recommend to call getNotificationData() method in onDeviceReady() method in index.html/js. 
    Example: Call getNotificationData() method for getting notification data. 
    <script type=”text/javascript”>
function onDeviceReady() {
MTractionSDKTracker.getNotificationData();
<script>
    

    Setting up the Push Notification Handlers
    

              Application State : In-Active/Background   
    

      

    •  When a push notification is received while the application is not in the foreground, it is displayed in the Android Notification Bar.
      • 

    •  When we click on push notification massage ,and notification data can be handled by onPushNotificationBackgroundCallBack() method in the mtractiontracker.js file. 
      Application State : Active/Foreground

      • 

    • If the notification is received while the app is active, it is up to the app to handle it. To do so, the call came into onPushNotificationForegroundCallBack() method in the mtractiontracker.js file. Also developer can set custom/own message box in this method. 
      Custom Configuration setting for Push Notification: 
      trackMTractionNotificationConfigurator
:function(soundFileName,iconName,isEnableSound,isVibrateEnable,callBackFlag)
      

      • 

    • Mandatory parameters (Login):                                                                                                                                                        
        

      • 
Sound File Name -Unique sound file name.
        • 

      • 
Icon Name - Unique icon name
        • 

      • 
Callback Flag - True/False
        • 

      

      • 

    • Optional parameters (Login):                                                                                                                                                        
        

      • 
Sound Enable - True/False
        • 

      • 
Vibration Enable - True/False
        • 

      

      • 

    

    • 

  • 
Enable Push Notification:

      

    1. Copy the MTractionPushReceiver.java file to your application main Package folder. Change the Package Name at the top of the file, to the package name of the main project. .
      2. 

    2. Enable push notification feature for your application. 
      

      <meta-data android:name=”mt_PushNotification” android:value=”true” />
 

      

      3. 

    3. Permission Setting in Manifest.xml file 
      <uses-permission android:name=”android.permission.GET_ACCOUNTS”/>
<uses-permission android:name=”android.permission.WAKE_LOCK”/>
<permission android:name=”PACKAGE_NAME.permission.C2D_MESSAGE” android:protectionLevel=”signature”/>
<uses-permission android:name=”PACKAGE_NAME.permission.C2D_MESSAGE”/>
<uses-permission android:name=”com.google.android.c2dm.permission.RECEIVE”/>
<uses-permission android:name=”android.permission.VIBRATE”/>
<uses-permission android:name=”android.permission.GET_TASKS” />
      
Note: To set up your permissions, Replace "YOUR_PACKAGE_NAME" with your own app's package name. 
      4. 

    4. Open the AndroidManifest.xml file in your project and add the following Receiver settings. 
      <receiver android:name=”com.mtraction.gcm.GCMBroadcastReceiver ”
android:permission=”com.google.android.c2dm.permission.SEND”>
<intent-filter>
<action android:name=”com.google.android.c2dm.intent.RECEIVE”/>
<action android:name=”com.google.android.c2dm.intent.REGISTRATION”/>
<category android:name=”PACKAGE_NAME”/>
</intent-filter>
</receiver>Note: To set up your permissions, Replace "YOUR_PACKAGE_NAME" with your own app's package name.  
       Note:To set up your permissions, Replace "YOUR_PACKAGE_NAME" with your own app's package name. .
      5. 

    5. Setting up push service 
      <service android:name=”com.mtraction.mtractionpushtracker.PushService”>
<meta-data android:name=”callback_receiver”android:value=”.MTractionPushReceiver”/>
</service>
      
Note: Implement/invoke own method to handle deep linking within the application. 
      6. 

    6. Configure Push Sender ID 
      < meta-data android:name=”MTRACTION_SENDER_ID” android:value=”senderid:APP_PROJECT_ID”/>

      
Note: Implement/invoke own method to handle deep linking within the application.
      7. 

    

    • 

  • 

    Sample Code
    

    <script>
function trackCustomNotification(){
mtractiontracker.trackMTractionNotificationConfigurator("soundFileName","iconName",”sound,vibration”,”callback”);
}
</script>
    

    •