Implementation guide for iPhone app download tracking

The iOS download tracking code utilizes the universal device identifier (UDID). We advise advertisers to review the recently revised iOS policies to determine if requesting the UDID in their applications is compliant with those policies.

This page will help you track downloads of your iOS app that are driven by AdMob advertising. Download tracking allows you to track the number of downloads, cost per download, and conversion rate for your iOS application advertising.  Download tracking works for applications on all iOS devices, including the iPad.

Download tracking requires an AdMob account. Register or log in at http://www.admob.com


Step 1: Create an iPhone ad

Create an iPhone ad to drive users to your app's page in the App Store.

1. Within a campaign, create an ad group of type "Application - Drive downloads of your app."  Choose either iPhone, iPad, or universal.  NOTE: Do not create a "Mobile Web" ad group to advertise an iOS app.  Download tracking will not work correctly with this type of ad group. 

2. In the App Store URL field, provide your App Store URL (you can find this by right-clicking on your App in the iTunes client and copying its URL). For example, for the Knots app, the App Store URL is:   

 http://itunes.apple.com/WebObjects/MZStore.woa/wa/viewSoftware?id=290888219&mt=8

There are several possible formats for an App Store URL.  Feel free to paste any format - our system will automatically convert the URL into a standard format.

3. After creating your ad, move on to Step 2: Report App Downloads below.

* NOTE: Please pause all ads until you have selected one of the conversion tracking options listed in Step 2.


Step 2: Report App Downloads

Report app downloads to AdMob. Downloads can be reported in three ways: 

Option 1-A: App Integration (Recommended & Preferred)

Would you like to drop a small code snippet into your app that will automatically report downloads to AdMob? Has your app already been released in the App Store?  Then this option is for you. 

1. Click the "Tools" tab, then "App Conversion Tracking". Choose the App you'd like to configure for tracking and click "Configure". An app will appear in this tab as soon as you've set up ads to advertise the app.

2. Choose the "App Integration" option. To integrate download tracking, follow the two steps on that page to paste two small snippets of code into your app.  The steps and code are also included here for convenience:

Add this line to your app delegate's applicationDidFinishLaunching: method:

  [self performSelectorInBackground:@selector(reportAppOpenToAdMob) withObject:nil];

Add these methods to your app delegate, replacing the string <APPLE ITUNES ID> with your app's iTunes id (provided by Apple):

// This method requires adding #import <CommonCrypto/CommonDigest.h> to your source file.
- (NSString *)hashedISU {
  NSString *result = nil;
  NSString *isu = [UIDevice currentDevice].uniqueIdentifier;
 
  if(isu) {
    unsigned char digest[16];
    NSData *data = [isu dataUsingEncoding:NSASCIIStringEncoding];
    CC_MD5([data bytes], [data length], digest);
 
    result = [NSString stringWithFormat: @"%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x",
           digest[0], digest[1], 
           digest[2], digest[3],
           digest[4], digest[5],
           digest[6], digest[7],
           digest[8], digest[9],
           digest[10], digest[11],
           digest[12], digest[13],
           digest[14], digest[15]];
    result = [result uppercaseString];
  }
  return result;
}

- (void)reportAppOpenToAdMob {
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init]; // we're in a new thread here, so we need our own autorelease pool
  // Have we already reported an app open?
  NSString *documentsDirectory = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory,
                                  NSUserDomainMask, YES) objectAtIndex:0];
  NSString *appOpenPath = [documentsDirectory stringByAppendingPathComponent:@"admob_app_open"];
  NSFileManager *fileManager = [NSFileManager defaultManager];
  if(![fileManager fileExistsAtPath:appOpenPath]) {
    // Not yet reported -- report now
    NSString *appOpenEndpoint = [NSString stringWithFormat:@"http://a.admob.com/f0?isu=%@&md5=1&app_id=%@",
                                 [self hashedISU], @"<APPLE ITUNES ID>"];
    NSURLRequest *request = [NSURLRequest requestWithURL:[NSURL URLWithString:appOpenEndpoint]];
    NSURLResponse *response;
    NSError *error = nil;
    NSData *responseData = [NSURLConnection sendSynchronousRequest:request returningResponse:&response error:&error];
    if((!error) && ([(NSHTTPURLResponse *)response statusCode] == 200) && ([responseData length] > 0)) {
      [fileManager createFileAtPath:appOpenPath contents:nil attributes:nil]; // successful report, mark it as such
      NSLog(@"App download successfully reported.");
    } else {
      NSLog(@"WARNING: App download not successfully reported. %@", [NSString stringWithData:responseData encoding:NSUTF8StringEncoding]);
    }
  }
  [pool release];
}

3. When you open your app for the first time after installing the code snippet, you should see the following message in your console: "App download successfully reported." If you do not see this message or if you receive a "WARNING: App download not successfully reported." message instead, follow step 2 to double-check your integration. The warning message should include information about what went wrong.

Note: after the first app download is successfully reported, subsequent app downloads will not be reported.


Option 1-B: App Integration with Site ID (Recommended & Preferred)

If your application has not yet been accepted to the App Store, it won't yet have an assigned app ID, but you can still integrate download tracking using an AdMob site ID as a placeholder. Follow steps A, B, and C below instead of steps 1, 2, and 3 above:

A. Register your app as a publisher with AdMob at http://www.admob.com/my_sites/create_site leaving the URL field blank.  Copy the site ID that's assigned to you so you don't forget it.  The Site ID should look similar to: a144faaf15d87bf.

B. Integrate the tracking code snippet as above, but replace the parameter 'app_id' with 'site_id' and copy and paste your newly created Site ID (a.k.a Publisher ID) in place of "<YOUR ADMOB SITE ID HERE>".  The steps are as follows: 

Add this line to your app delegate's applicationDidFinishLaunching: method:

  [self performSelectorInBackground:@selector(reportAppOpenToAdMob) withObject:nil];

Add these methods to your app delegate, replacing the string <YOUR ADMOB SITE ID HERE> with your app's site ID (the site ID should look similar to: a144faaf15d87bf):

// This method requires adding #import <CommonCrypto/CommonDigest.h> to your source file.
- (NSString *)hashedISU {
  NSString *result = nil;
  NSString *isu = [UIDevice currentDevice].uniqueIdentifier;

  if(isu) {
    unsigned char digest[16];
    NSData *data = [isu dataUsingEncoding:NSASCIIStringEncoding];
    CC_MD5([data bytes], [data length], digest);
 
    result = [NSString stringWithFormat: @"%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x%02x",
           digest[0], digest[1], 
           digest[2], digest[3],
           digest[4], digest[5],
           digest[6], digest[7],
           digest[8], digest[9],
           digest[10], digest[11],
           digest[12], digest[13],
           digest[14], digest[15]];
    result = [result uppercaseString];
  }
  return result;
}

- (void)reportAppOpenToAdMob {
  NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init]; // we're in a new thread here, so we need our own autorelease pool
  // Have we already reported an app open?
  NSString *documentsDirectory = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory,
                                  NSUserDomainMask, YES) objectAtIndex:0];
  NSString *appOpenPath = [documentsDirectory stringByAppendingPathComponent:@"admob_app_open"];
  NSFileManager *fileManager = [NSFileManager defaultManager];
  if(![fileManager fileExistsAtPath:appOpenPath]) {
    // Not yet reported -- report now
    NSString *appOpenEndpoint = [NSString stringWithFormat:@"http://a.admob.com/f0?isu=%@&md5=1&site_id=%@",
                                 [self hashedISU], @"<YOUR ADMOB SITE ID HERE>"];
    NSURLRequest *request = [NSURLRequest requestWithURL:[NSURL URLWithString:appOpenEndpoint]];
    NSURLResponse *response;
    NSError *error = nil;
    NSData *responseData = [NSURLConnection sendSynchronousRequest:request returningResponse:&response error:&error];
    if((!error) && ([(NSHTTPURLResponse *)response statusCode] == 200) && ([responseData length] > 0)) {
      [fileManager createFileAtPath:appOpenPath contents:nil attributes:nil]; // successful report, mark it as such
	  NSLog(@"App download successfully reported.");
    } else {
      NSLog(@"WARNING: App download not successfully reported. %@", [NSString stringWithData:responseData encoding:NSUTF8StringEncoding]);
    }
  }
  [pool release];
}

C. After your app has been accepted into Apple's App Store, edit the site you created in step 1 in order to add the App Store URL that you had initially left blank. To get this URL, simply right click on your app in the iTunes client and choose 'Copy iTunes Store URL'.  Go back into your AdMob account, click to the Sites & Apps tab, click "Manage Settings" on the site you created, click 'Edit', and add your App Store URL in the URL box.  Click 'Save Changes'.

As soon as you've entered this URL for the site, our system is able to link the placeholder site ID that you created with the actual app ID of the app, and we will begin tracking downloads within 12 hours.  


Option 2: Download API (For Advanced Users Only)

Use this option if you are already collecting ISU information and do not want to make code changes to your app. 

1. Click the "Tools" tab, then "App Conversion Tracking". Choose the App you'd like to configure for tracking and click "Configure". 

2. Choose the "Download API" option.

3. Run your campaign for a few minutes until some clicks have been generated

4. Pause the campaign

5. Ping our API with the ISU data you collect. The ISU data should be hashed using MD5 and then formatted as uppercase hex.  Note: Do not convert the ISU to uppercase before hashing, make sure only to convert the post-hash value to uppercase.

The pings made to our API endpoint should be in the following format: 

 http://a.admob.com/f0?isu=<MD5 HASHED ISU>&md5=1&app_id=<APPLE ITUNES ID>

If you choose to use a site ID, please use: 

 http://a.admob.com/f0?isu=<MD5 HASHED ISU>&md5=1&site_id=<PUBLISHER SITE ID>

6. Approximately 8-12 hours after your last ping to our endpoint, the Download Tracking status should change from "Pending" to "Running"

If after 12 hours the status is still "Pending", please check that you are posting the correct data to AdMob's endpoint: http://a.admob.com 


Option 3: Publish AdMob ads (For Publishers – May Show Limited Data**)

Use this option if you do not want to do any additional server side app integration AND you are already publishing AdMob ads in your app(s).
If you are not yet a publisher and wish to run AdMob ads please check out: http://helpcenter.admob.com

1. Please ensure that under the "Sites and Apps" tab you've already registered an iPhone App Site ID with your app store URL, have integrated AdMob's SDK into your application, and are showing live ads within your app. If you need instructions on how to do this, please click here

2. Click the "Tools" tab, then "App Conversion Tracking". 

3. Choose the App you would like to configure for tracking and click "Configure".

4. Choose the "AdMob Publisher" option and check the box next to the app you are currently running AdMob ads in.

** Data Limitations: AdMob will be unable to track all conversions if you do not show an ad to each user. For example: If only 10% of your users see an AdMob ad, we will probably only be able to report conversions on 10% of your total clicks and downloads.


Step 3: Monitor your downloads

Optimize your advertising spend by measuring results. 

You can find your download statistics along with your ad performance on http://www.admob.com by following these steps: 

1. Click on the "Tools" tab, and click "App Conversion Tracking". 

2. Select the app you'd like to track, and specify a date range. 

3. Reporting is broken down by app, by ad, or by day, and includes: ad cost, number of downloads, conversion rate, and cost per download.


FAQ

Q: How does iPhone download tracking work?
A: AdMob's iPhone download tracking enables you to see the amount users that downloaded your app as a result of your spend as an AdMob advertiser. Download tracking works as follows: 

1. A user clicks on an AdMob App Store ad. 

2. A user visits the App Store Info page and downloads the app. 

3. The app reports new downloads to AdMob. 

4. AdMob calculates the download rate and the cost per download for all apps reporting download information. 


Q: What sort of events can I track?
A: AdMob's iPhone Download tracking allows you to track how many times your application was downloaded from Apple's App store as a result of your AdMob ad spend.


Q: Is download tracking free?
A: Yes. 


  Q: How does AdMob define a trackable click?
A: In order for clicks on ads to be trackable, AdMob must have enough information about the devices they are being served on to register the click. AdMob is able to track clicks coming from inside applications but excludes those originating on the mobile web. If an ad does not result in a conversion over a 24 hour period the clicks on the ad will not be trackable.


Q: Do I have to be an AdMob advertiser to use download tracking?
A: Yes. We track downloads by remembering which users clicked on AdMob ads, which requires that you advertise with AdMob. 


Q: I'm an AdMob publisher. How do I set up download tracking for my app?
A: You should be all set! We'll automatically track downloads for each user to which you show an AdMob ad. Note, if you only show an ad to one in ten users, we'll only report on 10% of your total downloads, so be sure AdMob ads are requested on as many app opens as possible. If this is not the case, you may want to consider another integration option. 


Q: I don't want to make any code changes to my app. How do I set up download tracking?
A: AdMob's Download API enables developers to report back device identifiers (UDIDs). You must first hash these using md5 hashing for security. In order to use this option, you must first be collecting device identifiers from new app downloads and be able to report these back to AdMob on a daily basis via the API as specified above. 


Q: My app hasn't been accepted to the App Store. Can I still integrate download tracking?
A: Yes! You'll need to do one of the following: 

1. Register your app as a publisher with AdMob: http://www.admob.com/my_sites/create_site

2. Replace the parameter 'app_id' with 'site_id', using the id generated by AdMob above. It should be of the form: a144fsqf15d87bf


Q: How frequently can I make API pings to AdMob?
A: Pings can be made daily, however, we recommend that you ping the data to AdMob as often as possible.


Q: How do I know my API request was received?
A: The API response will return a confirmation for valid requests: 

 [true]

A true response confirms that we received your ping, but not that it was formatted correctly.


Q: How long before downloads will appear in my AdMob reporting?
A: Some download information may appear in under 24 hours. Final download data may take up to three days to appear in your reports. 


Q: What device identifier should I use?
A: The ISU provided to AdMob via the Download API must match the UIDevice uniqueIdentifier property, as documented here: 

http://developer.apple.com/iphone/library/documentation/UIKit/Reference/UIDevice_Class/Reference/UIDevice.html#//apple_ref/occ/instp/UIDevice/uniqueIdentifier

It is a persistent unique 40 character string per iPhone device that is also commonly referred to as the UDID.  We require that you md5-hash this value before sending it to us.  If you integrate our code snippets mentioned above, the md5-hashing will be done for you.


Q: What do the different states of Conversion Tracking represent (Not Configured, Pending, Running)?
A:
1. Not Configured - This signifies that a conversion tracking option has not been chosen.
2. Pending - This will change states to "Running" once AdMob registers the first conversion.
3. Running - This means that conversions are successfully being tracked and reported using the option you selected.


Q: Does AdMob provide any server side setup support?
A: Since this feature is for advanced users, AdMob does not provide help on setting up your server to post data to our API.


Wiresharking your iPhone App

Follow these steps to set up Wireshark to sniff iPhone applications on OS X -

Install (do once):

  1. Download Wireshark from http://www.wireshark.org/download.html .

Run (do each time you restart your computer):

  1. Give Wireshark access to sniff your network.
         1. Open the Terminal application and run the following commands:




               1. cd /dev
               2. sudo chmod a+r bpf*
               3. ls -l bpf*
         
         2. The last one should list a few bpf entries, and critically, in the permissions listing on the left, there should be three "r"s. 
   
   2. Share a wireless network
         1. Plug in an ethernet cable to your computer.
         2. Click on the Airport (wifi) icon at the top right of your operating system, select 'Create Network', and create a network with a distinctive name.
         3. Go to System Preferences, open the 'Sharing' preference pane, and highlight (but don't check yet) 'Internet Sharing'.
         4. Choose to share your connection from Ethernet.
         5. Choose to share your computers using AirPort.
         6. Click AirPort Options and type in the name of network you created in step 2. 
         7. Check the box next to 'Internet Sharing'.
         8. Click Start.
         9. Connect your iPhone or iPod Touch to the Wifi network you created in step 2.




   3. Launch Wireshark. (It may launch slowly the first time.) Click OK if it pops up an error.




   4. Configure Wireshark to only look at HTTP traffic from your wireless card by following these steps:
         1. Click Capture Options (or go to the menu item Capture -> Options).
         2. Choose Interface "en1". (This is likely to be your wireless card. If not, please use trial and error to find the right interface.)
         3. Click Capture Filter.
         4. Choose HTTP TCP port (80) from the list, click OK.
         5. Click Start. Wireshark is now monitoring your traffic! 




   5. If you want to filter to see only the stuff you want, follow these steps
         1. Click Filter.
         2. Click +Expression.
         3. Add something similar to 'field name:http host' contains value:"admob" or whatever else you'd like to filter out.




After following the steps above, on your iPhone go to Settings -> Wi-Fi -> turn Wi-Fi ON -> find and join the network you created above. Then download a new copy of your application on the device and watch Wireshark capture all the packets that are sent back and forth. Any traffic sent to AdMob can be seen through the packets captured.


If you have integrated our download tracking code properly, wireshark should show something similar to the following when filtering out for http host admob:

        Hypertext Transfer Protocol
   GET /f0?isu=489D43B97061E1E732C1D24E26B57E05&md5=1&app_id=123456789 HTTP/1.1\r\n
        GET /f0?isu=489D43B97061E1E732C1D24E26B57E05&md5=1&app_id=123456789 HTTP/1.1\r\n
           [Message: GET /f0?isu=489D43B97061E1E732C1D24E26B57E05&md5=1&app_id=123456789 HTTP/1.1\r\n]
       Request Method: GET
       Request URI: /f0?isu=489D43B97061E1E732C1D24E26B57E05&md5=1&app_id=123456789
       Request Version: HTTP/1.1
   Host: a.admob.com\r\n