Android Integration Guide: PhoneGap

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



Getting the Affle Tracker SDK

You can download the latest Android PhoneGap SDK from the link below:

Android PhoneGap SDK (Last updated: 24/August/2015)

It should contain the following:

1. AffleTrackerSDK.jar : SDK library for in-app integration.
2. AffleTracker.java : Extend/implementing the class AffleTracker in-app.
3. affletracker.js : Javascript bridge class for communication between HTML/JS native to AffleTracker java.
4. SDKProjectSettings.txt : Tracking ID and other key settings specific to the application.

The step-by-step integration process has been described in detail in the coming sections. Please note any developer attempting to integrate the SDK must have sound knowledge of JAVA/ANDROID IDE.

Integration Guide

Add AffleTrackerSDK.jar to your project as a project library.
• If you’re using Eclipse, modify your Java Build Path, and choose Add External JAR.
• If you’re using the SDK tools directly, drop it into your libs folder and the ant task will pick it up.
Add the AffleTracker.java to your project’s src/com/affle/affletrackersdk/ folder as shown in the image below.

phonegapaffletracker


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


addjs

Add plugin feature into the res/xml/config.xml file:

<feature name=”AffleTracker” >
<param name=”android-package” value=”com.affle.affletrackersdk.AffleTracker” / >
</feature >

The file structure should look like below:

— assets/
   — www/
    — js/
     — affletracker.js
— libs/
   — AffleTrackerSDK.jar
— res/
— src/
   — affle/
     — affletrackersdk/
      — AffleTracker.java


Integration Settings

1. Open the AndroidManifest.xml file in your project and add the following:-
Permission to access Internet, Phone State and Network State.

<uses-permission android:name=”android.permission.INTERNET” />
<uses-permission android:name=”android.permission.READ_PHONE_STATE” />
< uses-permission android:name=”android.permission.ACCESS_NETWORK_STATE”/>

Permission to access Internet, Phone State and Network State.

2. Put the following lines of code in the first place your app
run. We Recommend to place it in the onCreate() method of Application.

AffleAppDownloadTracker ad2ctrackerObj = new AffleAppDownloadTracker();
ad2ctrackerObj.trackDownload(getApplicationContext(), null);

3. To enable “DEBUG” logs, the following setting should be enabled.
* Please ensure that the “af_DebugMode” should be set to “false” before going live.

<application
//Other Settings ….
<meta-data
android:name=” af_DebugMode ”
android:value=”true” />
</application>

4. Add google-play-services_lib dependency project into your project Properties.

For Example :
projectprop

5. 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>


Download Conversion Tracking

If the requirement suggests, tracking the download conversions then use the following settings:

1. Open the AndroidManifest.xml file in your project and add the following RECEIVER settings.

< receiver android:name=”com.affle.affledowloadtracker.AffleAppDownloadTracker” android:exported=”true” >
< intent-filter >
< action android:name=”com.android.vending.INSTALL_REFERRER” />
< /intent-filter>

2. Do the following settings in the AndroidManifest.xml, Under the Application section.

<application
//Other Settings.
<meta-data
android:name=”af_cid”
android:value=”Affle_CAMPAIGN_ID”/>
</application>

The Affle_CAMPAIGN_ID is provided to you as a part of the SDKProjectSettings.txt file.

Testing

1. Connect your android device or start the emulator on your machine.
2. Ensure that the App does not pre-exist on the emulator or the Android device
3. Now Load the your App on the Device or the Android Emulator via the IDE & Open it
4. On You MAC or Linux Machine, perform the following steps on the terminal:-

– Go to the android Platform tools Folder. (android-sdk/platform-tools)
– run the command
./adb shell
– Execute the command:-
am broadcast -a com.android.vending.INSTALL_REFERRER -n PACKAGE_NAME/com.affle.affledowloadtracker.AffleAppDownloadTracker –es “referrer” “utm_source=ad2campaign_test”

** REPLACE PACKAGE_NAME with the application package name under which the AffleInstallReceiver.class has been implemented.

5. Validate from the logs printed in the DDMS of IDE

<application
//Other Settings.
<meta-data
android:name=”af_DebugMode”
android:value=”true” />
</application>

* Please ensure that the “af_DebugMode” should be set to “false” before going live.

6. You should be able to see the pings from either or both the configured Campaign Id
– af_cid

7. Once you’ve reached the point in your app where the activity should be tracked, check to see if it was recorded in the Event Logs Report. The event should be attributed to the same publisher as the install unless the event uses Re-Engagement.

In-App Stats & Purchase Tracking

If the requirement suggests, tracking the inApplication Stats like Page Views, Engagements, Events, Purchase Events & other Analytics, then use the following settings:

1. Open the AndroidManifest.xml file in your project and add the following: –

Under the Application section, add the following META-DATA

<application
//Other Settings.
<meta-data
android:name=”af_cid”
android:value=”Affle_CAMPAIGN_ID”//>
</application/>

The Affle_CAMPAIGN_ID setting is provided in the SDKProjectSetting.txt file.

2. Set tracking duration for a session as follow:

Under the Application section, add the following META-DATA

<application
//Other Settings.
<meta-data
android:name=”af_SessionTimeOut”
android:value=”3600″/>
</application>

The default value is 3600 seconds if it were not set.

3. Call the following methods in your program to capture the Page Views, Engagements, Events, Purchase Events & other Analytics

a) Page Views Tracking

Include the affletracker.js to your html file

<script type=”text/javascript” src=”js/affletracker.js”></script>

To track your page or screen views in the app call, the method “affletracker.inAppTrackerViewName” and pass the View Name that should be displayed on the analytics interface.

Method Name : inAppTrackerViewName

• Example for Home Screen: –
affletracker.inAppTrackerViewName(“Home”, null, null, null);

• Example for Category List Screen: –
affletracker.inAppTrackerViewName(“Category1List “, null, null, null);

<script type=”text/javascript”>
function onLoad() {
affletracker.inAppTrackerViewName(“Home”, null, null,null);
};
</script>


b) Page View & Details Tracking

Include the affletracker.js to your html file

<script type=”text/javascript” src=”js/affletracker.js”></script>

To track your page or screen views & extra details in the app call, the method “affletracker.inAppTrackerViewName” and pass the View Name & the Detail Description of the page that should be displayed on the analytics interface.

Method Name : inAppTrackerViewName

/**
* inAppTrackerViewName(viewName, viewDetail, eventName,extraParams) Function called by the
* Application to track views, events etc.
*
* @param viewName – Current View name.
* @param viewDetail – A detail string describes for current View, “null” if
* It weren’t exist.
* @param eventName – An event name on view, “null” if it weren’t exist.
* @param extraParams- extraParams in jsoan object with key value pair , “null” if it weren’t exist.
* extraParams key mapping will be send by Application Manager to Affle Maas Team
*/

var extraParams={“key1″:”xyz”,”key2:abc”};
Where key1 mapped with FirstName, key2 mapped with LastName.

Note : ExtraParams key mapping will be sent by Affle’s MAAS Team.

• Example for Category Detail Page with Title 1:
affletracker.inAppTrackerViewName(“Category1Detail”, “Title1”, null,extraParams);


• Example for Category Detail Page with Title 2:
affletracker.inAppTrackerViewName(“Category1Detail”, ” Title2″, null, extraParams);

<script type=”text/javascript”>
function onLoad() {
var extraParams=={“key1″:”Suraj”,”key2:Verma”};
affletracker.inAppTrackerViewName(“Home”, “Home page”, “test”, extraParams);
};
</script/>




c) Engagement/Events

Include the affletracker.js to your html file

<script type=”text/javascript” src=”js/affletracker.js”></script>

To track your Engagement/Events in the app, call the method “affletracker.inAppTrackerViewName” and pass the View Name, the Detail Description of the page & Event/Engagement Name that should be displayed on the analytics interface.

Method Name : inAppTrackerViewName

/**
* inAppTrackerViewName(viewName, viewDetail, eventName,extraParams) Function called by the
* Application to track views, events etc.
*
* @param viewName – Current View name.
* @param viewDetail – A detail string describes for current View, “null” if
* It weren’t exist.
* @param eventName – An event name on view, “null” if it weren’t exist.
* @param extraParams- extraParams in jsoan object with key value pair, “null” if it weren’t exist.
*/

var extraParams={“key1:Anil”,”key2:Sharma”};
Where key1 mapped with FirstName and key2 mapped with LastName.

Note: ExtraParams key mapping will be send by Application Manager to Affle’s Maas Team.

• Example for FB_LIKE on Home Screen:

affletracker.inAppTrackerViewName(“Category1Detail”, null,” fb_like”, extraParams);


• Example for TW_SHARE on Category List Screen:

affletracker.inAppTrackerViewName(“Category1Detail “, null,” tw_share”, extraParams);


• Example for RATING on Category Detail Page with Title 3:

affletracker.inAppTrackerViewName(“Category2Detail “, “Title3″,” tw_share”,null);


• Example for FB_SHARE on Category Detail Page with Title 4:

affletracker.inAppTrackerViewName(“Category2Detail “, “Title4″,” tw_share”,extraParams);

To track events, call the method on the place the event is triggered.

<script type=”text/javascript”>
function onClick() {
var extraParams={“key1″:”xyz”,”key2:abc”};
affletracker.inAppTrackerViewName(“Home”, “Home page”, “Event 1 clicked!”, extraParams);
}
</script>

d) Purchase

Include the affletracker.js to your html file

<script type=”text/javascript” src=”js/affletracker.js”></script>

To track your Purchase Events in the app, call the method “affletracker.inAppEventTrackerViewName” and pass the View Name, the Detail Description (if required), Purchase Event Name, Transaction Id, Purchase Amount of Transaction, Purchase Quantity, Purchase Currency, and Extra Params (like CardType, EventLocation, EventType etc.) that should be displayed on the analytics interface.

Method Name : inAppEventTrackerViewName

/**
* inAppEventTrackerViewName(viewName, viewDetail, pevent, ptid, pamount, pqty,
*pcurrency, extraParams)Function called by the Application to track for
* Purchase Event
* detail (view, pEvent, pTid, pAmount, pamount, pcurrency, extraParams
etc).
*
* @param viewName – Current View name.
* @param viewDetail – A detail string describes for current View, “null”
* if it weren’t exist.
* @param pevent – Purchase event name
* @param ptid – Purchase event transaction id, returned by payment
* gateway or booking engine.
* @param pqty – Purchase event quantity. Example: Number of tickets
* booked
* @param pamount – Purchase Event Amount. Example:- 200, 5 etc
* @param pcurrency – Purchase Event Currency. Example:- INR, EUR
* @param extraParams- Purchase Event extraParams. Example:-
* var extraParams={“key1:movie name”,”key2:movie language”,”key3:movie venue”};
*/
;



Example for Purchase on Movie Booking Detail Page
var extra={“key1:movie name”,”key2:movie language”,”key3:movie venue”};

//Where key1 mapped with movie name , key2 mapped with movie language, key3 mapped with movie venue.

affletracker.inAppEventTrackerViewName (“Movie1Title”, “null”, “Movie1Name”, “12345”, 1000, 4, “EUR”, extras);
* Price of 1 Ticket = 250, 4 Tickets = 1000


Example for Purchase on Taxi Booking Detail Page
var extraParams = {“key4″:”11:00:00”, “key5″:”abc”};
//where key4 mapped with booking time ,key5 mapped with driver name

affletracker.inAppEventTrackerViewName (“TaxiCategory1”, null, “YellowTaxi”, “abcd22344xxuz”, 1500, 1, “INR”, extraParams);
*Price of 1 Ticket = 1500


Example for Credit Purchase on Game Credit Purchase Page

var extras = {“key1:shooter”};
//where key1 mapped with gametype

affletracker.inAppEventTrackerViewName (“Game1”, null, “Credit”, “putc445ghfb”, 500, 1000, “INR”, extras);

NOTE: Extra Params Key mapping will be sent by Application Manager to Affle Maas Team

<script type=”text/javascript”>
function purchase() {
affletracker.inAppEventTrackerViewName(“Purchase Screen”, “Purchase Screen Detail”, “Buy Immortal”, “BuyImmortal”, “10”, 1, “EUR”, extras);
}
</script>


Testing

1. Connect your android device or start the emulator on you machine.
2. Ensure that the App does not pre-exist on the emulator or the Android device
3. Now Load the your App on the Device or the Android Emulator via the IDE & Open it
4. Validate from the logs printed in the DDMS of IDE.

<application
//Other Settings.
<meta-data
android:name=”af_DebugMode”
android:value=”true” />
</application>

*Please ensure that the “af_DebugMode” should be set to “false” before going live.

5. You should be able to see the pings from either or both the configured Campaign Id
– af_cid

6. Once you’ve reached the point in your app where the activity should be tracked, check to see if it was recorded in the Event Logs Report. The event should be attributed to the same publisher as the install unless the event uses Re-Engagement.

Note:- The easiest way to test is to send an email with a tracking link, log file and the updated file for the Android app. From an Android device, conduct the test with the information from the email.


Push Architecture/Settings

Architecture

push_notification

Push Notification or Google Cloud Messaging for Android (GCM) is a service that allows the Application owner to send data from the server to the application users’ Android-powered device, and also to receive messages from devices on the same connection.

Configuration

Copy the AfflePushReceiver.java file to your application’s src/com/affle/affletrackersdk/ folder. Change the Package Name at the top of the file, to the package name of the main project.
** You must add android-support-v4 to you project’s libs to use PUSH NOTIFICATION feature.

Configure the AndroidManifest.xml file like below to enable push notification feature.

< 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”/>
< meta-data
android:name=”af_PushNotification”
android:value=”true” />

Set af_PushNotification “true” for enable push Notification feature in AffletrackerSDK.

Setting Up Permissions
Replace the PACKAGE_NAME with the name of your application package.

Setting Up Receivers
Replace the PACKAGE_NAME with the name of your application package.

< receiver
android:name=”com.affle.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>

Setting up the Push Service

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

< service android:name=”com.affle.afflepushtracker.PushService”>
< meta-data
android:name=”callback_receiver”
android:value=”com.affle.affletrackersdk.AfflePushReceiver”/>
< /service>

When Push Notification receive from Affle Maas Platform. Affle tracker SDK integrated inside application ,display Notification Message in notification bar (when app is in background), or send onPushReceiveCallBack (message) Callback with custom data to application (when app is in foreground).

When notification message open from notification bar ,Affle tracker sdk invokes AfflePushReceiver.java class and set notification data for further use when application comes in foreground.
Developer can get that data by calling getNotificationData() and will notify by callback method onNotificationDataSuccess(message) to perform deeplinking.
For Example:-

<script type=”text/javascript”>
function onDeviceReady() {
affletracker.getNotificationData();
<script>

Configure Push Notification Timer

When user opens the push notification item – the SDK will start a timer.

< meta-data
android:name=”af_pnt”
android:value=”120″/>

During the timer running any pevent/event generated will be sent to the server with the push_id included. You can specify how long the timer can run by configure the push notification timer in your AndroidManifest.xml.

With the above configuration, the timer can run 120 seconds. If you not set the timer the SDK will start timer for 60 minutes by default.
If developer wants to configure timer on receiving Push Notification Message .Then Configured below mention code snippet on App’s Manifest file.

For Example:

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

Configure Push Sender Id

< meta-data
android:name=”SENDER_ID”
android:value=”senderid:APP_PROJECT_ID“/>

APP_PROJECT_ID is the project number provide by Google Projects Setup. Please refer to the step provided in the link to create Creating a Google API Project

Configure notification: Vibrate, Sound, Icon.

By default, the SDK will use application’s icon to display on notification item. Sound and vibrate is enabled.
To use your own icon or disable the sound or vibrate – a configuration class called AffleNotificationConfigurator is provided to help. The below example will show you how to use that class.

/**
* Function called by the Application to configure custom
* Notification affleNotificationConfigurator(iconName, isSoundEnable,
* isVibrateEnable, soundName).
* @param iconName – Notification Icon Name from drawable
* folder of res.
* @param isSoundEnable – Flag for enable or disable
* notification sound.
* @param isVibrateEnable – Flag for enable or disable
* notification vibration mode.
* @param soundName – File Name from raw folder of res, to play
* custom sound when receiving notification.
*/

<script type=”text/javascript”>
function onDeviceReady() {
affletracker.affleNotificationConfigurator(“ic_launcher”, “true”, “true”,
“overthehorizon”, “true”); }
<script>

Note:Also set permission settings in the AndroidManifest.xml

To show that dialog you need to configure your app’s AndroidManifest.xml like below:
Add the permissions settings.

<uses-permission android:name=”android.permission.GET_TASKS” />
<uses-permission android:name=”android.permission.SYSTEM_ALERT_WINDOW” />