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.

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);
  }
}
AddCombinedRuleUserList.java
      

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;
}
AddCombinedRuleUserList.cs
      

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
    );
}
AddCombinedRuleUserList.php
      

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
add_combined_rule_user_list.py
      

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
add_combined_rule_user_list.rb
      

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;
}
add_combined_rule_user_list.pl
      

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.