Conversion Tracking

From mkMob Developer Wiki
Jump to: navigation, search

API Overview

The mkMob conversion tracking API allows you to track both app installs and other types of conversion events that result from running your mobile advertising campaigns on the mkMob Platform. Once you are setup to post-back conversion data to our API, you will be able to see the total amount of conversions, cost per conversion and other useful information directly in your mkMob client panel.

Once conversions are being logged, you will be able to optimize your campaigns to match your CPA/CPI goal by excluding poor-performing Devices, OS and/or Locations from your campaigns.



API Details

You must call the mkMob Conversion tracking API using either a HTTP POST or HTTP GET request. Advertisers should provide conversion information to mkMob at the conversion endpoint.

https://ads.mkmob.com/conversion.asm?{requestParameters}

Parameters to Send

The following parameters need to be sent:

Parameter

Required?

Description

apikey Yes An unique API key that maps to your account. To get an API key, login to your Client Control Panel. Next, click the API tab, then click Generate API Key.
click_id Yes A Click Id is an unique variable generated by mkMob when a click happens. This is automatically generated by mkMob. You do not have to make any changes at your end. Just add click_id parameter as mentioned here.

Example: GET Method

https://ads.mkmob.com/conversion.asm?apikey=838c1eec0bf2554d7a9210ca0d985e2ee213f1d7&click_id=2a2e6bf3666d766c0a0c0b643c946dee4aec73a42300eba5-a53c-4f00-aa46-fe7862723cbc248340873539948de2e7cf9.11645688

API Response

The API will respond with a JSON encoded response body as follows:

Success JSON response:

{
 "status":"OK",
 "message":"Success",
}

Failure JSON response:

{
 "status":"error",
 "message":"error_message",
}

Note:

  • Only one conversion event will be allowed per Click ID. Any other call made with the same Click ID after a conversion has already been recorded will fail.
  • A conversion event for a CPC or CPM campaign must be posted to the API within 1 hour after the time the campaign was viewed by the user. For CPA/CPI/CPL/CPS campaigns, the conversion event should be posted to the API within 12 hours after the time the campaign was viewed by the user.


Android App Install- Google Play Store

Tracking your app conversions in Google Play Store is now child's play. To track conversions generate by your mkMob campaigns:

  1. You will have to add some code snippets to your Android Application. The main files that need to be modified are the BroadcastReceiver and Manifest file. Once you have made the changes in your app, you should update it in the Google Play store.
  2. Create a campaign promoting your Android app in mkMob
  3. Append &referrer=click_id%3D%CLICKID% at the end of your Google Play URL. This is very important.
  4. Once your campaign starts getting clicks and your app is downloaded from Google Play store, the conversion numbers will start to updated in the mkMob Client Panel.


App-2-Server installation Code for Android App Install Tracking

Step 1 – Add the code snippet below in your BroadcastReceiver file

Step 2 - In the code snippet, replace the text, YOUR-MKMOB-API-KEY, with your mkMob account API Key. THIS IS VERY IMPORTANT!

@Override
	public void onReceive(Context context, Intent intent) {
		try {
			if (intent.getAction().equals("com.android.vending.INSTALL_REFERRER")) {
				Bundle extras = intent.getExtras();
				String referrerString = extras.getString("referrer");
				if (referrerString != null && !referrerString.equals("")&& referrerString.contains("click_id")) {
					Map<String, String> referralParams = new HashMap<String, String>();
					referrerString = URLDecoder.decode(referrerString, "UTF-8");
					String[] params = referrerString.split("&");
					for (String param : params) {
						String[] pair = param.split("=");
						referralParams.put(pair[0], pair[1]);
					}
					String click_id = referralParams.get("click_id");
					if (click_id != null && !click_id.equals(""))
						sendData(context, click_id);
				} else {
					Log.i("TrackingReceiver", "Referrer is null.");
				}
			}
		} catch (Exception e) {
			Log.e("TrackingReceiver", "Error: " + e.getMessage());
		}
 
	}
 
	// check the internet connection
	private static boolean isConnected(Context context) {
		try {
		    ConnectivityManager connectivityManager = (ConnectivityManager) context.getSystemService(Context.CONNECTIVITY_SERVICE);
			if (connectivityManager != null && (connectivityManager.getActiveNetworkInfo().isConnected())) {
				return true;
			} else {
				return false;
			}
		} catch (Exception exception) {
			Log.e("TrackingReceiver", "Internet connection not available");
			return false;
		}
 
	}
 
	// send data to mkMob's API.
	private static void sendData(Context context, String click_id) {
		final List<NameValuePair> list = new ArrayList<NameValuePair>();
		list.add(new BasicNameValuePair("click_id", click_id));
		list.add(new BasicNameValuePair("apikey", "YOUR-MKMOB-API-KEY"));
		Log.i("TrackingReceiver", "Values: " + list);
		if (!isConnected(context))
			return;
		Thread thread = new Thread(new Runnable() {
			@Override
			public void run() {
				try {
					HttpClient httpclient = new DefaultHttpClient();
					HttpPost httppost = new HttpPost("https://ads.mkmob.com/conversion.asm");
					httppost.setEntity(new UrlEncodedFormEntity(list));
					BasicHttpParams basicHttpParams = new BasicHttpParams();
					httppost.setParams(basicHttpParams);
					HttpConnectionParams.setConnectionTimeout(basicHttpParams, 15000);
					HttpConnectionParams.setSoTimeout(basicHttpParams, 10000);
					HttpResponse response = httpclient.execute(httppost);
					int code = response == null ? 0 : response.getStatusLine().getStatusCode();
					Log.i("TrackingReceiver", "Status code: " + code);
					if (code == 200) {
						String string = EntityUtils.toString(response.getEntity());
						Log.i("TrackingReceiver", "Response: " + string);
					}
				} catch (UnsupportedEncodingException e) {
					Log.e("TrackingReceiver", "UnsupportedEncodingException: "+ e.getMessage());
				} catch (Exception e) {
					Log.e("TrackingReceiver", "Exception: " + e.getMessage());
				}
			}
		});
		thread.start();
	}
Step 3 – Editing Your Manifest File

1: Add the below intent filter in your receiver:

<intent-filter>
<action android:name="com.android.vending.INSTALL_REFERRER" />
</intent-filter>

Example:

<receiver android:name="<Receiver file Name>" android:exported="true" >
<intent-filter>
<action android:name="com.android.vending.INSTALL_REFERRER" />
</intent-filter>
</receiver>

2: Add the following Permissions in Manifest:

<!-- Required permissions for app conversion tracking -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />


Mobile Web Conversions

Sometimes, the content you are promoting might be a Mobile Web page or some other content on the Mobile Web such as, a registration or a purchase. With the mkMob Conversion Tracking API, tracking Mobile-Web conversions is as easy as 1-2-3. The implementation steps are:

  1. Add the following Javascript code at the bottom of your conversion page.
    <script type="text/javascript" id="mkmob-cs" data-api-key="YOUR-MKMOB-API-KEY" src="//cdn.mkmob.com/ad/InvokeTracking.js"></script>
  2. Replace the text YOUR-MKMOB-API-KEY with your mkMob Account API Key. THIS IS VERY IMPORTANT!
  3. Create a campaign promoting your Mobile-Web link in mkMob.
  4. Append ?click_id=%CLICKID% at the end of your landing page URL. This is very important.
  5. Ensure that you pass the ?click_id= variable to your conversion page in the URL. This is the same page on which you put the above tag.
  6. Once your campaign starts getting clicks and conversions start happening in your Mobile Website, the conversion numbers will start to update in the mkMob Client Panel.


Additional Instructions

  • The following is a Known Issue in campaign tracking SDK by Google:
    • Only one BroadcastReceiver class can be specified per app. Should you need to incorporate two or more BroadcastReceivers from different SDKs, you will need to create your own BroadcastReceiver class that will receive all broadcasts and call the appropriate BroadcastReceivers for each type of broadcast.
  • A fully functional Google Play URL with custom tracking parameters will be as follows:
https://play.google.com/store/apps/details?id=com.app.demo&referrer=click_id%3D%CLICKID%