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.

Key Point: Don't confuse logical_user_list with rule_based_user_list. A logical_user_list is defined as a custom combination of existing user lists whereas a rule_based_user_list is based on rules applied to the parameter values of your remarketing tag.

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

Java

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(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("My combination list of other user lists #" + getPrintableDateTime())
          .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());
  }
}
AddLogicalUserList.java
      

C#

public void Run(GoogleAdsClient client, long customerId, long[] userListIds)
{
    // Gets the UserListService client.
    UserListServiceClient userListServiceClient =
        client.GetService(Services.V13.UserListService);

    // Adds each of the provided list IDs to a list of rule operands specifying which lists
    // the operator should target.
    List<LogicalUserListOperandInfo> logicalUserListOperandInfoList =
        userListIds.Select(userListId => new LogicalUserListOperandInfo
        { UserList = ResourceNames.UserList(customerId, userListId) }).ToList();

    // 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 = new UserListLogicalRuleInfo
    {
        // 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.
        Operator = UserListLogicalRuleOperatorEnum.Types.UserListLogicalRuleOperator.Any,
    };
    userListLogicalRuleInfo.RuleOperands.Add(logicalUserListOperandInfoList);

    LogicalUserListInfo logicalUserListInfo = new LogicalUserListInfo();
    logicalUserListInfo.Rules.Add(userListLogicalRuleInfo);

    // Creates the new combination user list.
    UserList userList = new UserList
    {
        Name = "My combination list of other user lists " +
               $"#{ExampleUtilities.GetRandomString()}",
        LogicalUserList = logicalUserListInfo
    };

    // Creates the operation.
    UserListOperation operation = new UserListOperation
    {
        Create = userList
    };

    try
    {
        // Sends the request to add the user list and prints the response.
        MutateUserListsResponse response = userListServiceClient.MutateUserLists
            (customerId.ToString(), new[] { operation });
        Console.WriteLine("Created combination user list with resource name: " +
            $"{response.Results.First().ResourceName}");
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}
AddLogicalUserList.cs
      

PHP

public static function runExample(
    GoogleAdsClient $googleAdsClient,
    int $customerId,
    array $userListIds
) {
    // Adds each of the provided list IDs to a list of rule operands specifying which lists the
    // operator should target.
    $logicalUserListOperandInfoList = [];
    foreach ($userListIds as $userListId) {
        $logicalUserListOperandInfoList[] = new LogicalUserListOperandInfo([
            'user_list' => ResourceNames::forUserList($customerId, $userListId)
        ]);
    }

    // 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 = new UserListLogicalRuleInfo([
        // 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.
        'operator' => UserListLogicalRuleOperator::ANY,
        'rule_operands' => $logicalUserListOperandInfoList
    ]);

    // Creates the new combination user list.
    $userList = new UserList([
        'name' => 'My combination list of other user lists #' . Helper::getPrintableDatetime(),
        'logical_user_list' => new LogicalUserListInfo([
            'rules' => [$userListLogicalRuleInfo]
        ])
    ]);

    // Creates the operation.
    $operation = new UserListOperation();
    $operation->setCreate($userList);

    // Issues a mutate request to add the user list and prints some information.
    $userListServiceClient = $googleAdsClient->getUserListServiceClient();
    $response = $userListServiceClient->mutateUserLists($customerId, [$operation]);
    printf(
        "Created combination user list with resource name '%s'.%s",
        $response->getResults()[0]->getResourceName(),
        PHP_EOL
    );
}
AddLogicalUserList.php
      

Python

def main(client, customer_id, user_list_ids):
    """Creates a combination user list.

    Args:
        client: The Google Ads client.
        customer_id: The customer ID for which to add the user list.
        user_list_ids: A list of user list IDs to logically combine.
    """
    # Get the UserListService client.
    user_list_service = client.get_service("UserListService")

    # Add each of the provided list IDs to a list of rule operands specifying
    # which lists the operator should target.
    logical_user_list_operand_info_list = []
    for user_list_id in user_list_ids:
        logical_user_list_operand_info = client.get_type(
            "LogicalUserListOperandInfo"
        )
        logical_user_list_operand_info.user_list = user_list_service.user_list_path(
            customer_id, user_list_id
        )
        logical_user_list_operand_info_list.append(
            logical_user_list_operand_info
        )

    # Create a UserListOperation and populate the UserList.
    user_list_operation = client.get_type("UserListOperation")
    user_list = user_list_operation.create
    user_list.name = f"My combination list of other user lists #{uuid4()}"
    # Create a UserListLogicalRuleInfo specifying that a user should be added to
    # the new list if they are present in any of the provided lists.
    user_list_logical_rule_info = client.get_type("UserListLogicalRuleInfo")
    # 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.
    user_list_logical_rule_info.operator = (
        client.enums.UserListLogicalRuleOperatorEnum.ANY
    )
    user_list_logical_rule_info.rule_operands.extend(
        logical_user_list_operand_info_list
    )
    user_list.logical_user_list.rules.append(user_list_logical_rule_info)

    # Issue a mutate request to add the user list, then print the results.
    response = user_list_service.mutate_user_lists(
        customer_id=customer_id, operations=[user_list_operation]
    )
    print(
        "Created logical user list with resource name "
        f"'{response.results[0].resource_name}.'"
    )
add_logical_user_list.py
      

Ruby

def add_logical_user_list(customer_id, user_list_ids)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  # Creates the UserListLogicalRuleInfo specifying that a user should be added
  # to the new list if they are present in any of the provided lists.
  user_list_logical_rule_info = client.resource.user_list_logical_rule_info do |info|
    # 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 logical_user_list_operand_info.
    # 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.
    info.operator = :ANY
    user_list_ids.each do |list_id|
      info.rule_operands << client.resource.logical_user_list_operand_info do |op|
        op.user_list = client.path.user_list(customer_id, list_id)
      end
    end
  end

  # Creates the new combination user list operation.
  operation = client.operation.create_resource.user_list do |ul|
    ul.name = "My combination list of other user lists #{(Time.new.to_f * 1000).to_i}"
    ul.logical_user_list = client.resource.logical_user_list_info do |info|
      info.rules << user_list_logical_rule_info
    end
  end

  # Issues a mutate request to add the user list and prints some information.
  response = client.service.user_list.mutate_user_lists(
    customer_id: customer_id,
    operations: [operation],
  )
  puts "Created combination user list with resource name "\
    "'#{response.results.first.resource_name}'"
end
add_logical_user_list.rb
      

Perl

sub add_logical_user_list {
  my ($api_client, $customer_id, $user_list_ids) = @_;

  # Add each of the provided list IDs to a list of rule operands specifying which
  # lists the operator should target.
  my $logical_user_list_operand_info_list = [];
  foreach my $user_list_id (@$user_list_ids) {
    push @$logical_user_list_operand_info_list,
      Google::Ads::GoogleAds::V13::Common::LogicalUserListOperandInfo->new({
        userList =>
          Google::Ads::GoogleAds::V13::Utils::ResourceNames::user_list(
          $customer_id, $user_list_id
          )});
  }

  # Create the UserListLogicalRuleInfo specifying that a user should be added to
  # the new list if they are present in any of the provided lists.
  my $user_list_logical_rule_info =
    Google::Ads::GoogleAds::V13::Common::UserListLogicalRuleInfo->new({
      # 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.
      operator     => ANY,
      ruleOperands => $logical_user_list_operand_info_list
    });

  # Create the new combination user list.
  my $user_list = Google::Ads::GoogleAds::V13::Resources::UserList->new({
      name            => "My combination list of other user lists #" . uniqid(),
      logicalUserList =>
        Google::Ads::GoogleAds::V13::Common::LogicalUserListInfo->new({
          rules => [$user_list_logical_rule_info]})});

  # Create the operation.
  my $user_list_operation =
    Google::Ads::GoogleAds::V13::Services::UserListService::UserListOperation->
    new({
      create => $user_list
    });

  # Issue a mutate request to add the user list and print some information.
  my $user_lists_response = $api_client->UserListService()->mutate({
      customerId => $customer_id,
      operations => [$user_list_operation]});
  printf "Created combination user list with resource name '%s'.\n",
    $user_lists_response->{results}[0]{resourceName};

  return 1;
}
add_logical_user_list.pl