You are on page 1of 17

PartyTrackSDK(Android) document

2014/04/16

To begin
Partytrack SDK for Android is provided as a .jar file. Add Partytrack folder to the
project to integrate the SDK in.

Flow of the integration


1. Add .jar file to library.
2. Add settings to AndroidManifest.xml
3. Call up Initialize Setting method.
4. Call up each tracking methods.
This document will explain briefly regarding 2~4.
About measurement for Facebook mobile app install ad
PartyTrackSDK supports measurement Facebook mobile app install ad.
If you need to use this function, you must agree to the privacy policy and guidelines
below.
And you can not use the data of Facebook users without the consent of the users.
( For iOS, getting IDFA of users is required. )
https://www.facebook.com/about/privacy
https://www.facebook.com/ad_guidelines.php
Steps to start measurement:
1. register developer account for https://developers.facebook.com/
2. register you app account
3. get your App ID for facebook
If you integrate our SDK and add App ID to our dashboard, we regard you have
agreed the privacy policy and guidelines of Facebook.
And if you agree to
https://www.facebook.com/ads/manage/advanced_mobile_measurement/tos,
you can get the user level data.

Adding settings to AndroidManifest.xml (required)


This clause explains how to set up for followings:
permission setting
Android Advertising ID setting
GooglePlay Install Referrer setting and its using
Every setting is mandatory.

permission setting
Please add following permission.Required
<uses-permission android:name="android.permission.INTERNET" />

Permission to acquire ID which is used for check duplicated conversion is


following.
Ideally, using Android Advertising ID is the best way, but some networks
require below ID. Therefore it might be better to acquire them until the end
of July, 2014.
imei
<uses-permission android:name="android.permission.READ_PHONE_STATE" />

mac address
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

Setting for Android Advertising ID


Since August 2014, using Android Advertising ID is mandatory.
Please add following referrer to sub element of application tag to utilize
Install Referrer by GooglePlay.
<meta-data
android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version" />

To use Android Advertising ID, setting for Google Play Service SDK is
required. Please refer following URL for setting information.
https://developer.android.com/google/play-services/setup.html

Android Advertising ID is only acquired on device which OS is over


Android2.3 and using Google Play.
Please refer following URL for policy of Android Advertising ID by Google.
http://play.google.com/about/developer-content-policy.html#ADID

Please disregard message for The Google Play services resources were
not found. Check your project configuration to ensure that the resources
are included. displayed on Log cat when attempting to acquire Android
Advertising ID.

Please add following referrer to sub element of application tag to utilize


Install Referrer by GooglePlayRequired
If you use MultipleReferrerReceiver on next clause, this content does
not need to be implemented.
<receiver
android:name="it.partytrack.sdk.ReferrerReceiver"
android:exported="true" >
<intent-filter>
<action android:name="com.android.vending.INSTALL_REFERRER" />
</intent-filter>
</receiver>

If your app is already using receiver install referrer and need to utilize it in
conjunction with PartyTrack SDK:Inside your app in the onReceive method
of the receiver class, call the receiver class in our SDK as below.

package your.app.package;
import
import
import
import

it.partytrack.sdk.ReferrerReceiver;
android.content.BroadcastReceiver;
android.content.Context;
android.content.Intent;

public class YourBroadCastReceiver extends BroadcastReceiver {


@Override
public void onReceive(Context context, Intent intent) {
ReferrerReceiver partyReceiver = new ReferrerReceiver();
partyReceiver.onReceive(context, intent);
...
...
}
}

Please use MultipleReferrerReceiver In case of requesting multiple


receivers and unable to change receive class for certain reason(1).
Not mandatory to implement for previous clause if you use
MultipleReferrerReceiver class.
MultipleReferrerReceiver class automatically requests onReceive in
it.partytrack.sdk.ReferrerReceiver.
For implementation, please add receiver as following and write meta-data
tag of requesting receiver class on android:name attribute.
<receiver
android:name="it.partytrack.sdk.MultipleReferrerReceiver"
android:exported="true" >
<intent-filter>
<action android:name="com.android.vending.INSTALL_REFERRER" />
</intent-filter>
<meta-data android:name="sample.thirdparty.Receiver1" android:value="" />
<meta-data android:name="sample.thirdparty.Receiver2" android:value="" />
<meta-data android:name="sample.thirdparty.Receiver3" android:value="" />
</receiver>

Please adjust value properly if value is null character since


android:value attribute is necessary for meta-data tag.

1 In case like neither development language is not Java nor development of class succeeded
BroadcastReceiver is not affordable.

If you use obfuscation tools, please refer to the below.

If you use proguard, please describe below.


-keep public class it.partytrack.sdk.ReferrerReceiver{
public protected *;
}
-keep public class it.partytrack.sdk.MultipleReferrerReceiver{
public protected *;
}
-keep public class com.google.android.gms.ads.identifier.** {
public protected *;
}

In the case of other than proguard, please exclude from obfuscation


subject to the following class.
it.partytrack.sdk.ReferrerReceiver
it.partytrack.sdk.MultipleReferrerReceiver
com.google.android.gms.ads.identifier *Each method and a subclass of this following

If you cannot use Android Advertising ID for some reason,


excluding obfuscation for sub class under
com.google.android.gms.ads.identifier and method is not
necessary.

Verifying whether install receiver works by self test on next clause is


strongly recommended.
Although self test helps most of case, it is a test carried before App is
placed on market. To have accurate test, testing through Google Play is
strongly recommended.

Self-Test for Install Referrer implement status


Checking implement status is verified by requesting implemented Receiver
class over shell.
The Receiver class should be the one that you used on
AndroidManifest.xml.
Checking implement status goes with following commend.
1. Install App which finished install referrer integration
- adb install .apk

2. Run shell in Android


- adb shell
3. Issue install referrers BroadcastIntent
- am broadcast -a com.android.vending.INSTALL_REFERRER -n
your.app.package/.ReceiverClassName --es "referrer" "adzcore123adzcore
DO NOT CHANGE "adzcore123adzcore
4. Confirm referrer file for PartyTrack is made
- cd /data/data/your.app.package/files
- ls partytrack.referrer
- ls partytrack.full_referrer
If ls commend returns value asNo such file of directory, it means Receiver for
PartyTrack is not working properly.

No need to concern for return value asPermission deniedin not Rooted device.

Detail procedure and commend for Install Referrer is explained on


next clause.
Basically if referrer for PartyTrack is made, there would be no issue.

Case #1. Only using PartyTrack Receiver class


e.g.
- Package: com.test.app1
- apk file name: TestApp1.apk
1. Install App which finished install referrer integration
- adb install TestApp1.apk
2. Run shell in Android
- adb shell
3. Issue install referrers BroadcastIntent
- am broadcast -a com.android.vending.INSTALL_REFERRER -n
com.test.app1/it.partytrack.sdk.ReferrerReceiver --es "referrer" "adzcore123adzcore"
4. Confirm referrer file for PartyTrack is made
- cd /data/data/ com.test.app1/files
- ls partytrack.referrer
- ls partytrack.full_referrer

*Please rename each apk, package, and Receiver class name to


appropriate name before you start PartyTrack integration.

10

Case #2. Only using PartyTrack MulipleReferrerReceiver class


e.g.
- Package: com.test.app2
- apk file name: TestApp2.apk

1. Install App which finished install referrer integration


- adb install TestApp2.apk
2. Run shell in Android
- adb shell
3. .Issue install referrers BroadcastIntent
- am broadcast -a com.android.vending.INSTALL_REFERRER -n
com.test.app2/it.partytrack.sdk.MultipleReferrerReceiver --es "referrer"
"adzcore123adzcore"
4. Confirm referrer file for PartyTrack is made
- cd /data/data/com.test.app2/files
- ls partytrack.referrer
- ls partytrack.full_referrer

*Please rename each apk, package, and Receiver class name to


appropriate name before you start PartyTrack integration.

11

Case #3. Using own Receiver class


e.g.
- Package: com.test.app3
- apk file name: TestApp3.apk
- Own Receiver class name: com.test.app3.MyReceiver
1. Install App which finished install referrer integration
- adb install TestApp3.apk
2. Run shell in Android
- adb shell
3. Issue install referrers BroadcastIntent
- am broadcast -a com.android.vending.INSTALL_REFERRER -n
com.test.app3/.MyReceiver --es "referrer" "adzcore123adzcore"
4. Confirm referrer file for PartyTrack is made
- cd /data/data/ com.test.app3/files
- ls partytrack.referrer
- ls partytrack.full_referrer

*Please rename each apk, package, and Receiver class name to


appropriate name before you start PartyTrack integration.

12

Case #4. Using the 3rd partys Receiver class


e.g.
- Package: com.test.app4
- apk file name: TestApp4.apk
- Own Receiver class name: com.thirdparty.Receiver
1. Install App which finished install referrer integration
- adb install TestApp4.apk
2. Run shell in Android
- adb shell
3. Issue install referrers BroadcastIntent
- am broadcast -a com.android.vending.INSTALL_REFERRER -n com.test.app4/
com.thirdparty.Receiver --es "referrer" "adzcore123adzcore"
4. Confirm referrer file for PartyTrack is made
- cd /data/data/ com.test.app4/files
- ls partytrack.referrer
- ls partytrack.full_referrer

*Please rename each apk, package, and Receiver class name to


appropriate name before you start PartyTrack integration.

13

Calling initial method (required)


Import track class.
import it.partytrack.sdk.Track;

*to utilize track class use the corresponding import.

Call start method of track class.


And call it each time app launching.
Track.start(context, appId, appKey);

Context (type: context):


appId: (type: int) Insert ID provided by Adways.
appKey: (type:String) insert app KEY provided Adways
Track.start will initialize PartyTrackSDK and send install event.
If there are any event that is not sent, it will send that event.
Example
Track.start(this.getApplicationContext(), 100, abcdefghijk);

CAUTION
Please DO NOT SET WebView of UserAgent with OWN METHOD. It
causes tracking might not work properly.

14

Calling each tracking methods


PartyTrack creates install, update, launch and payment by default and
update and launch will be tracked after install setting method has been
implemented correctly.
Apart from install, update, launch and payment, if you would like to track
events such as registration or tutorial completion, create the relevant
event ID and call it up using event method.
Specifically, call up the below method of track class any timing you wish to
track the method.
Event tracking
Call the following method
Track.event(eventId);

eventId: (type: int); Send selected event data


However, if for any reason, install event fails to send, event data wont be sent until install
event is sent correctly.

Payment tracking
Call the following method
Track.payment(itemName, itemPrice, itemPriceCurrency, itemNum);

itemName: (String) Name of item


itemPrice: (float) unit price of item
itemPriceCurrency: (String) currency code (see below for more detail)
itemNum: (int) number of item *Generally "1"
Track.payment method will send payment data.
However, if for any reason, install event fails to send, event data wont be sent until install
event is sent correctly.
itemPriceCurrency should be set using 3 alphabet code set by ISO 4217.
Refer to the following list for the correct code http://en.wikipedia.org/wiki/ISO_4217
15

Option setting (not required)


PartTrackSDK options can be set to the below.

Debug Mode ON
Call setDebugMode method of Track Class.
Track.setDebugMode(true);

By turning debug mode ON, Logcat can output debug information to


PartyTrackDebugInfo.
Make sure debug setting Is OFF when the app is released.

Sending additional parameters to the server


Call the Track.setOptinalParam method below to add parameter to
the server.
Track.setOptionalparam method is alias of Track.setOptionalParam method.
Track.setOptionalParam(paramKey, paramValue);

paramKey: (String )
paramValue: (String)

Do not use capital letter.

Send corresponding parameter with the following format:


paramKey=paramValue
To set post back call for the above parameter, setting needs to be done on the Party
Track dashboard.
To utilize unique user ID to identify each user, use below as paramKey
Key

Value

Notes

Track.CLIENT_ID

client_id

e.g. user id of your service (not


device id)

16

Opt-out about facebook ads optimization by using user data


Any application can choose to include a setting for users to turn off ad
tracking within that app.
Facebook asks partners to include this option in their SDK and report
back the user's choice to Facebook along with the install or conversion
event.
Facebook will use the install or conversion event for ad reporting but
restrict it from being used in ad optimization.
The user's setting must persist across app launches.
If you use this function, call the below method.
Track.disableAdvertisementOptimize();

17