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

Multiple User Lists

You can construct custom combinations of existing user lists as a logical_user_list with UserListLogicalRuleInfo fields. The rules in the logical_user_list are ANDed, so a user must match every rule to be considered in the list. However, each rule lets you specify whether its operands are ANDed or ORed. In other words, you can specify whether the user must fulfill all of the rule operands or just one of them.

In addition, rules let you specify other logical_user_list objects as operands, effectively letting you create a tree of them. logical_user_list can be a very powerful way of defining complex hierarchies of groups for your targeting. You can combine lists with different AccessReason fields. However, if access is revoked, then that UserList will be treated as a list with no members when the rules of the logical_user_list are evaluated.

The following code shows how to create a logical_user_list containing users in either of two basic_user_list instances:

private void runExample(
    GoogleAdsClient googleAdsClient, long customerId, List<Long> userListIds) {
  // Adds each of the provided list IDs to a list of rule operands specifying which lists the
  // operator should target.
  List<LogicalUserListOperandInfo> logicalUserListOperandInfoList = new ArrayList<>();
  for (long userListId : userListIds) {
    String userListResourceName = ResourceNames.userList(customerId, userListId);
    logicalUserListOperandInfoList.add(
        LogicalUserListOperandInfo.newBuilder()
            .setUserList(StringValue.of(userListResourceName))
            .build());
  }

  // Creates the UserListLogicalRuleInfo specifying that a user should be added to the new list if
  // they are present in any of the provided lists.
  UserListLogicalRuleInfo userListLogicalRuleInfo =
      UserListLogicalRuleInfo.newBuilder()
          // Using ANY means that a user should be added to the combined list if they are present
          // on any of the lists targeted in the LogicalUserListOperandInfo. Use ALL to add users
          // present on all of the provided lists or NONE to add users that aren't present on any
          // of the targeted lists.
          .setOperator(UserListLogicalRuleOperator.ANY)
          .addAllRuleOperands(logicalUserListOperandInfoList)
          .build();

  // Creates the new combination user list.
  UserList userList =
      UserList.newBuilder()
          .setName(
              StringValue.of(
                  "My combination list of other user lists #" + System.currentTimeMillis()))
          .setLogicalUserList(
              LogicalUserListInfo.newBuilder().addRules(userListLogicalRuleInfo).build())
          .build();

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

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