Discover v201008: Remarketing

Version v201008 of the AdWords API introduces the UserListService and the CriterionUserList which give you API access to the features available in the ‘Audiences’ tab in the AdWords interface. To learn more about remarketing, visit the AdWords Help Center.

You can set up remarketing using the AdWords API in two steps:

1. Create a remarketing list.
2. Create a CriterionUserList to tie your list to an AdGroup.

We’ve also included short code snippets showing you how to manage LogicalUserLists, also known as custom combination lists, and how to monitor your user list size.

Create a remarketing list

Creating a remarketing list involves the creation of two separate entities: the RemarketingList itself and its associated UserListConversionTypes also known as remarketing tags. The following code shows how to create a remarketing list.

// Get the UserListService.
UserListServiceInterface userListService =
    user.getService(AdWordsService.V201008.USER_LIST_SERVICE);

// Create conversion type (remarketing tag).
UserListConversionType conversionType = new UserListConversionType();
conversionType.setName("Mars cruise customers #" + System.currentTimeMillis());

// Create remarketing user list.
RemarketingUserList userList = new RemarketingUserList();
userList.setName("Mars cruise customers #" + System.currentTimeMillis());
userList.setDescription("A list of mars cruise customers in the last year");
userList.setMembershipLifeSpan(365L);
userList.setConversionTypes(new UserListConversionType[] {conversionType});

// Create operations.
UserListOperation operation = new UserListOperation();
operation.setOperand(userList);
operation.setOperator(Operator.ADD);

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

// Add user list.
userList = userListService.mutate(operations).getValue()[0];

Tie a remarketing list to an AdGroup

A new type of criteria object called CriterionUserList is now part of v201008. Through this type of criteria you are able to tie a UserList to an AdGroup. As with other types of criteria, this type is also managed through the AdGroupCriterionService. The following code shows you how to create a CriterionUserList and tie it to an existing AdGroup.

// Create user list criteria.
CriterionUserList userListCriteria = new CriterionUserList();
userListCriteria.setUserListId(userList.getId());

// Create biddable ad group criterion.
BiddableAdGroupCriterion userListBiddableAdGroupCriterion = new BiddableAdGroupCriterion();
userListBiddableAdGroupCriterion.setAdGroupId(adGroupId);
userListBiddableAdGroupCriterion.setCriterion(userListCriteria);

// Create operation.
AdGroupCriterionOperation userListAdGroupCriterionOperation = 
    new AdGroupCriterionOperation();
userListAdGroupCriterionOperation.setOperand(userListBiddableAdGroupCriterion);
userListAdGroupCriterionOperation.setOperator(Operator.ADD);

AdGroupCriterionOperation[] criteriaOperations =
    new AdGroupCriterionOperation[] {userListAdGroupCriterionOperation};

// Add ad group criteria.
adGroupCriterionService.mutate(criteriaOperations);

Custom combination list

It’s also possible through the API to create LogicalUserLists, also known as custom combination lists in the AdWords interface. A LogicalUserList lets you group together other UserLists, which includes RemarketingUserLists and other LogicalUserLists, through a series of UserListLogicalRules. The following code shows you how to create a simple LogicalUserList that combines two other remarketing lists, but it’s possible to create more complex combinations using this type of list.

// Remarketing user lists to be referenced.
UserList list1 = new RemarketingUserList();
list1.setId(remarketingUserListId1);

UserList list2 = new RemarketingUserList();
list2.setId(remarketingUserListId2);

// Create logical user list.
LogicalUserList logicalList = new LogicalUserList();
logicalList.setName("Logical list #" + System.currentTimeMillis());
logicalList.setDescription("A list of two other lists");
logicalList.setMembershipLifeSpan(365L);
logicalList.setRules(new UserListLogicalRule[] {
    new UserListLogicalRule(UserListLogicalRuleOperator.ALL,
       new LogicalUserListOperand[] {
            new LogicalUserListOperand(null, list1),
            new LogicalUserListOperand(null, list2),
    })
});

// Create operation.
UserListOperation operation = new UserListOperation();
operation.setOperand(logicalList);
operation.setOperator(Operator.ADD);

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

// Add user list.
UserListReturnValue result = userListService.mutate(operations);

Monitor the size of your list

You also might be interested in monitoring the growth of your list. You can accomplish this by making a simple get() call to the UserListService to retrieve this kind of information. The following code shows you how to retrieve information about all of your user lists.

// Create selector.
UserListSelector selector = new UserListSelector();

// Get all user lists.
UserListPage page = userListService.get(selector);

// Display user lists information.
if (page.getEntries() != null) {
  for (UserList userList : page.getEntries()) {
    System.out.printf("User list with name '%s' has an estimate size of '%d' users.\n",
        userList.getName(), userList.getSize());
  }
}

All code snippets included in this post are based on the AdWords API Java Client Library, other client libraries also include code examples and support for remarketing.

As always, please post your questions about how to use this new service on the forum.

Posted by David Torres, AdWords API Team