Integration Steps

The features described on this page are only available for these types of Display Network campaigns: Mobile app installs, Mobile app engagement, and Ads in mobile apps. They are not available for other campaign types, like Universal App Campaigns, search campaigns, or campaigns that show on websites within the Google Display Network.

The AdWords Conversion Tracking SDK is a lightweight SDK with two main purposes.

First, it allows you to measure the effectiveness of your AdWords app promotion campaigns and ads that deep link into your app using Universal Links. You can tag the events you'd like to track in your app, then log in to AdWords to see how many of these conversions are being driven by your advertising. Learn more.

Second, the SDK can also be used to tag user activity in your app, so you can reach certain users with ads that re-engage them with your app later on. For example, you might want to target app re-engagement ads to users who downloaded your app but haven't used it recently.

The default integration of the AdWords Conversion Tracking SDK--described below--collects data about new app installs so you can see the cost-per-install performance of your AdWords advertising. It also collects information about app upgrades and app usage after the install. This post-download usage data allows AdWords to optimize your advertising. This data will also allow you to remarket to these segments of your existing user base with app re-engagement ads if you choose to set up remarketing later on in your AdWords account:

  • All users who have your app installed
  • People who did or didn't use the app recently
  • People using specific app versions

To target even more specific audiences, you can also tag custom events in your app (e.g., purchases or progress in a game) for remarketing use. This will allow you to reach users who have completed those actions with re-engagement ads later on. Custom remarketing is described here.

Usage and disclosure

Check the Personalized advertising policy to find out which sensitive categories of sites or apps can't use remarketing, and what you need to add to your site's or app's privacy policy.

If you'd like, you can disable the collection of post-download usage data by calling [ACTAutomatedUsageTracker disableAutomatedUsageReportingWithConversionID:(NSString *)conversionID] for each conversion ID used in your application (usually you'll only have one conversion ID).

Add the app download conversion snippet

Define an iOS mobile app conversion in your AdWords account. You'll be given a snippet that looks like this:

[ACTConversionReporter reportWithConversionID:@"MY_ID" label:@"MY_LABEL" value:@"MY_VALUE" isRepeatable:NO];

Add the snippet that was provided in your AdWords account to the application:didFinishLaunchingWithOptions: method, found in your app's AppDelegate.

// ConversionExampleAppDelegate.m

#import "ConversionExampleAppDelegate.h"
#import "ACTReporter.h"

@implementation ConversionExampleAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

  // Enable automated usage reporting.
  [ACTAutomatedUsageTracker enableAutomatedUsageReportingWithConversionID:@"0123456789"];

  [ACTConversionReporter reportWithConversionID:@"0123456789" label:@"abCDEFG12hIJk3Lm4nO" value:@"0.99" isRepeatable:NO];
  return YES;
}

@end

reportWithConversionID: takes the following arguments from a pre-filled snippet in your AdWords account:

  • an ID that identifies your conversion
  • an alphanumeric label that identifies your conversion
  • the value of your conversion
  • a boolean to indicate whether the conversion should fire only once or should fire multiple times. We pre-populate the appropriate value for you and strongly recommend leaving the default value unchanged.

Track application usage

To record the most accurate application usage data, you should also put the following code in your app's didFinishLaunchingWithOptions method:

// Enable automated usage reporting.
[ACTAutomatedUsageTracker enableAutomatedUsageReportingWithConversionID:MY_CONVERSION_ID];

On the other hand, if you'd like to opt out of transmitting application usage data to AdWords, just call the following method before any conversion or remarketing reports are made:

// Disable automated usage reporting for a single conversion ID.
[ACTAutomatedUsageTracker disableAutomatedUsageReportingWithConversionID:MY_CONVERSION_ID];

To measure in-app events as conversions for all campaigns, including those using Universal Links, you must add the following snippet to your app's application:continueUserActivity:restorationHandler method.

- (BOOL)application:(UIApplication *)application
    continueUserActivity:(NSUserActivity *)userActivity
      restorationHandler:(void (^)(NSArray *_Nullable))restorationHandler {
  if (userActivity.activityType == NSUserActivityTypeBrowsingWeb) {
    [ACTConversionReporter reportUniversalLinkWithUserActivity:userActivity];
    return YES;
  }
  return NO;
}

Only add this snippet if the restorationHandler method will return true. Do not add this snippet if the method will return false or take the user back to the website.

To begin measuring ad performance, you must also track each in app event as described below.

Track in-app events driven by advertising

It's also possible to track other events of your choice as conversions.

Events you track in your app might include things like whether a user completes a gameplay tutorial, or whether a user completes a purchase. Conversion events will show up in your AdWords account if a user carries out one of these conversions after clicking an ad.

To track these events, simply define additional conversions in your AdWords account, one for each event you'd like to track. Give each one a descriptive name. (AdWords allows you to define a large number of different conversions, and gives you a different label for each one.) You'll then include each code snippet in your app in the appropriate place to track the conversion.

Note that if your conversion has a value (e.g., some in-app purchases cost 99 cents while others cost 1.99), you can fill in the proper value into the 'value' parameter each time you report a conversion.

Example: Track app upgrades as conversions

To track app upgrades, first define a new conversion in your AdWords account. Name the conversion something like "App upgrade".

Then take the conversion code snippet that was provided and put it inside a block of code that checks each time the app launches to see whether the app has just been upgraded to a newer version.

#import <Foundation/Foundation.h>
#import <UIKit/UIKit.h>

#import "ACTReporter.h"

static NSString *const kApplicationVersionNumber = @"3.0.1";
static NSString *const kApplicationVersionNumberKey = @"my_application_version_number";

static NSString *const kConversionAppUpdateID = @"<conversion ID>";
static NSString *const kConversionAppUpdateLabel = @"<conversion label>";
static NSString *const kConversionAppUpdateValue = @"<conversion value>";

/// Splits the "." concatenated string of integers into an array of NSNumbers. Returns the array of
/// NSNumbers if all components can be converted to integers. Returns nil otherwise.
static NSArray *versionNumberArrayFromVersionNumberString(NSString *string) {
  NSArray *stringComponents = [string componentsSeparatedByString:@"."];
  NSMutableArray *numberComponents = [NSMutableArray arrayWithCapacity:[stringComponents count]];
  for (NSString *component in stringComponents) {
    NSScanner *scanner = [NSScanner scannerWithString:component];
    NSInteger integerValue = 0;
    if (![scanner scanInteger:&integerValue] || ![scanner isAtEnd]) {
      break;
    }
    NSNumber *value = @(integerValue);
    if (!value) {
      break;
    }
    [numberComponents addObject:value];
  }
  if ([numberComponents count] == [stringComponents count]) {
    return numberComponents;
  }
  return nil;
}

/// Returns YES if currentVersionNumberArray represents a newer version number than
/// previousVersionNumberArray.
static BOOL versionIsNewer(NSArray *previousVersionNumberArray,
                           NSArray *currentVersionNumberArray) {
  NSUInteger previousCount = [previousVersionNumberArray count];
  NSUInteger currentCount = [currentVersionNumberArray count];
  NSUInteger minCount = MIN(previousCount, currentCount);
  for (NSUInteger i = 0; i < minCount; ++i) {
    NSNumber *previousValue = [previousVersionNumberArray objectAtIndex:i];
    NSNumber *currentValue = [currentVersionNumberArray objectAtIndex:i];
    if ([previousValue compare:currentValue] == NSOrderedAscending) {
      return YES;
    }
    if ([previousValue compare:currentValue] == NSOrderedDescending) {
      return NO;
    }
  }
  if (currentCount > previousCount) {
    return YES;
  }
  return NO;
}

@interface MyAppDelegate : NSObject<UIApplicationDelegate>
@end

@implementation MyAppDelegate

- (void)reportConversionIfUpdated {
#if USE_ICLOUD_STORAGE
  NSUbiquitousKeyValueStore *storage = [NSUbiquitousKeyValueStore defaultStore];
#else
  NSUserDefaults *storage = [NSUserDefaults standardUserDefaults];
#endif

  NSString *previousVersionNumber = [storage stringForKey:kApplicationVersionNumberKey];
  NSArray *previousVersionNumberArray =
      versionNumberArrayFromVersionNumberString(previousVersionNumber);
  NSArray *currentVersionNumberArray =
      versionNumberArrayFromVersionNumberString(kApplicationVersionNumber);

  if (versionIsNewer(previousVersionNumberArray, currentVersionNumberArray)) {
    // Store the updated version number.
    [storage setObject:kApplicationVersionNumber forKey:kApplicationVersionNumberKey];

    // Report the upgrade conversion.
    [ACTConversionReporter reportWithConversionID:kConversionAppUpdateID
                                            label:kConversionAppUpdateLabel
                                            value:kConversionAppUpdateValue
                                     isRepeatable:YES];
  }
}

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  // Configure application.

  // If required, report the update conversion.
  [self reportConversionIfUpdated];

  return YES;
}

@end

Confirm setup

The first time you run your app after adding the conversion tracking snippet, you should see messages similar to the following logged to your console, indicating that your app is successfully tracking downloads:

ConversionExample[9412:c07] ACTConversionReporter: Sending ping with IDFA: [...]

ConversionExample[9412:c07] ACTConversionReporter: Ping successful.

The next time you run your app, these types of messages indicate the download tracking snippet already fired once (the first time the app was opened after being downloaded) and does not need to fire again:

ConversionExample[2618:c07] ACTConversionReporter: Already sent successful ping with IDFA and conversion label abCDEFG12hIJk3Lm4nO.

If you're tracking other conversion events in your app, you should see messages logged for those events each time they occur. Unlike downloads, which are tracked only once per app install, other in-app events are tracked each time the event occurs. Pay special attention to the labels that were provided to you when verifying your setup (e.g., abCDEFG12hIJk3Lm4nO in the example shown above). Each label corresponds to a different conversion event, so it's important not to mix them up. For example, abCDEFG12hIJk3Lm4nO might show up as "[YourApp] app download" in AdWords, but a different label, efGHIJK12hIJk3Lm4nO, might map to "[YourApp] in-app email sign-up". So it's worth checking that each event is firing the proper label.

Send feedback about...

Mobile Apps Conversion Tracking and Remarketing
Mobile Apps Conversion Tracking and Remarketing