With the release of v201101 we introduce the ConversionTrackerService to manage conversion tracking via the AdWords API. This new service lets you create, retrieve, modify and remove AdWordsConversionTracker objects, which hold all the information about a specific conversion type that resides in your account, including ID, name, status, category, and others, but more importantly the conversion code snippet you need to put on your website in order to fully implement conversion tracking. The main objective of this post is to show the basic operations that can be performed by using this service.

Creation

Let’s start by creating a "PURCHASE" AdWordsConversionTracker that specifies the one line site stats logo, HTML markup in the code snippet, and that your website is using HTTPS:


// Create AdWords conversion.
AdWordsConversionTracker adWordsConversionTracker =
    new AdWordsConversionTracker();
adWordsConversionTracker.setName("A purchase conversion tracker");
adWordsConversionTracker.setCategory(ConversionTrackerCategory.PURCHASE);
adWordsConversionTracker.setMarkupLanguage(
    AdWordsConversionTrackerMarkupLanguage.HTML);
adWordsConversionTracker.setHttpProtocol(
    AdWordsConversionTrackerHttpProtocol.HTTPS);
adWordsConversionTracker.setTextFormat(
    AdWordsConversionTrackerTextFormat.ONE_LINE);
adWordsConversionTracker.setUserRevenueValue("<%= shoppingCartTotal %>");

// Create operations.
ConversionTrackerOperation operation = new ConversionTrackerOperation();
operation.setOperator(Operator.ADD);
operation.setOperand(adWordsConversionTracker);
ConversionTrackerOperation[] operations =
    new ConversionTrackerOperation[] {operation};
// Add conversion tracker.
conversionTrackerService.mutate(operations);


AdWordsConversionTracker offers a set of properties that control what the conversion code snippet will look like. Let’s go over some of them:

markupLanguage: Determines the markup language of the code snippet. In most cases this will be HTML but CHTML, XHTML and WML are also supported, mostly for mobile devices that are not fully HTML capable.

httpProtocol: The protocol used by your web page, either HTTP or HTTPS. If this setting is incorrectly specified your visitors will experience warnings like "Page includes other resources which are not secure".

textFormat, conversionPageLanguage and backgroundColor: We encourage you to use visible text for conversion tracking when using AdWords conversion tracking technology. For this purpose two textFormat options are offered: ONE_LINE and TWO_LINE. conversionPageLanguage and backgroundColor control the language in which the text will be displayed and what background color will be used, respectively. If you decide to not use Google's site logo, you can specify HIDDEN for the textFormat. In this case, setting conversionPageLanguage and backgroundColor has no effects.

userRevenueValue: This value can be either fixed or dynamically set. For specific examples on how to set this value based on your server-side technology refer to the AdWords Conversion Tracking Setup Guide. Examples of its use would be a user shopping cart total value for a "PURCHASE" conversion or a fixed weight value you give to a specific "LEAD" conversion. This value is only meaningful to you in reports and it has no effect in AdWords costs. The conversion values can then be reported back to you using the reporting capabilities of the API by including fields such as ConversionValue in your reports.

Retrieval

As with most of our services, ConversionTrackerService offers a get method for you to retrieve ConversionTracker objects. This operation is based on generic selectors, so you can filter, sort and paginate results as desired.

The following example shows you how to retrieve the Id, Name and Category of all your ConversionTracker objects.


// Create selector.
Selector selector = new Selector();
selector.setFields(new String[] {"Name", "Status", "Category"});
selector.setOrdering(new OrderBy[] {new OrderBy("Name",
    SortOrder.ASCENDING)});

// Get all conversion trackers.
ConversionTrackerPage page = service.get(selector);

// Display conversion trackers.
if (page != null && page.getEntries() != null) {
  for (ConversionTracker conversionTracker : page.getEntries()) {
    if (conversionTracker instanceof AdWordsConversionTracker) {
      AdWordsConversionTracker awConversionTracker =
          (AdWordsConversionTracker) conversionTracker;
      System.out.printf("Conversion tracker with id \"%d\", " +
          "name \"%s\", status \"%s\", category \"%s\" and " +
          "snippet \"%s\" was found.\n", awConversionTracker.getId(),
          awConversionTracker.getName(),
          awConversionTracker.getStatus(),
          awConversionTracker.getCategory(),
          awConversionTracker.getSnippet());
    }
  }
}


Notice that even though the Snippet field was not requested in the selector, it will always be returned in your results. It contains the code you need to put in your web page to start capturing conversions. We recommend that you put this code as close as possible to the footer of the page.

Update

As you can create and retrieve ConversionTracker objects, it is also possible to update most of their properties using the service mutate operation. One of the most common operations is to disable a conversion tracker, hence stop capturing conversions even if the code snippet still resides in your website. The following code shows how to disable a conversion tracker.


long conversionId =
    Long.parseLong("CONVERSION_ID_YOU_WANT_TO_DISABLE");

// Create conversion tracker with updated status and name.
AdWordsConversionTracker adWordsConversionTracker =
    new AdWordsConversionTracker();
adWordsConversionTracker.setId(conversionId);
adWordsConversionTracker.setStatus(ConversionTrackerStatus.DISABLED);

// Create operations.
ConversionTrackerOperation operation = 
    new ConversionTrackerOperation();
operation.setOperand(adWordsConversionTracker);
operation.setOperator(Operator.SET);

ConversionTrackerOperation[] operations =
    new ConversionTrackerOperation[] {operation};

// Update conversion tracker.
ConversionTrackerReturnValue result = service.mutate(operations);


Reports

Most of the API reports contain conversion fields such as Conversions, ConversionValue, CostPerConversion, and others that you can query. Two conversion fields that allow you to segment conversion stats in your report are ConversionCategoryName and ConversionTypeName. Use ConversionCategoryName to group by conversion category (i.e., PURCHASE, LEAD, ...) and ConversionTypeName to group by ConversionTracker name, which is unique for each account. Keep in mind these two fields cannot be combined with non-conversion fields such as Impressions or Clicks.

User lists and conversions

A special mention goes to RemarketingUserList objects which are managed via the UserListService. This kind of list has a close relationship with conversions since every list is associated with at least one AdWords ConversionTracker. To retrieve the associated ConversionTracker objects, a RemarketingUserList contains a list of UserListConversionType objects which hold the IDs of the associated conversion trackers. Hence you can use those IDs to get, via the ConversionTrackerService, the code snippets required to fully enable your remarketing list. To learn more about user lists and remarketing in the AdWords API read the post on Remarketing.

All code examples in this post were developed using the AdWords API Java Client Library, but we also offer support for other popular languages. To learn more about our client libraries, visit our code site. As always, feel free to contact us via the AdWords API Forum.

  David Torres, AdWords API Team