Remarketing with Rule-based User Lists

Rule-based user lists allow you to define a targeting audience for your ads based on visited URLs or custom parameters you add to your remarketing tag.

Once you have a user list in place and add the remarketing tag to your site, you can target users in the list, bid differently for those users, and run reports that organize or filter stats based on members of the list.

Advertisers seeking to create user lists based on mobile app behavior should implement the Firebase SDK or work with third-party SDKs in order to track in-app behavior.

Adding the remarketing tag to your site

For your rule-based user lists to be populated, you need to add your account-level remarketing tag to your site. If you're planning to build remarketing lists based only on visited page URLs, you don't need to make any edits to your remarketing tag. If you're using custom parameters, see the following article for how to edit your tag to include them: Advanced strategies for tagging and creating remarketing lists.

Using built-in remarketing tag parameters

You can use the built-in remarketing parameter url__ to target a user list based on the URLs that people have visited on your website. For example, the code below illustrates how to create a rule-based user list for people who visited pages in two different sections of your website. Using a built-in remarketing parameter does not require making any edits to your remarketing tag.

Java

private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
  String urlString = "url__";

  // Creates a rule targeting any user that visited a url that contains 'example.com/section1'.
  UserListRuleItemInfo rule1 =
      UserListRuleItemInfo.newBuilder()
          // Uses a built-in parameter to create a domain URL rule.
          .setName(urlString)
          .setStringRuleItem(
              UserListStringRuleItemInfo.newBuilder()
                  .setOperator(UserListStringRuleItemOperator.CONTAINS)
                  .setValue("example.com/section1")
                  .build())
          .build();

  // Creates a rule targeting any user that visited a url that contains 'example.com/section2'.
  UserListRuleItemInfo rule2 =
      UserListRuleItemInfo.newBuilder()
          // Uses a built-in parameter to create a domain URL rule.
          .setName(urlString)
          .setStringRuleItem(
              UserListStringRuleItemInfo.newBuilder()
                  .setOperator(UserListStringRuleItemOperator.CONTAINS)
                  .setValue("example.com/section2")
                  .build())
          .build();

  // Creates an ExpressionRuleUserListInfo object, or a boolean rule that defines this user list.
  // The default rule_type for a UserListRuleInfo object is OR of ANDs (disjunctive normal form).
  // That is, rule items will be ANDed together within rule item groups and the groups themselves
  // will be ORed together.
  ExpressionRuleUserListInfo expressionRuleUserListInfo =
      ExpressionRuleUserListInfo.newBuilder()
          .setRule(
              UserListRuleInfo.newBuilder()
                  .addRuleItemGroups(
                      // Combine the two rule items into a UserListRuleItemGroupInfo object so
                      // Google Ads will AND their rules together. To instead OR the rules
                      // together, each rule should be placed in its own rule item group.
                      UserListRuleItemGroupInfo.newBuilder()
                          .addAllRuleItems(ImmutableList.of(rule1, rule2))
                          .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 a user list.
  UserList userList =
      UserList.newBuilder()
          .setName(
              "All visitors to example.com/section1 AND example.com/section2 #"
                  + getPrintableDateTime())
          .setDescription("Visitors of both example.com/section1 AND example.com/section2")
          .setMembershipStatus(UserListMembershipStatus.OPEN)
          .setMembershipLifeSpan(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);
  }
}
      

C#

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

    // Creates the user targeting rules for each URL.
    UserListRuleItemInfo rule1 = BuildVisitedSiteRuleInfo("example.com/section1");
    UserListRuleItemInfo rule2 = BuildVisitedSiteRuleInfo("example.com/section2");

    // Combine the two rule items into a UserListRuleItemGroupInfo object so Google Ads will
    // AND their rules together. To instead OR the rules together, each rule should be
    // placed in its own rule item group.
    UserListRuleItemGroupInfo userListRuleItemGroupInfo = new UserListRuleItemGroupInfo();
    userListRuleItemGroupInfo.RuleItems.Add(rule1);
    userListRuleItemGroupInfo.RuleItems.Add(rule2);

    UserListRuleInfo userListRuleInfo = new UserListRuleInfo();
    userListRuleInfo.RuleItemGroups.Add(userListRuleItemGroupInfo);

    // Creates an ExpressionRuleUserListInfo object, or a boolean rule that defines this
    // user list. The default rule_type for a UserListRuleInfo object is OR of ANDs
    // (disjunctive normal form). That is, rule items will be ANDed together within rule
    // item groups and the groups themselves will be ORed together.
    ExpressionRuleUserListInfo expressionRuleUserListInfo = new ExpressionRuleUserListInfo
    {
        Rule = userListRuleInfo
    };

    // Defines a representation of a user list that is generated by a rule.
    RuleBasedUserListInfo ruleBasedUserListInfo = new RuleBasedUserListInfo
    {
        // Optional: To include past users in the user list, set the prepopulation_status to
        // REQUESTED.
        PrepopulationStatus = UserListPrepopulationStatus.Requested,
        ExpressionRuleUserList = expressionRuleUserListInfo
    };

    // Creates a new user list.
    UserList userList = new UserList
    {
        Name = "All visitors to example.com/section1 AND example.com/section2 " +
               $"#{ExampleUtilities.GetRandomString()}",
        Description = "Visitors of both example.com/section1 AND example.com/section2",
        MembershipStatus = UserListMembershipStatus.Open,
        MembershipLifeSpan = 365L,
        RuleBasedUserList = ruleBasedUserListInfo
    };

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

    try
    {
        // Adds the user list.
        MutateUserListsResponse response = userListServiceClient.MutateUserLists
            (customerId.ToString(), new[] {operation});

        // Displays the results.
        Console.WriteLine("Created new 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;
    }
}

/// <summary>
/// Creates and returns a UserListRuleItemInfo object targeting a visit to a specified URL.
/// </summary>
/// <param name="url">The URL at which the rule will target users.</param>
/// <returns>A populated UserListRuleItemInfo object.</returns>
private UserListRuleItemInfo BuildVisitedSiteRuleInfo(string url)
{
    // Creates a rule targeting any user that visited the specified URL.
    UserListRuleItemInfo userVisitedSiteRule = new UserListRuleItemInfo
    {
        // Uses a built-in parameter to create a domain URL rule.
        Name = "url__",
        StringRuleItem = new UserListStringRuleItemInfo
        {
            Operator = UserListStringRuleItemOperator.Contains,
            Value = url
        }
    };

    return userVisitedSiteRule;
}
      

PHP

public static function runExample(
    GoogleAdsClient $googleAdsClient,
    int $customerId
) {
    // Creates a rule targeting any user that visited a url that contains
    // 'example.com/section1'.
    $rule1 = new UserListRuleItemInfo([
        // Uses a built-in parameter to create a domain URL rule.
        'name' => self::URL_STRING,
        'string_rule_item' => new UserListStringRuleItemInfo([
            'operator' => UserListStringRuleItemOperator::CONTAINS,
            'value' => 'example.com/section1'
        ])
    ]);

    // Creates a rule targeting any user that visited a url that contains
    // 'example.com/section2'.
    $rule2 = new UserListRuleItemInfo([
        // Uses a built-in parameter to create a domain URL rule.
        'name' => self::URL_STRING,
        'string_rule_item' => new UserListStringRuleItemInfo([
            'operator' => UserListStringRuleItemOperator::CONTAINS,
            'value' => 'example.com/section2'
        ])
    ]);

    // Creates an ExpressionRuleUserListInfo object, or a boolean rule that defines this user
    // list. The default rule_type for a UserListRuleInfo object is OR of ANDs (disjunctive
    // normal form). That is, rule items will be ANDed together within rule item groups and
    // the groups themselves will be ORed together.
    $expressionRuleUserListInfo = new ExpressionRuleUserListInfo([
        'rule' => new UserListRuleInfo([
            'rule_item_groups' => [
                // Combines the two rule items into a UserListRuleItemGroupInfo object so
                // Google Ads will AND their rules together. To instead OR the rules
                // together, each rule should be placed in its own rule item group.
                new UserListRuleItemGroupInfo([
                    'rule_items' => [$rule1, $rule2]
                ])
            ]
        ])
    ]);

    // Defines a representation of a user list that is generated by a rule.
    $ruleBasedUserListInfo = new RuleBasedUserListInfo([
        // Optional: To include past users in the user list, set the prepopulation_status to
        // REQUESTED.
        'prepopulation_status' => UserListPrepopulationStatus::REQUESTED,
        'expression_rule_user_list' => $expressionRuleUserListInfo
    ]);

    // Creates a user list.
    $userList = new UserList([
        'name' => 'All visitors to example.com/section1 AND example.com/section2 #' .
            Helper::getPrintableDatetime(),
        'description' => 'Visitors of both example.com/section1 AND example.com/section2',
        'membership_status' => UserListMembershipStatus::OPEN,
        'membership_life_span' => 365,
        'rule_based_user_list' => $ruleBasedUserListInfo
    ]);

    // 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 user list with resource name '%s'.%s",
        $response->getResults()[0]->getResourceName(),
        PHP_EOL
    );
}
      

Python

def main(client, customer_id):
    """Creates a rule-based user list.

    The list will be defined by an expression rule for users who have visited
    two different pages of a website.

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

    user_list_rule_info = client.get_type("UserListRuleInfo")

    # Combine the two rule items into a UserListRuleItemGroupInfo object so
    # Google Ads will AND their rules together. To instead OR the rules
    # together, each rule should be placed in its own rule item group.
    user_list_rule_item_group_info = client.get_type(
        "UserListRuleItemGroupInfo"
    )

    # Create rules targeting any user that visits the URLs in URL_LIST.
    for url in URL_LIST:
        user_list_rule_item_group_info.rule_items.append(
            _build_visited_site_rule_info(client, url)
        )
    user_list_rule_info.rule_item_groups.append(user_list_rule_item_group_info)

    # Creates an ExpressionRuleUserListInfo object, or a boolean rule that
    # defines this user list. The default rule_type for a UserListRuleInfo
    # object is OR of ANDs (disjunctive normal form). That is, rule items will
    # be ANDed together within rule item groups and the groups themselves will
    # be ORed together.
    expression_rule_user_list_info = client.get_type(
        "ExpressionRuleUserListInfo"
    )
    client.copy_from(expression_rule_user_list_info.rule, user_list_rule_info)

    # Define a representation of a user list that is generated by a rule.
    rule_based_user_list_info = client.get_type("RuleBasedUserListInfo")
    # Optional: To include past users in the user list, set the
    # prepopulation_status to REQUESTED.
    rule_based_user_list_info.prepopulation_status = client.get_type(
        "UserListPrepopulationStatusEnum"
    ).UserListPrepopulationStatus.REQUESTED
    client.copy_from(
        rule_based_user_list_info.expression_rule_user_list,
        expression_rule_user_list_info,
    )

    # Create a UserListOperation and populate the UserList.
    user_list_operation = client.get_type("UserListOperation")
    user_list = user_list_operation.create
    joined_urls = " AND ".join(URL_LIST)
    user_list.name = f"All visitors to {joined_urls} #{uuid4()}"
    user_list.description = f"Visitors of {joined_urls}"
    user_list.membership_status = client.get_type(
        "UserListMembershipStatusEnum"
    ).UserListMembershipStatus.OPEN
    user_list.membership_life_span = 365
    client.copy_from(user_list.rule_based_user_list, rule_based_user_list_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 expression rule user list with resource name "
        f"'{response.results[0].resource_name}.'"
    )


def _build_visited_site_rule_info(client, url):
    """Creates a UserListRuleItemInfo object targeting a visit to a given URL.

    Args:
        client: An initialized Google Ads client.
        url: The URL at which the rule will be targeted.
    Returns:
        A populated UserListRuleItemInfo object.
    """
    user_visited_site_rule = client.get_type("UserListRuleItemInfo")
    # Use a built-in parameter to create a domain URL rule.
    user_visited_site_rule.name = "url__"
    user_visited_site_rule.string_rule_item.operator = client.get_type(
        "UserListStringRuleItemOperatorEnum"
    ).UserListStringRuleItemOperator.CONTAINS
    user_visited_site_rule.string_rule_item.value = url

    return user_visited_site_rule
      

Ruby

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

  # Creates a user list.
  operation = client.operation.create_resource.user_list do |u|
    u.name = "All visitors to example.com/section1 AND example.com/section2 #" \
      "#{(Time.new.to_f * 1000).to_i}"
    u.description = "Visitors of both example.com/section1 AND " \
      "example.com/section2"
    u.membership_status = :OPEN
    u.membership_life_span = 365
    # Defines a representation of a user list that is generated by a rule.
    u.rule_based_user_list = client.resource.rule_based_user_list_info do |r|
      # Optional: To include past users in the user list, set
      # the prepopulation_status to REQUESTED.
      r.prepopulation_status = :REQUESTED
      # Creates an ExpressionRuleUserListInfo object, or a boolean rule that
      # defines this user list. The default rule_type for a user_list_rule_info
      # object is OR of ANDs (disjunctive normal form). That is, rule items will
      # be ANDed together within rule item groups and the groups themselves will
      # be ORed together.
      r.expression_rule_user_list =
        client.resource.expression_rule_user_list_info do |expr|
        expr.rule = client.resource.user_list_rule_info do |info|
          # Combines the two rule items into a UserListRuleItemGroupInfo object
          # so Google Ads will AND their rules together. To instead OR the rules
          # together, each rule should be placed in its own rule item group.
          info.rule_item_groups << client.resource.user_list_rule_item_group_info do |group|
            # Creates a rule targeting any user that visited a url that contains
            # 'example.com/section1'.
            group.rule_items << client.resource.user_list_rule_item_info do |item|
              # Uses a built-in parameter to create a domain URL rule.
              item.name = URL_STRING
              item.string_rule_item = client.resource.user_list_string_rule_item_info do |string_rule|
                string_rule.operator = :CONTAINS
                string_rule.value = "example.com/section1"
              end
            end
            # Creates a rule targeting any user that visited a url that contains
            # 'example.com/section2'.
            group.rule_items << client.resource.user_list_rule_item_info do |item|
              # Uses a built-in parameter to create a domain URL rule.
              item.name = URL_STRING
              item.string_rule_item = client.resource.user_list_string_rule_item_info do |string_rule|
                string_rule.operator = :CONTAINS
                string_rule.value = "example.com/section2"
              end
            end
          end
        end
      end
    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 user list with resource name " \
    "#{response.results.first.resource_name}"
end
      

Perl

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

  # Create a rule targeting any user that visited a URL that contains
  # 'example.com/section1'.
  my $rule1 = Google::Ads::GoogleAds::V7::Common::UserListRuleItemInfo->new({
      # Use a built-in parameter to create a domain URL rule.
      name           => URL_STRING,
      stringRuleItem =>
        Google::Ads::GoogleAds::V7::Common::UserListStringRuleItemInfo->new({
          operator => CONTAINS,
          value    => "example.com/section1"
        })});

  # Create a rule targeting any user that visited a URL that contains
  # 'example.com/section2'.
  my $rule2 = Google::Ads::GoogleAds::V7::Common::UserListRuleItemInfo->new({
      # Use a built-in parameter to create a domain URL rule.
      name           => URL_STRING,
      stringRuleItem =>
        Google::Ads::GoogleAds::V7::Common::UserListStringRuleItemInfo->new({
          operator => CONTAINS,
          value    => "example.com/section2"
        })});

  # Create an ExpressionRuleUserListInfo object, or a boolean rule that defines
  # this user list. The default rule_type for a UserListRuleInfo object is OR of
  # ANDs (disjunctive normal form). That is, rule items will be ANDed together
  # within rule item groups and the groups themselves will be ORed together.
  my $expression_rule_user_list_info =
    Google::Ads::GoogleAds::V7::Common::ExpressionRuleUserListInfo->new({
      rule => Google::Ads::GoogleAds::V7::Common::UserListRuleInfo->new({
          ruleItemGroups => [
            # Combine the two rule items into a UserListRuleItemGroupInfo object
            # so Google Ads will AND their rules together. To instead OR the rules
            # together, each rule should be placed in its own rule item group.
            Google::Ads::GoogleAds::V7::Common::UserListRuleItemGroupInfo->new(
              {ruleItems => [$rule1, $rule2]})]})});

  # Define a representation of a user list that is generated by a rule.
  my $rule_based_user_list_info =
    Google::Ads::GoogleAds::V7::Common::RuleBasedUserListInfo->new({
      # Optional: To include past users in the user list, set the prepopulationStatus
      # to REQUESTED.
      prepopulationStatus    => REQUESTED,
      expressionRuleUserList => $expression_rule_user_list_info
    });

  # Create a user list.
  my $user_list = Google::Ads::GoogleAds::V7::Resources::UserList->new({
    name =>
      "All visitors to example.com/section1 AND example.com/section2 #" .
      uniqid(),
    description =>
      "Visitors of both example.com/section1 AND example.com/section2",
    membershipStatus   => OPEN,
    membershipLifeSpan => 365,
    ruleBasedUserList  => $rule_based_user_list_info
  });

  # Create the operation.
  my $user_list_operation =
    Google::Ads::GoogleAds::V7::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 user list with resource name '%s'.\n",
    $user_lists_response->{results}[0]{resourceName};

  return 1;
}
      

Using custom remarketing tag parameters

You can add custom remarketing tag parameters to your remarketing tag to create more tailored user lists.

Before creating your own custom parameters, check out the list of predefined parameters to see if there's already a good fit for your use case. Using predefined parameters makes it easier to integrate with other Google Ads remarketing features.