Google Ads API is returning to beta status. Please read our blog post for more details.

Visitors who Took Specific Actions

You can populate your audience list with people who have taken specific actions on your website. If you're using conversion tracking, you can target ads to people who previously triggered a conversion (such as a purchase) on your website.

You can also target ads to people who have taken a particular action on your website that you do not consider a conversion, such as when a person adds but then deletes an item from their shopping cart without making a purchase.

In either case, you would set the basic_user_list field of a UserList with a BasicUserListInfo object containing references to the conversions you are targeting.

Triggered a conversion

If you haven't yet created a conversion tracker, you can do so using ConversionActionService. You can then install the conversion tracker tag on your website.

A basic user list defines its membership as people who had triggered one or more conversion trackers on your website. When you create a basic user list, you provide the resource name of the ConversionAction to a UserListActionInfo object, which is ultimately passed to the UserList.

The following example creates a BasicUserList associated with two existing conversion trackers:

private void runExample(
    GoogleAdsClient googleAdsClient, long customerId, List<Long> conversionActionIds) {
  List<UserListActionInfo> userListActionInfoList = new ArrayList<>();
  for (long conversionActionId : conversionActionIds) {
    // Creates the UserListActionInfo object for a given conversion action. This specifies the
    // conversion action that, when triggered, will cause a user to be added to a UserList.
    UserListActionInfo userListActionInfo =
        UserListActionInfo.newBuilder()
            .setConversionAction(
                StringValue.of(ResourceNames.conversionAction(customerId, conversionActionId)))
            .build();
    userListActionInfoList.add(userListActionInfo);
  }

  // Creates a basic user list info object with all of the conversion actions.
  BasicUserListInfo basicUserListInfo =
      BasicUserListInfo.newBuilder().addAllActions(userListActionInfoList).build();

  // Creates the basic user list.
  UserList basicUserList =
      UserList.newBuilder()
          .setName(StringValue.of("Example BasicUserList #" + System.currentTimeMillis()))
          .setDescription(
              StringValue.of(
                  "A list of people who have triggered one or more conversion actions"))
          .setMembershipLifeSpan(Int64Value.of(365))
          .setBasicUserList(basicUserListInfo)
          .setMembershipStatus(UserListMembershipStatus.OPEN)
          .build();

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

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

Non-conversion actions

You can create a basic user list for people who took actions on your website that you do not consider conversions by associating it with a RemarketingAction instead of a ConversionAction. The example below demonstrates how to create a RemarketingAction and retrieve the associated site tags.

private void runExample(GoogleAdsClient googleAdsClient, long customerId) {

  // Creates a remarketing action with the specified name.
  RemarketingAction remarketingAction =
      RemarketingAction.newBuilder()
          .setName(StringValue.of("Remarketing action #" + System.currentTimeMillis()))
          .build();

  // Creates a remarketing action operation.
  RemarketingActionOperation operation =
      RemarketingActionOperation.newBuilder().setCreate(remarketingAction).build();

  // Issues a mutate request to add the remarketing action and prints out some information.
  String remarketingActionResourceName;
  try (RemarketingActionServiceClient conversionActionServiceClient =
      googleAdsClient.getLatestVersion().createRemarketingActionServiceClient()) {
    MutateRemarketingActionsResponse response =
        conversionActionServiceClient.mutateRemarketingActions(
            Long.toString(customerId), Collections.singletonList(operation));
    remarketingActionResourceName = response.getResults(0).getResourceName();
    System.out.printf(
        "Added remarketing action with resource name '%s'.%n", remarketingActionResourceName);
  }

  // Creates a query that retrieves the previously created remarketing action with its generated
  // tag snippets.
  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);
  try (GoogleAdsServiceClient googleAdsServiceClient =
      googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
    // Issues a search request.
    SearchPagedResponse searchPagedResponse =
        googleAdsServiceClient.search(Long.toString(customerId), query);

    // There is only one row because we limited the search using the resource name, which is
    // unique.
    GoogleAdsRow googleAdsRow = searchPagedResponse.iterateAll().iterator().next();

    // Prints some attributes of the remarketing action. The ID and tag snippets are generated by
    // the API.
    RemarketingAction newRemarketingAction = googleAdsRow.getRemarketingAction();
    System.out.printf(
        "Remarketing action has ID %d and name '%s'.%n%n",
        newRemarketingAction.getId().getValue(), newRemarketingAction.getName().getValue());
    System.out.println("It has the following generated tag snippets:");
    for (TagSnippet tagSnippet : newRemarketingAction.getTagSnippetsList()) {
      System.out.printf(
          "Tag snippet with code type '%s' and code page format '%s' has the following global"
              + " site tag:%n%s%n",
          tagSnippet.getType(),
          tagSnippet.getPageFormat(),
          tagSnippet.getGlobalSiteTag().getValue());
      System.out.printf(
          "and the following event snippet:%n%s%n%n", tagSnippet.getEventSnippet().getValue());
    }
  }
}