Universal Application Tracking

From MdotM API
Jump to: navigation, search

MdotM offers advertising clients device ID-based tracking for iOS apps and both device ID-based and non-device ID-based tracking for Android applications.

iOS tracking:

  1. Device ID-based Method: client or server-to-server code relays identifierForAdvertising device IDs to run on in-app traffic with 100% accuracy

Android tracking:

  1. Universal Android Referrer Method, which involves passing a "referrer" into a Google Play URL and receiving the referrer from the application upon download completion.
  2. Device ID-based method involves passing Google Advertising ID and/or AndroidID.

For best results, combine both methods.

You use the MdotM dashboard to review and/or use the GetConversions API to retrieve all download events.

With the Android Referrer Method, advertisers can do download attribution tracking from ANY source, and does not involve UDIDs or persistent Device IDs, which is important due to Apple's Deprecation of UDIDs and privacy considerations.

  1. You generate MdotM Universal Tracking Link from the MdotM dashboard, e.g.
    http://ads.mdotm.com/ads/c.php?uc=61370&utm_source=facebook&utm_campaign=fbpage&utm_medium=social&utm_content=6018702139&subid=%ourrefid%
    and supply it to your media partners (e.g. Google Adwords, Millennial Media) or use on your mobile site or email campaign;
  2. User clicks on MdotM Universal Tracking Link, where MdotM generates the device token (Note: No Device ID is required for this step)
  3. User downloads and installs your application
  4. Real-time information about individual conversions are fired to the Advertiser Postback URL and Publisher Postback URL
  5. You use the MdotM dashboard to review and/or use the GetConversions API to retrieve all download events


iOS Conversion Tracking

Sample postback URL: http://ads.mdotm.com/ads/trackback.php?appid=&aid=&ate=&usertoken=&eventID=&advid=&clickid=

Required parameters: appid and {aid or clickid}

  • appid: 9 digit numeric Apple app ID
  • aid: user's advertisingIdentifier
  • ate: user's advertisingTrackingEnabled
  • usertoken: ID supplied by advertiser for user quality/RPU analysis
  • eventID: use "install" for first launch events. For post-install events, this value must match the event ID inputted in the campaign funnel. Default in campaign funnel is "Purchase".
  • advid: use the email address that's registered in your account
  • clickid: ID provided by MdotM that's generated on the click

iOS Client-Side Code

When reporting install events to MdotM, call this method to relay device identifiers from your app to MdotM:

// replace [ADVID] and [APPID] below
- (void)reportAppOpenToMdotM {
 NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init]; 
 NSString *eventID = @"install";
 NSString *usertoken = @"yourusertoken"; // supply your own user token, using e.g. identifierForVendor or CFUUIDCreate
 NSString *aid = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];
 NSString *ate = [[ASIdentifierManager sharedManager] isAdvertisingTrackingEnabled] ? @"1" : @"0";
 NSString *appOpenEndpoint = [NSString stringWithFormat:@"http://ads.mdotm.com/ads/trackback.php?advid=%@&aid=%@&ate=%@&usertoken=%@&appid=%@&eventID=%@", @"[ADVID]", aid, ate, usertoken, @"[APPID]", eventID];
 NSURLRequest *request = [NSURLRequest requestWithURL:[NSURL URLWithString:appOpenEndpoint]];
 NSURLResponse *response;
 NSError *error = nil;
 NSData *responseData = [NSURLConnection sendSynchronousRequest:request returningResponse:&response error:&error];
 [pool release];
}

Parameters defined above in #iOS_Conversion_Tracking.

iOS Server-to-Server Code

If the advertiser has not installed MdotM's SDK, MdotM also accepts server-to-server pings for each install event.

Sample server-to-server tracking code:

$advid = "you@yourcompany.com";  // your mdotm email login
// your application id (eg "1234432112") which for your iPhone app, you can find in your apps iTunes URL
$appid = "yourappid";  
$eventID = "install";
//  your iPhone app sends:
// see iOS ASIdentifierManager https://developer.apple.com/library/ios/#documentation/AdSupport/Reference/ASIdentifierManager_Ref/ASIdentifierManager.html 
// $aid = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];
// $ate = [[ASIdentifierManager sharedManager] isAdvertisingTrackingEnabled] ? @"1" : @"0";
// $usertoken = "yourusertoken";   --  We recommend you use the CFUUIDCreate or identifierForVendor function to create a UUID for your userToken parameter
$trackbackurl = "http://ads.mdotm.com/ads/trackback.php?advid=".urlencode($advid)."&aid=".urlencode($aid)."&ate=".urlencode($ate)."&appid=".$appid."&eventID=".$eventID."&usertoken=".$usertoken;
$trackbackresult = file_get_contents($trackbackurl); // the result is a JSON object

Parameters defined above in #iOS_Conversion_Tracking.

iOS Post Install Tracking

Populate the "eventID" parameter in your postback URL with custom values to track post-install events. Input a corresponding event ID in the campaign funnel for each different value used in the "eventID" parameter.

Post-install events are sent server-to-server. When using deviceID-based tracking, call this url:

http://ads.mdotm.com/ads/trackback.php?appid=&aid=&ate=&usertoken=&eventID=&advid=&value=&clickid=

Required parameters: appid, eventID, and {aid or clickid}

Parameters defined above in #iOS_Conversion_Tracking.

Android Conversion Tracking

Sample postback URL: http://ads.mdotm.com/ads/receiver.php?referrer=&package=&gaid=&ate=&androidid=&advid=&clickid=&eventID=&value=
  • referrer: referrer string collected from Google Play
  • package: app ID found in Google Play's URL
  • gaid: user's Google Advertising ID
  • ate: user's Advertising Tracking Enabled setting. If true set to 1. If false set to 0.
  • androidid: user's Android ID
  • advid: use the email address that's registered in your account
  • clickid: ID provided by MdotM that's generated on the click
  • eventID: must match event ID inputted in campaign funnel. Default is "purchase".
  • value: additional numerical data for post install events, such as revenue

Android Client-Side Code

NOTE: Starting Nov. 1, 2013

While developing application to retrieve the new Google Advertising ID you need a Google play service SDK.

1. You set up your Android application to relay referrers to MdotM.
Step A: Add this to your manifest url:

<receiver android:name="com.atminn.urbanroundup.MdotmReceiver" android:exported="true" >
  <intent-filter>
    <action android:name="com.android.vending.INSTALL_REFERRER" />
  </intent-filter>
</receiver>

replacing "com.atminn.urbanroundup.MdotmReceiver" with your packagename, i.e. "com.mycompany.myapp.MdotmReceiver"


Next, add the below meta data inside the <application></application> tag of your application manifest file

  <application>
        <meta-data  android:name="com.google.android.gms.version"  android:value="@integer/google_play_services_version" />
   </application>


In addition, you must also add the following permissions, if you haven't already:

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

Step B: Add this MdotmReceiver.java class to your project, replacing "com.atminn.urbanroundup" with your package name at the top:

package com.atminn.urbanroundup;

import java.net.URLEncoder;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.DefaultHttpClient;
import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;
import android.telephony.TelephonyManager;
import android.provider.Settings;
import com.google.android.gms.ads.identifier.AdvertisingIdClient;
import com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
import com.google.android.gms.common.GooglePlayServicesAvailabilityException;
import com.google.android.gms.common.GooglePlayServicesNotAvailableException;
import java.io.IOException;

public class MdotmReceiver extends BroadcastReceiver {
    public String postBackUrl = "";
    public String deviceId = "0";
    public String androidId = "0";
    public String gaid = "";
    public String ate = "";
    @Override
    public void onReceive( Context context, Intent intent ) {
      String referrer = "";
      try {
        referrer = intent.getStringExtra( "referrer" );
        if ( referrer == null ) {
	  referrer = "null_referrer_found";
        }
      } catch(Exception e) {
        referrer = "exception_found_retrieving_referrer";
      }

      try {
        final TelephonyManager telephonyManager = (TelephonyManager) context.getSystemService(Context.TELEPHONY_SERVICE);
        deviceId = telephonyManager.getDeviceId();
        if ( deviceId == null ) deviceId = "0";
      } catch(Exception e) {
        deviceId = "0";
      }

      try {
        androidId = Settings.Secure.getString(context.getContentResolver(), Settings.Secure.ANDROID_ID);
        if ( androidId == null ) androidId = "0";
      } catch(Exception e) {
        androidId = "0";
      }

      Info adInfo = null;
      boolean isLAT = false;
      try {
	 adInfo = AdvertisingIdClient.getAdvertisingIdInfo(context.getApplicationContext());
      } catch(GooglePlayServicesNotAvailableException e) {
	 // Google Play services is not available entirely.
      } catch(IOException e) {
        // Unrecoverable error connecting to Google Play services (e.g., the old version of the service doesn't support getting AdvertisingId).
      } catch(IllegalStateException e) {
	// This exception occurs when we run this code on main/UI  thread. So do run it on separate thread 
      } catch(GooglePlayServicesRepairableException e) {
	// Google play service needs update
      }

      if ( adInfo != null ) {
         gaid = adInfo.getId();
	 isLAT = adInfo.isLimitAdTrackingEnabled();
      } 

      if ( isLAT ) { 
        ate = "1";
      } else {
        ate = "0";
      }

      String packageName = "";
      Context applicationContext = context.getApplicationContext();
      if ( applicationContext == null ) {
        packageName = "null_package";
      } else {
        packageName = applicationContext.getPackageName();
      }

      postBackUrl = "http://ads.mdotm.com/ads/receiver.php?referrer=" + URLEncoder.encode( referrer ) + "&package=" + URLEncoder.encode( packageName ) + "&gaid=" + URLEncoder.encode(gaid) + "&ate=" + ate + "&deviceid=" + URLEncoder.encode(deviceId) + "&androidid=" + URLEncoder.encode(androidId);
      makePostBack.start();
    }

    private Thread makePostBack = new Thread() {
      public void run() {
        try{
          HttpClient httpClient = new DefaultHttpClient();
          HttpGet httpGet = new HttpGet( postBackUrl ); 
          httpClient.execute(httpGet);
        } catch(Exception e) {
          return;
        }
      }
   };
}

Note: Android doesn't permit the use of multiple INSTALL_REFERRERs in the manifest. If you wish to have multiple receivers listen for the INSTALL_REFERRER, you will need to create your own custom receiver and call the onReceive functions for both from the custom receiver's onReceive function.

For example, it would be something like:

public class CustomReceiver extends BroadcastReceiver {
  @Override
   public void onReceive( Context context, Intent intent ) {
     ...
     ...
     MdotMReceiver.onReceive();
     OtherReceiver.onReceive();
     ...
     ...
   }
}

2. Upload your application to the Android Market!

Note: The only way to test these trackbacks is by uploading the updated app to the Android Market and simulate a download. Upon simulation of the download, we can check on our end as to whether we saw the trackback.

3. When new app user clicks on your MdotM ad, the user is be taken to the Android Market URL with additional referrer parameter, such as:

market://details?id=com.atminn.urbanroundup&referrer=utm_source%3D12345%26utm_medium%3Dmdotm%26utm_campaign%3D6789%26utm_content%3D123abcdef

We'll take care of all the referrer information -- you just need to let us know your package name.

4. When a user downloads your Android application, your application sends this referrer information back to MdotM. If MdotM finds a match between your referrer information and a click generated by MdotM, an install is recorded! This works in close to real-time, with 1-5 minute delays.

Parameters defined above in #Android_Conversion_Tracking.

Android Server-to-Server Code

Sample postback URL: http://ads.mdotm.com/ads/receiver.php?referrer=&package=&gaid=&ate=&androidid=&deviceid=&advid=&clickid=

Required parameters: package and {androidid, gaid, deviceid, clickid, or referrer}

Parameters defined above in #Android_Conversion_Tracking.

// $referrer sent to your servers
// $gaid sent to your servers
// $ate sent to your servers
// $deviceid sent to your servers:
//   your Android app sends: telephonyManager.getDeviceId()
// $androidid sent to your servers

// your application id which for
//  your Android app ("com.yourcompany.yourapp"), you can find in the Android manifest/Market URL  

$appid = "yourappid";  
$trackbackurl = "http://ads.mdotm.com/ads/receiver.php?referrer=".urlencode( $referrer )."&package=".urlencode( $appid )."&gaid=".urlencode($gaid)."&ate=".urlencode($ate)."&deviceid=".urlencode($deviceId)."&androidid=".urlencode($androidid)&advid=".urlencode($advid)&clickid=".urlencode($clickid);
$trackbackresult = file_get_contents($trackbackurl); // the result is a JSON object

Testing Referral Tracking

The definitive test is to submit the application to the market, construct a URL with a uniquely identifiable referrer and download from Google Play. This isn’t always practical during development so an alternative way to do this is to use adb to send the installation intent. Once connected via adb shell the following command will send the intent:

am broadcast -a com.android.vending.INSTALL_REFERRER -n your.pacakage.name.here/.ReferralReceiver --es "referrer" "utm_source=test_source&utm_medium=test_medium&utm_term=test_term&utm_content=test_content&utm_campaign=test_name"


Android Post Install Tracking

Populate the "eventID" parameter in your postback URL with custom values to track post-install events. Input a corresponding event ID in the campaign funnel for each different value used in the "eventID" parameter.

Post-install events are sent server-to-server by calling this url:

http://ads.mdotm.com/ads/receiver.php?package=&gaid=&ate=&androidid=&deviceid=&eventID=&advid=&value=&clickid=

Required parameters: package, eventID, and {androidid, gaid, deviceid, or clickid}

Parameters defined above in #Android_Conversion_Tracking.

MdotM Unity Plug-In for Install Tracking

Advertisers that use Unity may download the Unity plugin for MdotM Install Tracking from the URLs below

iOS has two methods exposed (reportAppOpenWithAppleId and registerAppEvent) and Android pings are handled via the manifest file.

Conversion Tracking when using clickID ONLY

If your system cannot pass an appid (iOS) or package name (Android), MdotM can track using just a click ID.

If your system *can* pass an appid or package name, please use #iOS_Conversion_Tracking or #Android_Conversion_Tracking as outlined above.

When a user clicks on an ad, MdotM would call your servers with a 32-character string unique to that click and passed to the parameter of your choice, e.g:

http://m.yoursite.com/page?clickid=[CLICKID]

You can relay conversion events back to MdotM by firing one of the following pixels:

http://ads.mdotm.com/ads/conversion.php?email=your@email.com&secretKey=yoursecretkey&clickid={yourMacroForClickID}

https://secure.mdotm.com/ads/conversion.php?email=your@email.com&secretKey=yoursecretkey&clickid={yourMacroForClickID}

[CLICKDID] is a randomly generated unique 32-character string specific to each click.

To implement this on your server, you must store the click ID in the from the point they land on your page until the conversion event takes place.

For Third party Tracking (Hasoffers, Ad-X, Kochava), see Third Party Tracking for more information.

Advertiser Postback URLs

When MdotM records a valid conversion, an advertiser or publisher can be notified via their postback URL in real time using a HTTP GET call. A popular use of the postback URL is to return a usertoken that can be used for user quality/RPU analysis. Advertisers can set their Advertiser Postback URL in Your Account > Your Profile.

MdotM supports macros that can be used to dynamically populate postback URL parameters. These macros are always enclosed in curly braces.

Sample postback URL: http://example.com/postback/?adgroup={adgroupID}&ts={conversionDT}&usertoken={usertoken}

The following macros can be used in your postback URL:

  • {clickID} - MdotM-generated clickID
  • {appid} - iTunes 9 digit numeric ID, or Google Play ID
  • {clickDT}- time of click, in PST
  • {clickTS} - time of click, in UNIX style
  • {conversionDT} - time of conversion, in PST
  • {conversionDateTime} -
  • {conversionTS} -
  • {price} -
  • {clientIP} - user's client IP address
  • {adtype} -
  • {campaignCode} -
  • {partnerkey} -
  • {utm_source} -
  • {utm_medium} -
  • {utm_campaign} -
  • {utm_content} -
  • {utm_term} -
  • {odin} -
  • {openudid} -
  • {usertoken} - ID supplied by advertiser for user quality/RPU analysis
  • {aid} - user's advertisingIdentifier, if provided on install by advertiser
  • {gaid} - user's Google Advertising ID, if provided on install by advertiser
  • {sha1aid} -
  • {md5aid} -
  • {ate} - user's advertisingTrackingEnabled (iOS), or user's isLimitTrackingEnabled (Android) value, if provided on install by advertiser
  • {deviceid} - user's AndroidID, if provided on install by advertiser
  • {sha1deviceid} - sha1 hash of the deviceid
  • {md5deviceid} - md5 hash of the deviceid
  • {countryCode} - user's 2-digit countryCode (e.g. "US", "GB", ...)
  • {device} - user's device at click (e.g. "iPhone", "iPod", "iPad", "Android")
  • {os} - user's OS at click (e.g. "4.0")
  • {secretkey} -
  • {signature} -
  • {adID} - ID of the ad/creative that the install belongs to
  • {adGroupID} - ID of the adgroup that the install belongs to
  • {campaignID} - ID of the campaign that the install belongs to
  • {adName} -
  • {subid} - SubID passed by publisher - any string
  • {subid2} - yet another SubID passed by publisher - any string
  • {subid3} - yet another SubID passed by publisher - any string
  • {subid4} - yet another SubID passed by publisher - any string
  • {subid5} - yet another SubID passed by publisher - any string
  • {subid6} - yet another SubID passed by publisher - any string

For non-real-time conversion information, advertisers can retrieve all conversions using the GetConversions API.