Monetise your app installs and in-app activities with our mobile SDK.
Tradedoubler's mobile Software Development Kit (SDK) optimises your Performance Marketing app activity. Whether your traffic comes from mobile web or in-app the SDK allows you to:
The mobile SDK supports the Android and iOS platforms with 32-bit and 64-bit support for iOS. They include all the benefits of Tradedoubler's accurate and secure tracking with mobile specific additions.
Do not have an affiliate program with Tradedoubler? Contact us
This documentation is intended for advertisers. If you are a publisher, go to the publisher documentation.
Our world-class tracking accuracy, robustness and security available for your e-commerce site is mirrored in our mobile SDK. You can find more information on Tradedoubler's tracking here.
The SDKs operate differently depending on the platform (iOS or Android) but the functionality remains the same.
App Download Tracking (ADT) allows you to drive uptake of your app via Tradedoubler's publisher network. With ADT you only pay for completed installs - the user must launch the app - on a CPI basis.
Once the download has taken place you will probably want to track the quality and performance of the traffic. ADT allows this by tracking pre-defined activities on a CPA or CPL basis. Events could include in-app purchases, reaching a certain game level or registering for a service.
Now you can identify the best traffic sources and track the lifetime value of downloads generated by publishers - all on a performance based remuneration model.
Native apps are often an essential part of advertisers' multi-channel marketing strategy, as they offer the best consumer experience on a smartphone or tablet. Until now it has been difficult to track publisher traffic going to pre-installed advertisers' apps. This limits publishers' options when promoting in-app transactions.
Tradedoubler's In-App Tracking (IAT) makes it possible to drive users to pre-installed apps, giving the advertiser the option to direct the user to the destination that offers the best experience of the brand.
At the time of click Tradedoubler will check the user's device to see if your app is already installed, and if so direct them to it. In-app activities (e.g. purchases, registrations, game achievements) are then tracked on a performance based model.
You can now incorporate your apps within your performance marketing activities.
Publishers often use deep links to direct the user to a specific area or page in your app rather than sending them to a generic landing page. This method provides an improved user journey and increased conversion rates as users are driven to the product/area they requested rather than having to search again.
In-app actions may take place when the device does not have an internet connection (e.g. underground transport or during a flight). When this happens Tradedoubler's SDK will store the action data locally. When the app is next launched the SDK will check for any stored actions and send them to Tradedoubler. This way you can be certain that all actions will be tracked.
This section covers the implementation of ADT and IAT on the iOS platform.
You should start by enabling the debug mode for the SDK to confirm that everything is running OK. Activate debug mode in your didFinishLaunchingWithOptions function:
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { //... [MobileSDK enableDebug]; //... }
Unzip the SDK and drag the Tradedoubler-SDK.framework folder into your Xcode project. Our SDK has dependencies on the following Apple frameworks that you also need to add.
CFNetwork.framework (required) Security.framework (required) SystemConfiguration.framework (required) AdSupport.framework (optional)
Within the project's Build Settings, set 'Architectures for Debug' to armv7 and (preferably) for Release to Standard Architectures (armv7, arm64) - $(ARCHS_STANDARD).
The custom URL is used to start your app from Safari or other apps. Open your project’s –Info.plist file and add a new URLScheme like this:
<key>NSAppTransportSecurity</key> <dict> <key>NSExceptionDomains</key> <dict> <key>tradedoubler.com</key> <dict> <key>NSIncludesSubdomains</key> <true/> <key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key> <true/> <key>NSTemporaryExceptionMinimumTLSVersion</key> <string>TLSv1.1</string> </dict> </dict> </dict>
In your app’s delegate class add the following code:
#import <Tradedoubler-SDK/MobileSDK.h> //... - (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url { [MobileSDK registerCustomUrlParameters:url]; return YES; }
This is the method that's called right after your app has been launched from another app (such as Safari) using the custom URL scheme you created in the previous section. It is very important this is called, as the SDK takes care of capturing parameters that are necessary for some of its core features.
Now you have everything in place to start looking at the code. At the start of the application we need to check if this app should be tracked or if this has already been done. Create a MobileSDK object and simply call its method trackDownloadAsLead (for a free app) or trackDownloadAsSale (for a purchased app) within your app delegate as shown below.
#import <Tradedoubler-SDK/MobileSDK.h> //... - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [MobileSDK enableDebug]; // Start of App Download Tracking NSString *organization = @"<ORG_NO>"; NSString *event = @"<EVENT_NO>"; NSString *secretCode = @"<SECRET_CODE>"; NSString *currency = @"EUR"; NSString *orderValue = @"1.49"; int timeout = 10; // in seconds BOOL trackAsSale = true; if(trackAsSale) { [MobileSDK trackDownloadAsSale:organization withEvent:event withSecretCode:secretCode withTimeout:timeout withCurrency:currency withOrderValue:orderValue]; } else { [MobileSDK trackDownloadAsLead:organization withEvent:event withSecretCode:secretCode withTimeout:timeout]; } // Your app code... }
Configure the parameters above as follows:
organization
, event
and secretCode
will be provided by Tradedoubler.currency
(3 letters) and orderValue
should be entered accordingly. The order value should be the price of the app in the App Store.testMode
can be used during testing. See Testing for information.timeout
controls the maximum time in seconds for the SDK to try to reach the trackback host. 10 seconds is acceptable for most cases.trackAsSale
should be set to true for 'paid-for' apps or false for free apps.This method will also check for any cached data and, if found, send it to Tradedoubler. This data will be for previous in-app actions that were not sent to Tradedoubler because there was no data connection at the time.
IAT rewards the publisher that generated the last click into your app.
Use the trackSaleWithAttributionToLastClick method to perform an in-app trackback. The orderNumber corresponds to the transaction and must be unique and generated by your system.
Note: The event ID here is not the same as for the ADT tracking.
NSString *organization = @"<ORG_ID>"; NSString *event = @"<EVENT_ID>"; NSString *orderNumber = @"<ORDER_NUMBER>"; NSString *code = @"<SECRET_CODE>"; NSString *currency = @"EUR"; NSString *orderValue = @"1.49"; NSString *voucherCode = @"MYVOUCHER"; int timeout = 10; // in seconds // The following code collects data about the basket contents // If you report product info in the Report Info parameter you need to include this. Otherwise it can be removed NSArray *prod1 = @[@"<Product_ID>", @"<Product_Name>", @"<Product_Price>", @"<Quantity>"]; NSArray *prod2 = @[@"<Product_ID>", @"<Product_Name>", @"<Product_Price>", @"<Quantity>"]; // ... NSArray *products = @[prod1, prod2]; // Update so data for all products is included [MobileSDK trackSaleWithAttributionToLastClick:organization withEvent:event withOrderNumber:orderNumber withSecretCode:code withTimeout:timeout withCurrency:currency withOrderValue:orderValue withVoucherCode:voucherCode withProducts:products];
To check if a deep link request exists you should issue the following method:
NSString *deepLink = [MobileSDK getLastClickDeepLink];
The method will return the deeplink URL if it exists or nil.
Please note the following:
The trackback will only be performed once so it can be hard to test your implementation several times. For testing purposes you can add a call to the method clearUniqueIdentifier which wipes the old trackback. Add [MobileSDK clearUniqueIdentifier];
before the trackDownload method.
The testMode flag can be used to force the SDK to use random identifiers in order to simulate multiple app installs. Every time the app is launched it will attempt to perform a trackback with a new device identifier.
Output similar to the following should show up in your log for ADT implementations. You can enable it in XCode by pressing shiftcmd-C:
2013-05-16 16:45:52.628 ADT-Demo2[6073:c07] [Tradedoubler]: trackDownloadAsSale called 2013-05-16 16:45:52.629 ADT-Demo2[6073:c07] [Tradedoubler]: trackDownloadAsLead called 2013-05-16 16:45:52.629 ADT-Demo2[6073:c07] [Tradedoubler]: Is connected, trying to reach host to perform ADT 2013-05-16 16:45:52.630 ADT-Demo2[6073:c07] [Tradedoubler]: Trying to reach host 'tbs.tradedoubler.com' on port 80 within 5 seconds. 2013-05-16 16:45:52.653 ADT-Demo2[6073:c07] [Tradedoubler]: Creating UUID: 2013-05-16 16:45:52.654 ADT-Demo2[6073:c07] [Tradedoubler]: Parameters: <,,1369579552.653554,> 2013-05-16 16:45:52.657 ADT-Demo2[6073:c07] [Tradedoubler]: Host was reachable, so now performing trackback in browser to URL 'http://hst.2013-05-16 16:45:54.229 ADT-Demo2[6073:c07] ****** handleOpenURL: scoopshot2://trackresult?programid=224788&affiliateid=2152864 ******* 2013-05-16 16:45:54.229 ADT-Demo2[6073:c07] [Tradedoubler]: Registering custom URL parameters from: scoopshot2://trackresult?programid=224788&2013-05-16 16:45:54.231 ADT-Demo2[6073:c07] [Tradedoubler]: Extracted parameters from trackback: 2013-05-16 16:45:54.231 ADT-Demo2[6073:c07] [Tradedoubler]: programid: xxxxxx 2013-05-16 16:45:54.231 ADT-Demo2[6073:c07] [Tradedoubler]: affiliateid: xxxxxxx 2013-05-16 16:45:54.232 ADT-Demo2[6073:c07] [Tradedoubler]: iattduid: 2013-05-16 16:45:54.233 ADT-Demo2[6073:c07] [Tradedoubler]: Storing parameters in keychain: 224788,2152864,1369579552.653554, 2013-05-16 16:45:54.237 ADT-Demo2[6073:c07] [Tradedoubler]: Will report SDK usage to [http://tbl.tradedoubler.com/report?organization=xxxxxxx&
Output similar to the following should show up in your log for IAT implementations:
2012-12-17 11:33:40.266 1.4.1-test[20048:c07] [Tradedoubler]: postDownloadTrackback called 2012-12-17 11:33:40.269 1.4.1-test[20048:c07] [Tradedoubler]: postDownloadTrackback: preparing trackback with values: 2012-12-17 11:33:40.269 1.4.1-test[20048:c07] [Tradedoubler]: uuid: 008F6B54-0C08-4BCF-B6E9-910DC5CFAA44 2012-12-17 11:33:40.270 1.4.1-test[20048:c07] [Tradedoubler]: appVersion: 10 2012-12-17 11:33:40.270 1.4.1-test[20048:c07] [Tradedoubler]: checksum: v04D9F15105A4C89FD8FD2B3C95CDC4830E 2012-12-17 11:33:40.270 1.4.1-test[20048:c07] [Tradedoubler]: program: xxxxxx 2012-12-17 11:33:40.271 1.4.1-test[20048:c07] [Tradedoubler]: affiliate: xxxxxxx 2012-12-17 11:33:40.271 1.4.1-test[20048:c07] [Tradedoubler]: currency: EUR 2012-12-17 11:33:40.271 1.4.1-test[20048:c07] [Tradedoubler]: orderValue: 1.49 2012-12-17 11:33:40.272 1.4.1-test[20048:c07] [Tradedoubler]: organization: xxxxxxx 2012-12-17 11:33:40.272 1.4.1-test[20048:c07] [Tradedoubler]: event: xxxxxx 2012-12-17 11:33:40.272 1.4.1-test[20048:c07] [Tradedoubler]: postDownloadTrackback: sending trackback: http://tbl.tradedoubler.com/report?orderNumber=1355740420&orderValue=1.49¤cy=EUR&checksum=v04D9F15105A4C89FD8FD2B3C95CDC4830E&program=xxxxxx&affiliate=xxxxxxx
This section covers the implementation of ADT and IAT on the Android platform.
To integrate Tradedoubler's app tracking capabilities within your Android app you will need the following:
The first thing you need to do is to put the tradedoubler-mobile-sdk-android-VERSION.jar in your classpath.
In your AndroidManifest.xml you need to add the following permissions:
android.permission.INTERNET android.permission.ACCESS_NETWORK_STATE
These permissions will allow the SDK to access the tracking servers.
You also need to add a receiver for the intent com.android.vending.INSTALL_REFERRER
(note that this must be your very first item within the application tag). Here's an example of the AndroidManifest.xml.
<?xml version="1.0" encoding="utf-8"?> <manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.tradedoubler.adtdemo" android:versionCode="1" android:versionName="1.0"> <uses-permission android:name="android.permission.INTERNET"/> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/> <application android:icon="@drawable/icon" android:label="@string/app_name"> <receiver android:name="com.tradedoubler.sdk.utils.ReferralListener" android:exported="true"> <intent-filter> <action android:name="com.android.vending.INSTALL_REFERRER" /> </intent-filter> </receiver> <activity android:name=".ADTDemo" android:theme="@android:style/Theme.NoTitleBar"> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter> </activity> </application> </manifest>
Now you have everything in place to start looking at the code. At the start of the application we need to check if this app should be tracked or if this has already been done.
Simply add the inner class DownloadTracker as below and create an object and execute it in your main activity's onCreate method. Make sure you modify its parameters as appropriate.
import com.tradedoubler.sdk.MobileSDK; //... @Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.main); // Replace with your own layout xml new DownloadTracker().execute(); } private class DownloadTracker extends AsyncTask{ @Override protected Void doInBackground(Void... params) { //Start of App Download Tracking String orgId = "<ORG_NO>"; String event = "<EVENT_NO>"; String secretCode = "<SECRET_CODE>"; String currency = "EUR"; String orderValue = "1.49"; boolean testMode = false; // Never set this to true in an app that goes into production int timeout = 10; // in seconds boolean trackAsSale = true; MobileSDK mobileSDK = MobileSDK.getInstance(this); if(trackAsSale) { mobileSDK.trackDownloadAsSale(orgId, event, secretCode, currency, orderValue, testMode, timeout); } else { mobileSDK.trackDownloadAsLead(orgId, event, secretCode, testMode, timeout); } return null; } }
Configure the parameters above as follows:
orgId
, event
and secretCode
will be provided by Tradedoubler.currency
(3 letters) and orderValue
should be entered accordingly. The order value should be the price of the app on Google Play.testMode
can be used during testing. See Testing for information.timeout
controls the maximum time in seconds for the SDK to try to reach the trackback host. 10 seconds is acceptable for most cases.trackAsSale
should be set to true for 'paid-for' apps or false for free apps.This method will also check for any cached data and, if found, send it to Tradedoubler. This data will be for previous in-app actions that were not sent to Tradedoubler because there was no data connection at the time.
IAT rewards the publisher that generated the last click into your app.
You must first add an intent filter to your main activity in order to enable a custom URL scheme for your app:
<intent-filter> <action android:name="android.intent.action.VIEW"/> <category android:name="android.intent.category.DEFAULT"/> <category android:name="android.intent.category.BROWSABLE"/> <data android:scheme="myapp"/> </intent-filter>
Make sure you change the scheme attribute to correspond to your app name (a-z without spaces). In the above example, the app would be launchable from a web page or another app using the URL myapp://
You must also feed the SDK with the necessary parameters that were sent to your app when launched with the custom URL scheme:
@Override public void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.main); // Add this MobileSDK mobileSDK = MobileSDK.getInstance(this); Intent intent = getIntent(); if (Intent.ACTION_VIEW.equals(intent.getAction())) { Uri uri = intent.getData(); mobileSDK.registerCustomUrlParameters(uri.toString()); } }
Now use the trackSaleWithAttributionToLastClick method to perform an in-app trackback. The orderNumber corresponds to the transaction and must be unique and generated by your system.
String organization = "<ORG_NO>"; String event = "<IN_APP_EVENT_NO>"; String orderNumber = "<ORDER_NUMBER>"; String secretCode = "<SECRET_CODE>"; String currency = "EUR"; String orderValue = "100.00"; String voucherCode = "MyVoucherCode"; boolean testMode = false; int timeout = 10; String [][] products = { { "<Product_ID>", "<Product_Name>", "<Product_Price>", "<Quantity>" }, { "<Product_ID>", "<Product_Name>", "<Product_Price>", "<Quantity>" } }; mobileSDK.trackSaleWithAttributionToLastClick(organization, event, orderNumber, secretCode, timeout,currency, orderValue, voucherCode, products);
Publishers may want to deep link to a specific area or page of your app rather than sending the user to a generic landing page. This method provides an improved user journey and increased conversion rates as users are driven to the product/area they requested rather than having to search again.
To check if a deep link request exists you should issue the following method:
String deepLink = mobileSDK.getLastClickDeepLink();
The method will return the deeplink URL if it exists or nil.
Please note the following:
The trackback will only be performed once so it can be hard to test your implementation several times. For testing purposes you can add a call to the method clearUniqueIdentifier which wipes the old trackback. Add mobileSDK.clearUniqueIdentifier();
before the trackDownload method:
The testMode flag can be used to force the SDK to use random identifiers in order to simulate multiple app installs. Every time the app is launched it will attempt to perform a trackback with a new device identifier.
Since testing requires you to put your app on Google Play we have created an app to simulate a download from Google Play. It is called "ReferralSimulator" and is shipped with the SDK. Install it like this:
cd path/
to point to the folder containing the ReferralSimulator.Now that the ReferralSimulator is installed you need to generate a TDUID. For initial testing you can set this to "testing" or something similar. This won't generate a valid lead or sale in our system but we can still see if the trackback is made. See the section "Generating valid leads and sales during testing" if you need to generate a valid lead or sale.
Now start your own app (not ReferralSimulator) once and then close it. This is necessary from Android 3.0 onwards to ensure the broadcast reaches the app.
Start ReferralSimulator, enter the TDUID into the app and press "Broadcast!". Then start your app. Our SDK makes your app listen to this broadcast and will detect the parameter. The parameter is then used to send the information back to Tradedoubler.
You can verify that the SDK is invoked by running 'adb logcat' from a terminal shell. You should see output like the following:
I/MobileSDK( 4673): ReferralListener: activated I/MobileSDK( 4673): Performed trackback: http://tbl.tradedoubler.com/report?organization= 1710346&event=260422&leadNumber=1037564e21b7c9cdb82&checksum= v04db5a1346ae60862c8c28444f449ab48f&tduid=3
If you haven't run the ReferralSimulator, the messages should look like:
I/MobileSDK( 5053): Did not attempt to trackback as the TDUID is missing (Queueing!)
If you use the ReferralSimulator for testing please note the following:
In order to generate a valid lead or sale you need a valid TDUID. The TDUID is generated by Tradedoubler when a user clicks on an affiliate link and is stored in a browser cookie. An affilliate link can look like this:
Click <a href="http://clk.tradedoubler.com/click?p(PROGRAM_ID)a(AFFILIATE_ID)g(AD_ID)">here</a> to generate the TDUID
When you click on a link like this a cookie called TradeDoublerGUID is set in your browser that contains the TDUID. You can extract this TDUID if you use Google Chrome's developer tools or the Firefox Firebug plugin. Enter this TDUID in the ReferralSimulator.
When packaging your app for distribution it's important to make sure that the SDK's class files inside its JAR file are included. You will probably package using one of these methods:
external.libs.dir=lib
<property file="build.properties"/>
The MobileSDK should automatically be included in the final APK without any configuration as long as the checkbox is marked under "Project Explorer -> Build Path -> Order and Export" for the library file 'tradedoubler-mobile-sdk-android-VERSION.jar'.
mvn install:install-file -Dfile=tradedoubler-mobile-sdk-android-<VERSION>.jar \ -DgroupId=com.tradedoubler.sdk - DartifactId=tradedoubler-mobile-sdk-android \ -Dpackaging=jar -DgeneratePom=true
com.tradedoubler.sdk tradedoubler-mobile-sdk-android LATEST compile
Details of the latest version of each SDK can be found below. Whenever you are updating your app check this section to make sure you have the latest version of the Tradedoubler SDK.
Operating System | Version | Change Log |
---|---|---|
iOS | 1.6.0 | Added support for Cookieless Tracking. Only a 64-bit SDK is available from this version forward as Apple now requires all apps (new or updated) to use this format. |
Android | 1.5.4 | Replaced the use of Android ID with Google Advertising ID. Added support for voucher code tracking, report info and offline tracking. |