Android Integration: Native

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 Native SDK from the link below:

Android Native SDK 6.1.2 (Last updated: 30/Nov/2015)

It should contain the following:

1. AffleTrackerSDK.jar : This is the SDK library for integration in the application.
2. AffleInstallReceiver.java : This file is provided to extend/implement the base class of the AffleTracker.
3. AffleMultipleInstallReceivers.java
4. AfflePushReceiver.java

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.

Download Conversion Tracking

Basic Settings

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.

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

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

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

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

For Example :

add_google_play_service

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 >

Settings for Download Conversion Tracking

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

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

2. Open the AndroidManifest.xml file in your project and add the following

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

RECEIVER settings.

3. Do the following settings in the AndroidManifest.xml, Under the Application

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

section.

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

4. This step is only use for direct downloads, app publish other than google play store.

< application
//Direct download Settings.
< meta-data
android:name=”af_DDSource”
android:value=”Affle_PUBLISHER”/>
< /application>


Where Affle_PUBLISHER value would be provided in Project Setting file.
Note:-Don’t use this step if app publish in google play store.

Testing: Affle MAAS App

Paid/Owned/Organic Install Test –

Step 1: Test App Installs

1. Install the Affle MAAS App from here. This app will simulate a broadcast to your application.
2. Install your app integrated with AffletrackerSDK on Android device and launch it once.
3. Launch Affle MAAS App , Click on Test Install Button

null

4. Fill the specified package name of Install Receiver Class (e.g.”com.test.abs.AffleInstallReceiver”) of your application. And click on desired Test

Test Install

1. Organic Install – An organic install is when a user installs mobile app directly via Google Playstore. The User did not click on an advertisement banner (to install this app).

2. Owned Install – An owned install is when a user installs mobile app on click of an advertisement banner (to install this app). These advertisement banners, emails, sms or any other channel are used by the App Owner to directly market their product. Typically these installs are driven by a particular utm_source. The App developers, owners do not use Affle Maas Platform promotion channels. However, the Affle MAAS SDK can records these installs and report them under Owned. Example:- Owned_Adwords, Owned_email, Owned_smslink etc.

OwnedInstall

3. Paid Install – Paid install is when a user installs mobile app on click of an advertisement banner (to install this app). These banners are promoted via the Affle MAAS Platform and the installs will get recorded under a specific media source on the platform and shall be reported as Paid Installs.
For Affle Transaction Id, developer need to connect with Affle’s Tech Team.

Screenshot_2015-06-10-18-49-00

5. Launch your App again.
6. Check Affle MAAS Interface for Install analytics under your campaign.
7. Fire In-App events from your app.
8. Check Affle MAAS Interface for Event tracking.

Step 2: Steps after app installed on device

Use Android device that does not have this app installed. If the app is already Installed, Uninstall the application first and clear device history (device ID) from our system by Testing App
Clear Device History by following Steps: –

1. SignIn in Testing App through Affle MAAS Platform Authenticated User-Id and Password.

Screenshot_2015-06-10-18-51-17

2. Enter your Campaign Id in field for clearing device history (This is for testing only). Where Campaign Id ,you will get through e-mail by Affle MAAS Team.

CampaignId

3. Click on Forget Device Button.
Response of this action will be displayed as a toast message with all require details.

Testing: Google Playstore Apps

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. On You MAC or Linux Machine, perform the following steps on the

• Goto 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/.AffleInstallReceiver –es “referrer” “utm_source=xyz”

terminal:-

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

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

5. Validate from the logs printed in the DDMS of IDE.
* Please ensure that the “af_DebugMode” should be set to “false” before going live.

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

Testing: 3rd Party/Direct Download Apps

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 the configured Campaign Id
– af_cid

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.

Integrating Multiple Download Conversion Tracking SDK’s

1. If your Android app has multiple receivers for INSTALL_REFERRER, you will instead need to write a custom receiver that will call these receivers.
Create a new receiver class file AffleMultipleInstallReceivers.java (extending BroadcastReceiver) that looks something like this:

package com.affle.affletrackersdksample; //Application Package Name
import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;
import com.affle.affledowloadtracker.AffleAppDownloadTracker;
public class AffleMultipleInstallReceivers extends BroadcastReceiver {
@Override
public void onReceive(Context context, Intent intent) {
//Call AffleAppDownloadTracker
AffleAppDownloadTracker ad2ctrackerObj = new AffleAppDownloadTracker();
ad2ctrackerObj.onReceive(context,intent);

//Initialize and call onReceive for other receivers
}
}

2. Then place the receiver in your AndroidManifest.xml file like shown below,

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

but change the receiver name to the one you created above.


InApp Stats Tracking

Basic Settings

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

< 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. To enable “DEBUG” logs, the following setting should be enabled.

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

3. Add google-play-services_lib dependency project into your project’s Properties.

For Example :

add_google_play_service

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

InApp Stats & Purchase Tracking Settings

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

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

Under the Application section, add the following META-DATA

The Affle_CAMPAIGN_ID setting is provided in the ProjectSetting 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
To track your page or screen views in the app call, the method “inAppTrackerViewName” and pass the View Name that should be displayed on the analytics interface.

public static void inAppTrackerViewName (
Context context,
String viewName,
String viewDetail,
String eventName
Hashtable < String, Object> extraParams
)

Method Name : inAppTrackerViewName

• Example for Home Screen: –
AffleInApptracker.inAppTrackerViewName (context, “home”,””,””, “”);
• Example for Category List Screen: –
AffleInApptracker .inAppTrackerViewName (context, “Category1List”,””,””,””);

on_resume_method_2

To track view or view detail. You can call the method in onResume method of the Activity.

onresume-method-activity

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

public static void inAppTrackerViewName (
Context context,
String viewName,
String viewDetail,
String eventName
Hashtable < String, Object> extraParams
)

Method Name : inAppTrackerViewName

• Example for Category Detail Page with Title 1: –
AffleInApptracker.inAppTrackerViewName (context, “Category1Detail”,” Title1″,””,””);
• Example for Category Detail Page with Title 2: –
AffleInApptracker.inAppTrackerViewName (context, “Category1Detail”, “Title2″,””,””);

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

public static void inAppTrackerViewName (
Context context,
String viewName,
String viewDetail,
String eventName
Hashtable < String, Object> extraParams
)

Method Name : inAppTrackerViewName

Hashtable<String, Object> extraParams = new Hashtable<String, Object>();
extraParams.put(“key1”, “ABC”); // key1 mapped with FirstName
extraParams.put(“key2”, “XYZ”); //key2 mapped with LastName
extraParams.put(“key3”, “Male”); //key3 mapped with Gender
extraParams.put(“key4”, “Gurgaon”); //key4 mapped with Address

Note:- Extra Params key mapping will be send by the Application Manager to Affle MAAS Team.

• Example for FB_LIKE on Home Screen: –
AffleInApptracker.inAppTrackerViewName (context, “home”, “”, “fb_like”, extraParams);
• Example for TW_SHARE on Category List Screen: –
AffleInApptracker.inAppTrackerViewName (context, “Category1List”, “”, “tw_share”, extraParams);

• Example for RATING on Category Detail Page with Title 3: –
AffleInApptracker.inAppTrackerViewName (context, “Category2Detail”, ” Title3″, “rating5”, extraParams);

• Example for FB_SHARE on Category Detail Page with Title 4: –
AffleInApptracker.inAppTrackerViewName (context, “Category2Detail”, ” Title4″, “fb_share”, extraParams);

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

Example: – An event can be tracked via on a button click in the Activity by using the method like the block of code below.

event-tracked-on-click

d) Purchase
To track your Purchase Events in the app, call the method “inAppEventTrackerViewName” and pass the View Name, the Detail Description (if required), Purchase Event Name, Transaction Id, Purchase Amount of Transaction, and Purchase Quantity that should be displayed on the analytics interface.

public static void inAppEventTrackerViewName (
Context context,
String viewName,
String viewDetail,
String pevent,
String ptid,
String pamount,
int pqty,
String pcurrency,
Hashtable < String, Object> extraParams
)

Method Name : inAppEventTrackerViewName

• Example for Purchase on Movie Booking Detail Page: –

Hashtable<String, Object> extraParams = new Hashtable<String, Object>();
extraParams.put(“key1”, “ABC”); // key1 mapped with cardName
extraParams.put(“key2”, “Delhi”); // key2 mapped with eventLocation
extraParams.put(“key3”, “Movie”); // key3 mapped with eventType
extraParams.put(“key4”, “visa”); // key4 mapped with cardType

Note:- Extra Params key mapping will be send by the Application Manager to Affle MAAS Team.

AffleInApptracker.inAppEventTrackerViewName (context, “Movie1Title”, “”, “Movie1Name”, “12345”, 1000, 4, “INR”, extraParams);
* Price of 1 Ticket = 250, 4 Tickets = 1000

• Example for Purchase on Taxi Booking Detail Page: –
AffleInApptracker.inAppEventTrackerViewName (context, “TaxiCategory1”, “”, “YellowTaxi”, “abcd22344xxuz”, 1500, 1, “INR”, extraParams);
*Price of 1 Ticket = 1500

• Example for Credit Purchase on Game Credit Purchase Page: –

AffleInApptracker.inAppEventTrackerViewName (context, “Game1”, “”, “Credit”, “putc445ghfb”, 500, 1000, “INR”, extraParams);

on_resume_method_2

This method is use to track purchase event.
Example: Use this method to track in app billing by calling the method in the place the purchase event success.

app-billing-method

Note:- For Proper In-App analytics tracking we recommend to pass AffleInAppTracker.APP_EXIT event on exit of Application
For Example –

AppExitEvent

Testing For Applications Hosted on Google Playstore/3rd party Application store

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

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

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

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

5. You should be able to see the pings from 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.


 

Application Push Notifications

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.

Basic Settings

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

< 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. Open the AndroidManifest.xml file in your project and add the following

< intent-filter>
< data android:scheme=”APP_NAME” />
< action android:name=”android.intent.action.VIEW” />
< category android:name=”android.intent.category.BROWSABLE” />
< category android:name=”android.intent.category.DEFAULT” />
< /intent-filter &gt

intent filter, in the Main Activity: –

Replace the APP_NAME with your application name in small case. This APP_NAME is provided to you as a part of the ProjectSettings file.

3. Do the following settings in the AndroidManifest.xml, Under the Application

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

section.

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

4. To enable “DEBUG” logs, the following setting should be enabled.

< 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. Add google-play-services_lib dependency project into your project’s Properties.

For Example :

add_google_play_service

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

Testing: Google Playstore/3rd Party Appstore

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

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

4. Validate from the logs printed in the DDMS of IDE.
* Please ensure that the “af_DebugMode” should be set to “false” before going live.

5. You should be able to see the pings from 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.

Affle Push Architecture/Settings

push_notification

Enabling Push Notifications

Copy the AfflePushReceiver.java file to your applications main Package 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. http://developer.android.com/tools/support-library/setup.html

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=”.AfflePushReceiver”/>
< /service>

When Push Notification receive from Affle Ads Platform. Affle tracker SDK integrated inside application, display Notification Message in notification bar (when app is in background), or send onAfflePushReceive() Callback with custom data to application (when app is in foreground). When notification message open from notification bar Affle tracker sdk invokes AfflePushReceiver class and pass all custom data to application. Developer can use this data to perform deeplinking.

Enable/Disable Push Notification Feature

Add the following below code where you want to enable/disable push notification feature.

AffleNotificationConfigurator.getInstance(this)
.setEnablePushNotification(false);

Configure Push Notification Timer

When user open 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

Above configuration, I specify 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 http://developer.android.com/google/gcm/gs.html#create-proj

Configure notification: Vibrate, Sound, Icon.

By default, the SDK will use application’s icon to display on notification item. Also, sound and vibrate is enable.
For whom want to use your own icon or disable the sound or vibrate. We provide a configuration class called AffleNotificationConfigurator to help. The below example will show you how to use that class.

affle-notification-configurator

AffleNotificationConfigurator affleNotificationConfigurator = AffleNotificationConfigurator
.getInstance(this);
affleNotificationConfigurator.config(R.drawable.ic_launcher, true, true,
R.raw.soundID ,new AffleCustomNotification() {
@Override
public void onAfflePushReceive(Bundle pBundle) {
// TODO Auto-generated method stub
String title = pBundle.getString(“title”);
String message = pBundle.getString(“message”);
String url = pBundle.getString(“url”);
}
});

The class should be ideally implemented in the main class and always placed below “trackDownload” method call.

Also do the permission settings in the AndroidManifest.xml

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

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


Application Deep-linking on mSite Banner

App Url Scheme Setting –

Define intent filter in Activity, where user wants to handle it as mSite (Mobile Site Banner) Deep-linking in Manifest file.
Note: – APP_URL_SCHEME will be provided in ProjectSetting file from Affle Maas Team.

<intent-filter>
<data android:scheme=”APP_URL_SCHEME” />
<action android:name=”android.intent.action.VIEW” />
<category android:name=”android.intent.category.DEFAULT” />
<category android:name=”android.intent.category.BROWSABLE” />
</intent-filter>

For Example –

<activity android:name=”.DeeplinkingActivity”>
<intent-filter>
<data android:scheme=”affle” />
<action android:name=”android.intent.action.VIEW” />
<category android:name=”android.intent.category.DEFAULT” />
<category android:name=”android.intent.category.BROWSABLE” />
</intent-filter>
</activity>

App Url Scheme Handling in App –

In order for your app to respond when it receives a custom URL call, Developer needs to follow some steps on development site
1. Developer has to extend AffleDeepLinkingActivity class in Activity to which user wants to integrate as a mSite banner deep-linking activity.

2. Developer has to implement the onHandleAffleUri(Uri arg0) method in extended class.

@Override
public void onHandleAffleUri(Uri arg0) {
// TODO Auto-generated method stub
}

App Url Scheme Testing

Now, to check that our registered URL scheme works, we’ll head out to Mozilla. Go to Mozilla browser and Open it. Next, type App_Scheme registered with App in the address bar of Mozilla, (Same as we do with http:// URLs). Press Go.
For Example : As given in below screenshot.

DeepLinking

You should see that we’ve arrived back in our Application.