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(StringValue.of(urlString))
          .setStringRuleItem(
              UserListStringRuleItemInfo.newBuilder()
                  .setOperator(UserListStringRuleItemOperator.CONTAINS)
                  .setValue(StringValue.of("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(StringValue.of(urlString))
          .setStringRuleItem(
              UserListStringRuleItemInfo.newBuilder()
                  .setOperator(UserListStringRuleItemOperator.CONTAINS)
                  .setValue(StringValue.of("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(
              StringValue.of(
                  "All visitors to example.com/section1 AND example.com/section2 #"
                      + System.currentTimeMillis()))
          .setDescription(
              StringValue.of("Visitors of both example.com/section1 AND example.com/section2"))
          .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);
  }
}

C#

public void Run(GoogleAdsClient client, long customerId)
{
    // Gets the UserListService.
    UserListServiceClient userListServiceClient =
        client.GetService(Services.V5.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' => new StringValue(['value' => self::URL_STRING]),
        'string_rule_item' => new UserListStringRuleItemInfo([
            'operator' => UserListStringRuleItemOperator::CONTAINS,
            'value' => new StringValue(['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' => new StringValue(['value' => self::URL_STRING]),
        'string_rule_item' => new UserListStringRuleItemInfo([
            'operator' => UserListStringRuleItemOperator::CONTAINS,
            'value' => new StringValue(['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' => new StringValue(['value' =>
            'All visitors to example.com/section1 AND example.com/section2 #' . uniqid()
        ]),
        'description' => new StringValue(['value' =>
            'Visitors of both example.com/section1 AND example.com/section2'
        ]),
        'membership_status' => UserListMembershipStatus::OPEN,
        'membership_life_span' => new Int64Value(['value' => 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
    );
}

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::V5::Common::UserListRuleItemInfo->new({
      # Use a built-in parameter to create a domain URL rule.
      name => URL_STRING,
      stringRuleItem =>
        Google::Ads::GoogleAds::V5::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::V5::Common::UserListRuleItemInfo->new({
      # Use a built-in parameter to create a domain URL rule.
      name => URL_STRING,
      stringRuleItem =>
        Google::Ads::GoogleAds::V5::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::V5::Common::ExpressionRuleUserListInfo->new({
      rule => Google::Ads::GoogleAds::V5::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::V5::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::V5::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::V5::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::V5::Services::UserListService::UserListOperation->
    new({
      create => $user_list
    });

  # Issue a mutate request to add the user list and print some information.
  my $user_list_response = $api_client->UserListService()->mutate({
      customerId => $customer_id,
      operations => [$user_list_operation]});
  printf "Created user list with resource name '%s'.\n",
    $user_list_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.