Visitors to Your Website

The simplest type of audience list comprises visitors to your website.

Retrieving remarketing tag

All Google Ads accounts have exactly one account-level remarketing tag, created automatically when the account is opened. The tag is available even if you haven't yet initiated remarketing. The first step is to retrieve your account's account-level remarketing tag by issuing a search request against the remarketing_action resource:

String query =
    String.format(
        "SELECT remarketing_action.id,"
            + " remarketing_action.name,"
            + " remarketing_action.tag_snippets "
            + "FROM remarketing_action "
            + "WHERE remarketing_action.resource_name = '%s'",
        remarketingActionResourceName);

Installing remarketing tag

The next step is to install your account-level remarketing tag on all of your site's pages. Learn more about adding the remarketing tag to your site or mobile app.

You can also use the Google Tag Assistant in Chrome to validate your tag installation.

Creating user lists

Next, you need to create a user list that contains the people who've triggered the remarketing tag. You create and manage user lists with UserListService.

There are different kinds of user lists with different characteristics. To create a list that captures everyone who visited any page on your website, set the rule_based_user_list field of your UserList with a RuleBasedUserListInfo object.

Then, specify an ExpressionRuleUserListInfo field on your RuleBasedUserListInfo object, which contains a rule targeting people who visited your website. Refer to Rule-based User Lists for further details on using rule-based remarketing lists.

private String createUserList(GoogleAdsClient googleAdsClient, long customerId) {
  // Creates a rule targeting any user that visited a url containing 'example.com'.
  UserListRuleItemInfo rule =
      UserListRuleItemInfo.newBuilder()
          // Uses a built-in parameter to create a domain URL rule.
          .setName(StringValue.of("url__"))
          .setStringRuleItem(
              UserListStringRuleItemInfo.newBuilder()
                  .setOperator(UserListStringRuleItemOperator.CONTAINS)
                  .setValue(StringValue.of("example.com"))
                  .build())
          .build();

  // Specifies that the user list targets visitors of a page based on the provided rule.
  ExpressionRuleUserListInfo expressionRuleUserListInfo =
      ExpressionRuleUserListInfo.newBuilder()
          .setRule(
              UserListRuleInfo.newBuilder()
                  .addRuleItemGroups(
                      UserListRuleItemGroupInfo.newBuilder().addRuleItems(rule).build())
                  .build())
          .build();

  // Defines a representation of a user list that is generated by a rule.
  RuleBasedUserListInfo ruleBasedUserListInfo =
      RuleBasedUserListInfo.newBuilder()
          // Optional: To include past users in the user list, set the prepopulation_status to
          // REQUESTED.
          .setPrepopulationStatus(UserListPrepopulationStatus.REQUESTED)
          .setExpressionRuleUserList(expressionRuleUserListInfo)
          .build();

  // Creates the user list.
  UserList userList =
      UserList.newBuilder()
          .setName(StringValue.of("All visitors to example.com" + System.currentTimeMillis()))
          .setDescription(StringValue.of("Any visitor to any page of example.com"))
          .setMembershipStatus(UserListMembershipStatus.OPEN)
          .setMembershipLifeSpan(Int64Value.of(365))
          .setRuleBasedUserList(ruleBasedUserListInfo)
          .build();

  // Creates the operation.
  UserListOperation operation = UserListOperation.newBuilder().setCreate(userList).build();

  // Creates the user list service client.
  try (UserListServiceClient userListServiceClient =
      googleAdsClient.getLatestVersion().createUserListServiceClient()) {
    // Adds the user list.
    MutateUserListsResponse response =
        userListServiceClient.mutateUserLists(
            Long.toString(customerId), ImmutableList.of(operation));
    String userListResourceName = response.getResults(0).getResourceName();
    // Prints the result.
    System.out.printf("Created user list with resource name '%s'.%n", userListResourceName);
    return userListResourceName;
  }
}

Two important attributes of a user list are membership_life_span and membership_status. The former allows you to define the time period, in days, for which a user is considered to be in the list. The latter defines whether the list will accept new users.

Targeting ads to user lists

The final step is to target ads to members of your user list. The process is similar to other types of targeting criteria in the API. The following code demonstrates how you can use an AdGroupCriterion to target ads in an ad group to a user list:

private String targetAdsInAdGroupToUserList(
    GoogleAdsClient googleAdsClient, long customerId, long adGroupId, String userList) {
  // Creates the ad group criterion targeting members of the user list.
  AdGroupCriterion adGroupCriterion =
      AdGroupCriterion.newBuilder()
          .setAdGroup(StringValue.of(ResourceNames.adGroup(customerId, adGroupId)))
          .setUserList(UserListInfo.newBuilder().setUserList(StringValue.of(userList)).build())
          .build();

  // Creates the operation.
  AdGroupCriterionOperation operation =
      AdGroupCriterionOperation.newBuilder().setCreate(adGroupCriterion).build();

  // Creates the ad group criterion service.
  try (AdGroupCriterionServiceClient adGroupCriterionServiceClient =
      googleAdsClient.getLatestVersion().createAdGroupCriterionServiceClient()) {
    // Adds the ad group criterion.
    MutateAdGroupCriteriaResponse response =
        adGroupCriterionServiceClient.mutateAdGroupCriteria(
            Long.toString(customerId), ImmutableList.of(operation));
    // Gets and prints the results.
    String adGroupCriterionResourceName = response.getResults(0).getResourceName();
    System.out.printf(
        "Successfully created ad group criterion with resource name '%s' "
            + "targeting user list with resource name '%s' with ad group with ID %d.%n",
        adGroupCriterionResourceName, userList, adGroupId);
    return adGroupCriterionResourceName;
  }
}

As with other types of criteria, you can assign other properties to the AdGroupCriterion object, such as bid overrides.

Switching targeting levels

If you are switching from ad group level user list criteria to campaign level, you must first remove the existing user list criteria from each enabled or paused ad group under that campaign.

First, retrieve all of the AdGroupCriteria under a given campaign:

private List<String> getUserListAdGroupCriterion(
    GoogleAdsClient googleAdsClient, long customerId, long campaignId) {
  List<String> userListCriteria = new ArrayList<>();
  // Creates the Google Ads service client.
  try (GoogleAdsServiceClient googleAdsServiceClient =
      googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
    // Creates a request that will retrieve all of the ad group criteria under a campaign.
    SearchGoogleAdsRequest request =
        SearchGoogleAdsRequest.newBuilder()
            .setCustomerId(Long.toString(customerId))
            .setPageSize(PAGE_SIZE)
            .setQuery(
                "SELECT ad_group_criterion.criterion_id"
                    + " FROM ad_group_criterion"
                    + " WHERE campaign.id = "
                    + campaignId
                    + " AND ad_group_criterion.type = 'USER_LIST'")
            .build();
    // Issues the search request.
    SearchPagedResponse searchPagedResponse = googleAdsServiceClient.search(request);
    // Iterates over all rows in all pages. Prints the results and adds the ad group criteria
    // resource names to the list.
    for (GoogleAdsRow googleAdsRow : searchPagedResponse.iterateAll()) {
      String adGroupCriterionResourceName = googleAdsRow.getAdGroupCriterion().getResourceName();
      System.out.printf(
          "Ad group criterion with resource name '%s' was found.%n",
          adGroupCriterionResourceName);
      userListCriteria.add(adGroupCriterionResourceName);
    }
  }
  return userListCriteria;
}

Then, remove all of the ad group criteria target that were returned:

private void removeExistingListCriteriaFromAdGroup(
    GoogleAdsClient googleAdsClient, long customerId, long campaignId) {
  // Retrieves all of the ad group criteria under a campaign.
  List<String> adGroupCriteria =
      getUserListAdGroupCriterion(googleAdsClient, customerId, campaignId);

  List<AdGroupCriterionOperation> operations = new ArrayList<>();

  // Creates a list of remove operations.
  for (String adGroupCriterion : adGroupCriteria) {
    operations.add(AdGroupCriterionOperation.newBuilder().setRemove(adGroupCriterion).build());
  }

  // Creates the ad group criterion service.
  try (AdGroupCriterionServiceClient adGroupCriterionServiceClient =
      googleAdsClient.getLatestVersion().createAdGroupCriterionServiceClient()) {
    // Removes the ad group criterion.
    MutateAdGroupCriteriaResponse response =
        adGroupCriterionServiceClient.mutateAdGroupCriteria(
            Long.toString(customerId), operations);
    // Gets and prints the results.
    System.out.printf("Removed %d ad group criteria.%n", response.getResultsCount());
    for (MutateAdGroupCriterionResult result : response.getResultsList()) {
      System.out.printf(
          "Successfully removed ad group criterion with resource name '%s'.%n",
          result.getResourceName());
    }
  }
}

Existing campaign level user list criteria must also be removed when switching to ad group level user lists, and the process mirrors the example shown above.

Targeting ads in a campaign to a user list is done similarly with a CampaignCriterion:

private String targetAdsInCampaignToUserList(
    GoogleAdsClient googleAdsClient, long customerId, long campaignId, String userList) {
  // Creates the campaign criterion.
  CampaignCriterion campaignCriterion =
      CampaignCriterion.newBuilder()
          .setCampaign(StringValue.of(ResourceNames.campaign(customerId, campaignId)))
          .setUserList(UserListInfo.newBuilder().setUserList(StringValue.of(userList)).build())
          .build();

  // Creates the operation.
  CampaignCriterionOperation operation =
      CampaignCriterionOperation.newBuilder().setCreate(campaignCriterion).build();

  // Creates the campaign criterion service client.
  try (CampaignCriterionServiceClient campaignCriterionServiceClient =
      googleAdsClient.getLatestVersion().createCampaignCriterionServiceClient()) {
    // Adds the campaign criterion.
    MutateCampaignCriteriaResponse response =
        campaignCriterionServiceClient.mutateCampaignCriteria(
            Long.toString(customerId), ImmutableList.of(operation));
    // Gets and prints the campaign criterion resource name.
    String campaignCriterionResourceName = response.getResults(0).getResourceName();
    System.out.printf(
        "Successfully created campaign criterion with resource name '%s' "
            + "targeting user list with resource name '%s' with campaign with ID %d.%n",
        campaignCriterionResourceName, userList, campaignId);
    return campaignCriterionResourceName;
  }
}