← 返回目录
来源:Google Ads API 官方文档 · 中文版 · 本地归档

开始使用目标客户匹配

借助目标客户匹配功能,您可以利用您的线上及线下数据,在搜索网络、“购物”标签页、Gmail、YouTube 和展示广告网络上覆盖和重新吸引客户。目标客户匹配功能利用客户与您分享的信息,将广告定位到相应客户及其他类似客户。您可以 批量上传客户关系管理 (CRM) 数据、添加或移除 数据,或者使用这些用户列表创建 logical_user_list。

如需查看不同类型的受众群体 细分受众群列表,并将目标客户匹配与其他用户列表选项进行比较,请参阅受众群体管理概览。

详细了解目标客户匹配和受众群体定位。

前提条件

并非所有账号都有资格使用目标客户匹配功能。如需使用目标客户匹配功能,您的账号必须满足以下要求:

  • 政策遵从记录良好
  • 付款记录良好

根据您的账号满足的要求,您可以使用不同的功能。如需了解资格要求和限制,请参阅目标客户匹配 政策。

开始之前:规划实现方案

在开始编写任何代码之前,请务必规划目标客户匹配实现方案。本部分概述了整个流程和关键注意事项,可帮助您设计稳健的集成方案。制定明确的计划后,您就可以继续执行后续的实现步骤了。

使用流程

以下是创建客户名单并定位到该名单的推荐流程:

  1. 创建空的客户名单。

  2. 创建 OfflineUserDataJob。与创建多个较小的作业相比,创建单个大型作业的效率要高得多。

    请确保在 OfflineUserDataJob create 请求中填充 customer_match_user_list_metadata 的 consent 字段。对于 remove 请求,不需要征得用户同意。如果作业的 consent.ad_user_data 或 consent.ad_personalization 设置 为 DENIED,API 会返回 OfflineUserDataJobError.CUSTOMER_NOT_ACCEPTED_CUSTOMER_DATA_TERMS 。

    如果用户拒绝了同意,您可以创建一个包含 remove 操作的作业,以从用户列表中移除用户的标识符。

    如果您缺少特定用户的同意,请创建一个单独的作业,在该作业中,您无需设置作业的 customer_match_user_list_metadata 的 consent 字段,然后使用该单独作业的 create 操作为这些用户添加标识符。

  3. 使用 OfflineUserDataJobService.AddOfflineUserDataJobOperations 方法添加操作。我们建议您在一次调用中添加最多 10,000 个标识符,以获得最佳处理效果。单个 AddOfflineUserDataJobOperations 请求 最多可以包含操作列表中的所有 UserData 对象中的 100,000 个标识符。

    例如,如果您的每个 UserData 对象都有一个 hashed_email 的 UserIdentifier 和另一个 hashed_phone_number 的 UserIdentifier,那么每个请求发送 5,000 个 UserData 对象是最佳做法,因为每个请求总共包含 10,000 个用户标识符。

  4. 重复上一步,直到添加所有操作或作业达到容量上限。您可以向单个作业添加的操作数量没有限制;不过,我们建议每个作业的操作数量不超过 1,000,000 个,以获得最佳处理效果。

  5. 运行作业。您必须在创建作业后的 5 天内运行该作业。 否则,该作业将无法再运行。

  6. 轮询以查看上传是否成功。

  7. 验证匹配率。

  8. 定位到该列表。

OfflineUserDataJobService 和 UserDataService

您可以使用两种服务上传目标客户匹配数据。请根据您的使用场景选择服务,因为服务可能会有限制。

目标客户匹配数据上传服务
OfflineUserDataJobService (首选) 大多数开发者都使用此服务。此服务针对高吞吐量的大规模上传进行了优化,并在完成时返回成功指标。本指南 主要介绍此服务。
UserDataService 此服务经过优化,可一次上传少量标识符并进行零星更新 ,但未针对持续运行进行优化。每个请求最多可以包含 10 个操作。此外,单个请求在所有 user_identifiers 中总共不能包含超过 100 个项。

如需了解有关使用此服务进行上传的指南 ,请访问管理目标客户匹配集成指南 。

您应在 UploadUserDataRequest create 请求中填充 customer_match_user_list_metadata 的 consent 字段。对于 remove 请求,不需要征得用户同意。 如果 consent.ad_user_data 或 consent.ad_personalization 为 DENIED,API 会返回一个响应,并将 received_operations_count 设置为零,表示请求未得到处理。如果标识符的同意状态为 DENIED, 您可以请求使用 remove 操作从用户列表中移除该标识符。UploadUserDataRequest

最佳实践

在设计目标客户匹配集成时,请牢记以下最佳实践:

  • 请勿尝试使用多个账号修改单个用户列表。用户 列表只能由创建该列表的 Google Ads 账号或数据合作伙伴账号 修改。

  • 尽可能增加每个 AddOfflineUserDataJobOperationsRequest的操作数量(最多 100,000 个标识符),以 避免 RESOURCE_EXHAUSTED 错误。

  • 请勿在同一 OfflineUserDataJob中混合使用create和remove操作。这样做可能会导致 CONFLICTING_OPERATION错误。

  • 在 AddOfflineUserDataJobOperationsRequest 中启用 partial_failure,以便在运行作业之前检测到任何存在问题的操作。 操作在上传到 OfflineUserDataJob 时会经过验证。

  • 如需在更新用户列表时避免 CONCURRENT_MODIFICATION 错误,请执行以下操作:

    避免同时有多个 OfflineUserDataJob 进程处于 RUNNING 状态,如果它们定位到同一用户列表资源 名称(在 CustomerMatchUserListMetadata.user_list 中指定)。发生此错误的原因是多个作业尝试同时修改同一列表。如果您在 API 作业正在处理时通过 Google Ads 界面修改列表,也可能会出现此冲突。

    此限制适用于已启动(即处于 RUNNING 状态)的作业。相比之下,您可以安全地发出多个 AddOfflineUserDataJobOperations 请求,以向仍处于 PENDING 状态的单个 OfflineUserDataJob 添加数据。您可以在调用RunOfflineUserDataJob以启动该进程之前的任何时间向作业添加操作 。

  • 如果您有数千个操作要应用,请创建一个包含所有操作的 OfflineUserDataJob。 请勿创建多个作业,每个作业仅包含数百个操作,然后按顺序或同时运行这些作业。与多个小型作业相比,包含所有操作的单个大型作业的效率要高得多,并且可以减少工作流中出现错误的可能性。

如需了解如何使用客户名单以获得最佳定位效果,请参阅 目标客户匹配最佳实践。

第 1 步:创建客户名单

使用 UserListService创建客户名单。客户名单是通过在 user_list对象上设置 crm_based_user_list字段来创建的。可以在支持定位客户名单的广告系列类型上设置 crm_based_user_list 字段:

不同广告系列类型中的目标客户匹配
搜索网络 广告在搜索网络上展示。
展示广告网络 广告在展示广告网络上展示,并且仅当有 GSP 广告素材时才会在 Gmail 上展示。
将展示广告网络也纳入投放范围 的搜索广告系列 广告在搜索网络上展示,并且仅当有 GSP 广告素材时才会在 Gmail 上展示。
视频广告系列 广告仅当有 TrueView 插播广告时才会在 YouTube 上展示。
购物广告系列 广告在“购物”标签页中展示。

crm_based_user_list 包含三个字段:

  • app_id:一个字符串,用于唯一标识收集数据的移动应用。为上传移动广告 ID 创建 CrmBasedUserList 时,必须提供此字段。

  • upload_key_type:列表的匹配键类型,可以是 CONTACT_INFO、CRM_ID 或 MOBILE_ADVERTISING_ID。同一列表中不允许混合使用数据类型。 所有客户名单都必须提供此字段。

  • data_source_type:列表的数据源。默认值为 FIRST_PARTY。列入许可名单的客户可以创建第三方来源的客户名单。

借助用户列表的 membership_life_span 属性,您可以定义 用户被视为在列表中的时间段(以天为单位)。目标客户匹配用户列表的 membership_life_span 不得超过 540,这也是默认值。

The membership_status attribute 用于定义列表是否接受新用户。

用于创建客户名单的代码示例

Java

private String createCustomerMatchUserList(GoogleAdsClient googleAdsClient, long customerId) {
  // Creates the new user list.
  UserList userList =
      UserList.newBuilder()
          .setName("Customer Match list #" + getPrintableDateTime())
          .setDescription("A list of customers that originated from email addresses")
          // Membership life span must be between 0 and 540 days inclusive. See:
          // https://developers.google.com/google-ads/api/reference/rpc/latest/UserList#membership_life_span
          // Sets the membership life span to 30 days.
          .setMembershipLifeSpan(30)
          // Sets the upload key type to indicate the type of identifier that will be used to
          // add users to the list. This field is immutable and required for a CREATE operation.
          .setCrmBasedUserList(
              CrmBasedUserListInfo.newBuilder()
                  .setUploadKeyType(CustomerMatchUploadKeyType.CONTACT_INFO))
          .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 Customer Match user list with resource name: %s.%n",
        response.getResults(0).getResourceName());
    return response.getResults(0).getResourceName();
  }
}

      

C#

private string CreateCustomerMatchUserList(GoogleAdsClient client, long customerId)
{
    // Get the UserListService.
    UserListServiceClient service = client.GetService(Services.V25.UserListService);

    // Creates the user list.
    UserList userList = new UserList()
    {
        Name = $"Customer Match list# {ExampleUtilities.GetShortRandomString()}",
        Description = "A list of customers that originated from email and physical" +
            " addresses",
        // Membership life span must be between 0 and 540 days inclusive. See:
        // https://developers.google.com/google-ads/api/reference/rpc/latest/UserList#membership_life_span
        // Sets the membership life span to 30 days.
        MembershipLifeSpan = 30,
        CrmBasedUserList = new CrmBasedUserListInfo()
        {
            UploadKeyType = CustomerMatchUploadKeyType.ContactInfo
        }
    };
    // Creates the user list operation.
    UserListOperation operation = new UserListOperation()
    {
        Create = userList
    };

    // Issues a mutate request to add the user list and prints some information.
    MutateUserListsResponse response = service.MutateUserLists(
        customerId.ToString(), new[] { operation });
    string userListResourceName = response.Results[0].ResourceName;
    Console.WriteLine($"User list with resource name '{userListResourceName}' " +
        $"was created.");
    return userListResourceName;
}
      

PHP

private static function createCustomerMatchUserList(
    GoogleAdsClient $googleAdsClient,
    int $customerId
): string {
    // Creates the user list.
    $userList = new UserList([
        'name' => 'Customer Match list #' . Helper::getPrintableDatetime(),
        'description' => 'A list of customers that originated from email '
            . 'and physical addresses',
        // Membership life span must be between 0 and 540 days inclusive. See:
        // https://developers.google.com/google-ads/api/reference/rpc/latest/UserList#membership_life_span
        // Sets the membership life span to 30 days.
        'membership_life_span' => 30,
        'crm_based_user_list' => new CrmBasedUserListInfo([
            // Sets the upload key type to indicate the type of identifier that will be used to
            // add users to the list. This field is immutable and required for a CREATE
            // operation.
            'upload_key_type' => CustomerMatchUploadKeyType::CONTACT_INFO
        ])
    ]);

    // Creates the user list 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(
        MutateUserListsRequest::build($customerId, [$operation])
    );
    $userListResourceName = $response->getResults()[0]->getResourceName();
    printf("User list with resource name '%s' was created.%s", $userListResourceName, PHP_EOL);

    return $userListResourceName;
}
在接这个接口时卡住了?
Stuck wiring this API into production? We build ad-delivery tooling on these platforms — campaign automation, reporting pipelines, error-handling and migration between API versions.
联系我们 · Talk to us 每日平台更新简报 →