“会员目标客户匹配”服务概览

本指南介绍了如何在 Merchant API 中使用会员客户匹配服务。借助此服务，商家和代表商家的第三方会员回馈服务提供商可以管理客户会员回馈数据（例如用户标识符和层级信息），以便在 Google 搜索上进行自然个性化设置，而无需有效的 Google Ads 账号。

概览

使用会员回馈目标客户匹配服务上传会员数据，这些数据随后会用于在 Google 搜索中提供自然会员个性化功能，例如显示会员专享价格。您可以使用 ManageLoyaltyCustomerMatch 自定义方法将客户与会员回馈活动层级相关联，从而根据用户标识符插入、更新或移除其会员回馈活动状态。

主要概念

  • 统一接口：用于添加、更新或移除客户会员等级详情的唯一端点。
  • 隐私至上的设计：为保护用户隐私并防止未经授权的账号探测，该 API 不支持 GET 或 LIST 操作，从而确保在不检索或审核的情况下管理数据。
  • 灵活识别：使用至少一个有效标识符（例如邮箱、实际地址或电话号码）匹配用户。
  • 基于同意的处理：仅当最终用户向 Google 授予必要的同意时，该服务才会存储和使用客户数据。为了保护和防止账号存在探测或同意情况，如果未匹配或未获得同意，该服务会返回静默成功。

前提条件

如需使用会员回馈目标客户匹配服务，请遵循以下要求：

  • 账号设置：确保您拥有有效的 Merchant Center 账号（如果您是第三方会员回馈活动提供商，则需要拥有对商家账号的授权访问权限）。您无需创建 Google Ads 账号即可使用会员卡目标客户匹配服务。
  • 会员回馈活动配置：在 Merchant Center 账号中启用会员回馈活动，并确保您已定义会员层级。
  • 注意层级顺序：请注意在 Merchant Center 界面中定义会员层级的顺序。 API 会使用此确切序列进行枚举映射。

方法：ManageLoyaltyCustomerMatch

ManageLoyaltyCustomerMatch 方法是管理客户忠诚度关联的中央接口。根据提供的输入，该服务会自动确定是插入、更新还是移除客户的会员卡层级状态。该操作是幂等的：重复的相同请求与单个请求具有相同的效果。

以下请求演示了如何通过 API 管理客户会员卡关联：

POST https://merchantapi.googleapis.com/{API_VERSION}/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage

此请求定义了以下必需的路径参数：

  • API_VERSION：API 版本，例如 v1。
  • ACCOUNT_ID：Merchant Center 账号 ID。

在请求正文中添加 loyaltyCustomer 对象。

{
    "userIdentifier": {
      "emailAddress": "string",
      "address": {
        "addressLines": ["string"],
        "locality": "string",
        "administrativeArea": "string",
        "postalCode": "string",
        "regionCode": "string"
      },
      "phoneNumber": "string"
    },
    "loyaltyTier": "LoyaltyTier",
    "pointBalance": "integer"
  }

loyaltyCustomer 字段

  • userIdentifier：用于匹配客户的一组标识符。userIdentifier 中必须至少提供一个有效字段。
  • loyaltyTier：要与客户关联的会员卡等级。对应于 Merchant Center 设置中的层级顺序。 如需了解详情，请参阅了解 loyaltyTier 映射。 使用 NON_MEMBER 移除现有关联。
  • pointBalance：客户当前的积分余额。

userIdentifier 字段

请至少提供以下字段中的一个：

  • emailAddress：客户的邮箱。
  • address：客户的实际地址。必须填写邮政编码。
  • phoneNumber：客户的电话号码。建议使用 E.164 格式。

了解 loyaltyTier 映射

该 API 不使用自定义名称。loyaltyTier 枚举值（TIER1 到 TIER7）是语义标签。它们不会使用您在 Merchant Center 界面中分配的自定义名称（例如“Gold Rewards”）或自定义标签（例如“gold_tier”）。而是严格映射到您在 Merchant Center 的会员回馈活动设置中定义层级的顺序：

  • TIER1：对应于 Merchant Center 会员回馈活动配置中列出的第一个层级。
  • TIER2：对应于 Merchant Center 会员回馈活动配置中列出的第二个层级。
  • TIER3 到 TIER7：对应于 Merchant Center 会员回馈活动配置中列出的第三到第七个层级。

示例：

如果您的 Merchant Center 会员回馈活动按以下顺序定义了层级：

  1. 层级名称：“Silver Status”，层级标签：“silver”
  2. 层级名称：“Gold Member”，层级标签：“gold”
  3. 层级名称：“Platinum Elite”，层级标签：“platinum”

然后，在 accounts.loyaltyCustomers.manage API 调用中：

  • 如需将客户分配到“白银状态”，您必须使用 loyaltyTier: TIER1。
  • 如需将客户分配到“金牌会员”，您必须使用 loyaltyTier: TIER2。
  • 如需将客户分配到“白金精英”，您必须使用 loyaltyTier: TIER3。

LoyaltyTier 枚举值

  • TIER1
  • TIER2
  • TIER3
  • TIER4
  • TIER5
  • TIER6
  • TIER7
  • NON_MEMBER（用于表示移除客户的会员卡关联）

了解 ManageLoyaltyCustomerMatch 响应正文

ManageLoyaltyCustomerMatch 方法会返回一个 ManageLoyaltyCustomerMatchResponse 对象：

{
  "loyaltyCustomer": {
    // loyaltyCustomer object from the request
  }
}

有关回答的重要注意事项

  • 成功执行 upsert（数据已存储）：如需成功存储或更新客户的会员卡层级关联，请满足以下条件：

    • 您将 Google 用户与提供的 userIdentifier 进行匹配
    • 您将请求中的 loyaltyTier 设置为 NON_MEMBER 以外的有效值
    • 匹配的用户已同意使用会员卡数据

响应包含请求中的 loyaltyCustomer 对象，表示服务已成功处理并存储数据：

{
  "loyaltyCustomer": {
    "userIdentifier": {
     "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
    }
}
  • 成功删除：如需成功移除客户与此商家的任何现有会员卡关联，必须满足以下条件：
    • 您与某个 Google 用户匹配，该用户具有提供的 userIdentifier
    • 您将请求中的 loyaltyTier 设置为 NON_MEMBER

响应是一个空的 JSON 对象：

{}
  • 不匹配/未同意（静默成功）：如果提供的 userIdentifier 与 Google 账号不匹配，或者匹配的用户未同意使用会员回馈数据，则 API 会返回 HTTP 200 OK 状态，并附带一个空的 JSON 对象：{}。无论是尝试 upsert 还是尝试移除，都会发生这种情况。

示例

TIER1 对应于第一个定义的层级（例如 'Basic'），TIER2 对应于第二个层级（例如 'Premium'）。

如需将客户添加到 TIER2 或使用电子邮件地址更新其状态，请发送以下请求：

POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage"
  -d '{
      "userIdentifier": {
        "emailAddress": "customer@example.com"
      },
      "loyaltyTier": "TIER2",
      "pointBalance": 1500
  }'

当用户成功匹配并同意后，API 会返回以下响应：

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
  }
}

如果没有匹配项或用户未同意，该 API 会返回以下响应：

{}

如需使用电话号码移除客户的会员卡关联，请发送以下请求：

POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage" \
  -d '{
      "userIdentifier": {
        "phoneNumber": "+18005550132"
      },
      "loyaltyTier": "NON_MEMBER"
  }'

无论记录是否存在，API 都会返回以下成功响应：

{}

如需使用多个标识符添加或更新客户，请发送以下请求：

POST
"https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/loyaltyCustomers:manage" \
  -d '{
      "userIdentifier": {
        "emailAddress": "user@example.com",
        "address": {
          "postalCode": "94043",
          "regionCode": "US"
        }
      },
      "loyaltyTier": "TIER1"
  }'

响应与第一个示例类似，具体取决于匹配和用户同意情况。

错误处理

该 API 使用标准 HTTP 代码。常见错误字符串包括：

HTTP 代码 错误字符串 说明
400 INVALID_ARGUMENT 缺少 user_identifier 或 loyalty_tier，或者标识符为空。
401 UNAUTHENTICATED 凭据无效或缺失。
403 PERMISSION_DENIED 经过身份验证的用户无权访问指定的 Merchant Center 账号。
404 NOT_FOUND 您的配置中不存在指定的会员层级标签。
412 FAILED_PRECONDITION 您尚未在账号中配置会员回馈活动。
429 RESOURCE_EXHAUSTED 已达到配额上限。

错误示例

404 NOT_FOUND 示例：

向未配置会员回馈活动的账号 ID 发出的任何有效请求。

API 会返回以下错误响应：

{
  "error": {
    "code": 404,
    "message": "The loyalty program is not found for account: {ACCOUNT_ID}.",
    "status": "NOT_FOUND",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "notFound",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "ACCOUNT_ID": "{ACCOUNT_ID}",
          "REASON": "NOT_FOUND_LOYALTY_PROGRAM"
        }
      }
    ]
  }
}

原因：路径中的商家账号没有有效的会员回馈活动。

400 INVALID_ARGUMENT 示例：

如果请求包含 loyaltyTier 字段的无效值，则会发生错误：

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER11",
    "pointBalance": 100
  }
}

API 会返回以下错误响应：

{
  "error": {
    "code": 400,
    "message": "Invalid value at 'loyalty_customer.loyalty_tier' (type.googleapis.com/google.shopping.merchant.loyaltycustomers.v1.LoyaltyCustomer.LoyaltyTier), \"TIER11\"",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "loyalty_customer.loyalty_tier",
            "description": "Invalid value at 'loyalty_customer.loyalty_tier' (type.googleapis.com/google.shopping.merchant.loyaltycustomers.v1.LoyaltyCustomer.LoyaltyTier), \"TIER11\""
          }
        ]
      }
    ]
  }
}

原因： TIER11 不是 loyaltyTier 的有效枚举值。当您尝试在只有一个层级可用时指定 TIER2，也可能会发生同样的错误。

如果请求正文中缺少必需的 loyaltyTier 字段，则会发生错误：

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "pointBalance": 100
  }
}

API 会返回以下错误响应：

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.loyalty_tier] Required field not provided: loyalty_customer.loyalty_tier",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "required",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_LOCATION": "loyalty_customer.loyalty_tier",
          "REASON": "MISSING_REQUIRED_FIELD"
        }
      }
    ]
  }
}

原因：loyaltyTier 字段为必填字段。

如果地址标识符不完整（例如缺少 postalCode 字段），则会发生错误：

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "address": {
        "locality": "Sunnyvale",
        "administrativeArea": "CA",
        "regionCode": "US"
      }
    },
    "loyaltyTier": "TIER1",
    "pointBalance": 100
  }
}

API 会返回以下错误响应：

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.user_identifier] The format of loyalty_customer.user_identifier does not match the expected format ... Value: at least one valid user identifier should be provided.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_NAME": "loyalty_customer.user_identifier",
          "REASON": "INVALID_VALUE"
        }
      }
    ]
  }
}

原因：虽然提供了地址，但缺少必需的 postalCode 字段，因此不被视为有效标识符。

如果您请求的层级索引超出所配置计划的范围，则会发生错误：

场景：商家在 Merchant Center 中仅配置了一个层级。

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 100
  }
}

API 会返回以下错误响应：

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.loyalty_tier] The format of loyalty_customer.loyalty_tier does not match the expected format `valid LoyaltyTier`. Value: TIER2.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_NAME": "loyalty_customer.loyalty_tier",
          "PATTERN": "valid LoyaltyTier",
          "FIELD_VALUE": "TIER2",
          "REASON": "INVALID_VALUE"
        }
      }
    ]
  }
}

原因：请求了 TIER2，但与账号关联的会员回馈活动未定义第二层级。

如果请求包含格式错误的 emailAddress，则会发生错误：

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@google"
    },
    "loyaltyTier": "TIER1",
    "pointBalance": 100
  }
}

API 会返回以下错误响应：

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.user_identifier] The format of loyalty_customer.user_identifier does not match the expected format `email_address: \t \"customer@google\"\n`. Value: at least one valid user identifier should be provided.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_NAME": "loyalty_customer.user_identifier",
          "REASON": "INVALID_VALUE"
        }
      }
    ]
  }
}

原因：邮箱格式无效。

如果 userIdentifier 对象为空，则会发生错误：

{
  "loyaltyCustomer": {
    "userIdentifier": {},
    "loyaltyTier": "TIER1",
    "pointBalance": 100
  }
}

API 会返回以下错误响应：

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.user_identifier] Required field not provided: loyalty_customer.user_identifier",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "required",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_LOCATION": "loyalty_customer.user_identifier",
          "REASON": "MISSING_REQUIRED_FIELD"
        }
      }
    ]
  }
}

原因：userIdentifier 对象存在，但不包含实际标识符字段。

注意：标识符验证。

  • API 会对标识符执行基本格式检查（例如，电子邮件结构、地址中是否存在 postalCode）。
  • 不过，某些通过初始检查的标识符可能与任何 Google 用户账号都不匹配，或者可能不采用后端匹配系统可识别的格式。在这种情况下，您将收到静默成功空响应 {}，其 HTTP 状态为 200 OK。

最佳做法

请遵循以下最佳实践来优化集成。

  • 对于大规模集成：由于 API 按请求运行，因此需要客户端并行处理，才能实现大型数据集所需的吞吐量。您应设计集成来管理多个并发请求。如需了解如何通过并行化来构建实现以处理更高的请求量，请参阅如何发送多个请求指南。

  • 配额管理：默认配额为 1,000,000 次请求/天和 10,000 次请求/分钟。如需了解如何监控和检查配额，请参阅配额和限制。

  • 优先考虑电子邮件地址：尽可能在 userIdentifier 中添加客户的 emailAddress。邮箱通常是最准确、最可靠的标识符，可用于将用户与其 Google 账号进行匹配。

  • 处理空响应：将应用设计为正确地将空 {} 响应解读为成功，并理解这意味着由于隐私原因（不匹配或未征得同意），数据未存储。请勿重试请求。

  • 验证层级顺序：请务必在 Merchant Center 界面中确认会员层级的顺序，以确保在 API 调用中使用正确的 TIER1 到 TIER7 枚举值。此映射基于界面中定义的顺序，而不是其名称。

  • 监控错误：记录并监控 API 响应，注意任何 4xx 错误以捕获集成问题，尤其是可能表示层级理解不匹配的 404 错误。

上一页
Manage loyalty programs