Learn more about migrating to the Google Ads API by watching our latest webinar

Visitors to Specific Pages

You can target people who have visited specific pages or sections of your website using an expression_rule_user_list targeted to more specific URLs, not just your website's domain.

See Rule-based remarketing for an example and more details.

Visitors of a page who did visit another page

You can target people who visited more than one page using a combined_rule_user_list. The targeting would be done the same way as in the previous example. Only the first step changes, where you use a combined_rule_user_list rather than an expression_rule_user_list.

First, create two rules. Then, combine the rules with the combined_rule_user_list.

Java

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

  // Creates a rule targeting any user that visited a url that equals
  // http://example.com/example1'.
  UserListRuleItemInfo userVisitedSite1Rule =
      UserListRuleItemInfo.newBuilder()
          // Uses a built-in parameter to create a domain URL rule.
          .setName(urlString)
          .setStringRuleItem(
              UserListStringRuleItemInfo.newBuilder()
                  .setOperator(UserListStringRuleItemOperator.EQUALS)
                  .setValue("http://example.com/example1")
                  .build())
          .build();

  // Creates a UserListRuleInfo object containing the first rule.
  UserListRuleInfo userVisitedSite1RuleInfo =
      UserListRuleInfo.newBuilder()
          .addRuleItemGroups(
              UserListRuleItemGroupInfo.newBuilder().addRuleItems(userVisitedSite1Rule).build())
          .build();

  // Creates a rule targeting any user that visited a url that equals
  // http://example.com/example2'.
  UserListRuleItemInfo userVisitedSite2Rule =
      UserListRuleItemInfo.newBuilder()
          // Uses a built-in parameter to create a domain URL rule.
          .setName(urlString)
          .setStringRuleItem(
              UserListStringRuleItemInfo.newBuilder()
                  .setOperator(UserListStringRuleItemOperator.EQUALS)
                  .setValue("http://example.com/example2")
                  .build())
          .build();

  // Creates a UserListRuleInfo object containing the second rule.
  UserListRuleInfo userVisitedSite2RuleInfo =
      UserListRuleInfo.newBuilder()
          .addRuleItemGroups(
              UserListRuleItemGroupInfo.newBuilder().addRuleItems(userVisitedSite2Rule).build())
          .build();

  // Creates the user list where "Visitors of a page who did visit another page". To create a user
  // list where "Visitors of a page who did not visit another page", change the
  // UserListCombinedRuleOperator from AND to AND_NOT.
  CombinedRuleUserListInfo combinedRuleUserListInfo =
      CombinedRuleUserListInfo.newBuilder()
          .setLeftOperand(userVisitedSite1RuleInfo)
          .setRightOperand(userVisitedSite2RuleInfo)
          .setRuleOperator(UserListCombinedRuleOperator.AND)
          .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)
          .setCombinedRuleUserList(combinedRuleUserListInfo)
          .build();

  // Creates a user list.
  UserList userList =
      UserList.newBuilder()
          .setName(
              "All visitors to http://example.com/example1 AND http://example.com/example2 #"
                  + getPrintableDateTime())
          .setDescription(
              "Visitors of both http://example.com/example1 AND http://example.com/example2")
          .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)
{
    // Get the UserListServiceClient.
    UserListServiceClient userListServiceClient =
        client.GetService(Services.V8.UserListService);

    // Creates a rule targeting any user that visited a url that equals
    // 'http://example.com/example1'.
    UserListRuleInfo userVisitedSite1RuleInfo =
        BuildVisitedSiteRuleInfo("http://example.com/example1");

    // Creates a rule targeting any user that visited a url that equals
    // 'http://example.com/example2'.
    UserListRuleInfo userVisitedSite2RuleInfo =
        BuildVisitedSiteRuleInfo("http://example.com/example2");

    // Creates the user list where "Visitors of a page who did visit another page".
    // To create a user list where "Visitors of a page who did not visit another page",
    // change the UserListCombinedRuleOperator from .And to .AndNot.
    CombinedRuleUserListInfo combinedRuleUserListInfo = new CombinedRuleUserListInfo()
    {
        LeftOperand = userVisitedSite1RuleInfo,
        RightOperand = userVisitedSite2RuleInfo,
        RuleOperator = UserListCombinedRuleOperator.And
    };

    // 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,
        CombinedRuleUserList = combinedRuleUserListInfo
    };

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

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

    try
    {
        // Adds the new user list and prints the result.
        MutateUserListsResponse response = userListServiceClient.MutateUserLists
            (customerId.ToString(), new[] { operation });
        Console.WriteLine("Created 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 UserListRuleInfo object targeting a visit to a specified URL.
/// </summary>
/// <param name="url">The URL at which the rule will be targeted.</param>
/// <returns>A populated UserListRuleInfo object.</returns>
private UserListRuleInfo 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.Equals,
            Value = url
        }
    };

    // Creates a UserListRuleInfo object containing the new rule.
    UserListRuleInfo userVisitedSiteRuleInfo = new UserListRuleInfo()
    {
        RuleItemGroups =
        {
            new UserListRuleItemGroupInfo()
            {
                RuleItems = {userVisitedSiteRule}
            }
        }
    };

    return userVisitedSiteRuleInfo;
}
      
      

PHP

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

    // Creates a UserListRuleInfo object containing the first rule.
    $userVisitedSite1RuleInfo = new UserListRuleInfo([
        'rule_item_groups' => [
            new UserListRuleItemGroupInfo([
                'rule_items' => [$userVisitedSite1Rule]
            ])
        ]
    ]);

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

    // Creates a UserListRuleInfo object containing the second rule.
    $userVisitedSite2RuleInfo = new UserListRuleInfo([
        'rule_item_groups' => [
            new UserListRuleItemGroupInfo([
                'rule_items' => [$userVisitedSite2Rule]
            ])
        ]
    ]);

    // Creates the user list where "Visitors of a page who did visit another page". To create a
    // user list where "Visitors of a page who did not visit another page", change the
    // UserListCombinedRuleOperator from PBAND to AND_NOT.
    $combinedRuleUserListInfo = new CombinedRuleUserListInfo([
        'left_operand' => $userVisitedSite1RuleInfo,
        'right_operand' => $userVisitedSite2RuleInfo,
        'rule_operator' => UserListCombinedRuleOperator::PBAND
    ]);

    // 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,
        'combined_rule_user_list' => $combinedRuleUserListInfo
    ]);

    // Creates a user list.
    $userList = new UserList([
        'name' => 'All visitors to http://example.com/example1 AND ' .
            'http://example.com/example2 #' . Helper::getPrintableDatetime(),
        'description' => 'Visitors of both http://example.com/example1 AND ' .
            'http://example.com/example2',
        '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 a combination of rules 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")

    rule_infos = []

    # Create rules targeting any user that visits "http://example.com/example1"
    # and "http://example.com/example2".
    for url in ["http://example.com/example1", "http://example.com/example2"]:
        rule_infos.append(_build_visited_site_rule_info(client, url))

    # The two rules are combined by joining the first AND second URLs. See
    # https://developers.google.com/google-ads/api/reference/rpc/latest/CombinedRuleUserListInfo
    # for more details.
    # This rule will create a user list where "Visitors of a page who did visit
    # another page". To create a user list where "Visitors of a page who did not
    # visit another page", change the UserListCombinedRuleOperator from AND to
    # AND_NOT.
    combined_rule_user_list_info = client.get_type("CombinedRuleUserListInfo")
    client.copy_from(combined_rule_user_list_info.left_operand, rule_infos[0])
    client.copy_from(combined_rule_user_list_info.right_operand, rule_infos[1])
    combined_rule_user_list_info.rule_operator = (
        client.enums.UserListCombinedRuleOperatorEnum.AND
    )

    # 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.enums.UserListPrepopulationStatusEnum.REQUESTED
    )
    client.copy_from(
        rule_based_user_list_info.combined_rule_user_list,
        combined_rule_user_list_info,
    )

    # Create a UserListOperation and populate the UserList.
    user_list_operation = client.get_type("UserListOperation")
    user_list = user_list_operation.create
    user_list.name = (
        "All visitors to http://example.com/example1 AND "
        f"http://example.com/example2 #{uuid4()}"
    )
    user_list.description = (
        "Visitors of both http://example.com/example1 AND "
        "http://example.com/example2"
    )
    user_list.membership_status = client.enums.UserListMembershipStatusEnum.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 combined user list with resource name "
        f"'{response.results[0].resource_name}.'"
    )


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

    Args:
        client: An initialized Google Ads client.
        url: The string URL at which the rule will be targeted.
    Returns:
        A populated UserListRuleInfo 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.enums.UserListStringRuleItemOperatorEnum.EQUALS
    )
    user_visited_site_rule.string_rule_item.value = url

    user_visited_site_rule_info = client.get_type("UserListRuleInfo")
    rule_item_group_info = client.get_type("UserListRuleItemGroupInfo")
    rule_item_group_info.rule_items.append(user_visited_site_rule)
    user_visited_site_rule_info.rule_item_groups.append(rule_item_group_info)

    return user_visited_site_rule_info
      
      

Ruby

def add_combined_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 http://example.com/example1 AND " \
      "http://example.com/example2 ##{(Time.new.to_f * 1000).to_i}"
    u.description = "Visitors of both http://example.com/example1 AND " \
      "http://example.com/example2"
    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 the user list where "Visitors of a page who did visit another
      # page". To create a user list where "Visitors of a page who did not visit
      # another page", change the rule_operator from AND to AND_NOT.
      r.combined_rule_user_list = client.resource.combined_rule_user_list_info do |c|
        # Creates a UserListRuleInfo object containing the first rule.
        c.left_operand = client.resource.user_list_rule_info do |rule|
          rule.rule_item_groups << client.resource.user_list_rule_item_group_info do |group|
            # Creates a rule targeting any user that visited a url that equals
            # 'http://example.com/example1'.
            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 = :EQUALS
                string_rule.value = "http://example.com/example1"
              end
            end
          end
        end
        # Creates a UserListRuleInfo object containing the second rule.
        c.right_operand = client.resource.user_list_rule_info do |rule|
          rule.rule_item_groups << client.resource.user_list_rule_item_group_info do |group|
            # Creates a rule targeting any user that visited a url that equals
            # 'http://example.com/example2'.
            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 = :EQUALS
                string_rule.value = "http://example.com/example2"
              end
            end
          end
        end
        c.rule_operator = :AND
      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_combined_rule_user_list {
  my ($api_client, $customer_id) = @_;

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

  # Create a UserListRuleInfo object containing the first rule.
  my $user_visited_site1_rule_info =
    Google::Ads::GoogleAds::V8::Common::UserListRuleInfo->new({
      ruleItemGroups =>
        Google::Ads::GoogleAds::V8::Common::UserListRuleItemGroupInfo->new({
          ruleItems => [$user_visited_site1_rule]})});

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

  # Create a UserListRuleInfo object containing the second rule.
  my $user_visited_site2_rule_info =
    Google::Ads::GoogleAds::V8::Common::UserListRuleInfo->new({
      ruleItemGroups =>
        Google::Ads::GoogleAds::V8::Common::UserListRuleItemGroupInfo->new({
          ruleItems => [$user_visited_site2_rule]})});

  # Create the user list where "Visitors of a page who did visit another page".
  # To create a user list where "Visitors of a page who did not visit another page",
  # change the UserListCombinedRuleOperator from AND to AND_NOT.
  my $combined_rule_user_list_info =
    Google::Ads::GoogleAds::V8::Common::CombinedRuleUserListInfo->new({
      leftOperand  => $user_visited_site1_rule_info,
      rightOperand => $user_visited_site2_rule_info,
      ruleOperator => AND
    });

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

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

  # Create the operation.
  my $user_list_operation =
    Google::Ads::GoogleAds::V8::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;
}
      
      

Visitors of a page who did not visit another page

You can target people who visited one page but not another page by using combined_rule_user_list. The only change that would have to be made to the previous example is that the rule_operator needs to change from AND to AND_NOT.