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
Kevin Winter, AdWords API Team
Kevin Winter, AdWords API Team
