Tổng quan về Dịch vụ So khớp khách hàng trong chương trình khách hàng thân thiết

Hướng dẫn này mô tả cách sử dụng Dịch vụ so khớp khách hàng thân thiết trong Merchant API. Dịch vụ này cho phép người bán và nhà cung cấp chương trình khách hàng thân thiết bên thứ ba thay mặt người bán quản lý dữ liệu khách hàng thân thiết, chẳng hạn như giá trị nhận dạng người dùng và thông tin về cấp, để cá nhân hoá kết quả tự nhiên trên Google Tìm kiếm mà không cần có tài khoản Google Ads đang hoạt động.

Tổng quan

Sử dụng Dịch vụ so khớp khách hàng thân thiết để tải dữ liệu về khách hàng thân thiết lên. Sau đó, dữ liệu này sẽ được dùng để cung cấp các tính năng cá nhân hoá tự nhiên cho khách hàng thân thiết trên Google Tìm kiếm, chẳng hạn như hiển thị giá dành riêng cho thành viên. Bạn sử dụng phương thức tuỳ chỉnh ManageLoyaltyCustomerMatch để liên kết khách hàng với các cấp của chương trình khách hàng thân thiết, cho phép bạn chèn, cập nhật hoặc xoá trạng thái khách hàng thân thiết của họ dựa trên giá trị nhận dạng người dùng.

Khái niệm chính

  • Giao diện hợp nhất: Một điểm cuối duy nhất để thêm, cập nhật hoặc xoá thông tin chi tiết về cấp độ khách hàng thân thiết.
  • Thiết kế ưu tiên quyền riêng tư: Để bảo vệ quyền riêng tư của người dùng và ngăn chặn việc thăm dò tài khoản trái phép, API này không hỗ trợ các thao tác GET hoặc LIST, đảm bảo rằng dữ liệu được quản lý mà không cần truy xuất hoặc kiểm tra.
  • Nhận dạng linh hoạt: So khớp người dùng bằng ít nhất một giá trị nhận dạng hợp lệ, chẳng hạn như địa chỉ email, địa chỉ thực tế hoặc số điện thoại.
  • Xử lý dựa trên sự đồng ý: Dịch vụ chỉ lưu trữ và sử dụng dữ liệu khách hàng khi người dùng cuối đã cấp sự đồng ý cần thiết cho Google. Để bảo vệ và ngăn chặn việc thăm dò sự tồn tại của tài khoản hoặc trạng thái đồng ý, dịch vụ sẽ trả về trạng thái thành công thầm lặng nếu không có kết quả trùng khớp hoặc không được đồng ý.

Điều kiện tiên quyết

Hãy tuân thủ các yêu cầu sau để sử dụng Dịch vụ so khớp khách hàng thân thiết:

  • Thiết lập tài khoản: Đảm bảo rằng bạn có một tài khoản Merchant Center đang hoạt động (hoặc quyền truy cập được uỷ quyền vào tài khoản của người bán nếu bạn là nhà cung cấp chương trình khách hàng thân thiết bên thứ ba). Bạn không cần tạo tài khoản Google Ads để sử dụng Dịch vụ so khớp khách hàng thân thiết.
  • Cấu hình chương trình khách hàng thân thiết: Bật chương trình khách hàng thân thiết trong tài khoản Merchant Center và đảm bảo bạn đã xác định các cấp khách hàng thân thiết.
  • Lưu ý về thứ tự cấp: Lưu ý thứ tự mà bạn xác định các cấp khách hàng thân thiết trong giao diện người dùng của Merchant Center. API sử dụng chính xác trình tự này cho việc liên kết enum.

Phương thức: ManageLoyaltyCustomerMatch

Phương thức ManageLoyaltyCustomerMatch đóng vai trò là giao diện trung tâm để quản lý mối liên kết với khách hàng thân thiết. Dựa trên thông tin đầu vào được cung cấp, dịch vụ sẽ tự động xác định xem có nên chèn, cập nhật hay xoá trạng thái cấp khách hàng thân thiết của khách hàng hay không. Thao tác này có tính chất luỹ đẳng: các yêu cầu giống hệt nhau lặp lại sẽ có cùng hiệu quả như một yêu cầu duy nhất.

Yêu cầu sau đây minh hoạ cách quản lý mối liên kết khách hàng thân thiết thông qua API:

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

Yêu cầu này xác định các tham số đường dẫn bắt buộc sau:

  • API_VERSION: Phiên bản API, chẳng hạn như v1.
  • ACCOUNT_ID: Mã tài khoản Merchant Center.

Thêm đối tượng loyaltyCustomer vào nội dung yêu cầu.

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

Trường loyaltyCustomer

  • userIdentifier: Tập hợp giá trị nhận dạng dùng để so khớp khách hàng. Bạn phải cung cấp ít nhất một trường hợp lệ trong userIdentifier.
  • loyaltyTier: Cấp khách hàng thân thiết để liên kết với khách hàng. Liên kết với thứ tự của cấp trong chế độ thiết lập Merchant Center. Để biết thông tin chi tiết, hãy xem bài viết Tìm hiểu về việc liên kết loyaltyTier. Sử dụng NON_MEMBER để xoá mối liên kết hiện có.
  • pointBalance: Số dư điểm hiện tại của khách hàng.

Trường userIdentifier

Cung cấp ít nhất một trong các trường sau:

  • emailAddress: Địa chỉ email của khách hàng.
  • address: Địa chỉ thực tế của khách hàng. Bạn phải nhập mã bưu chính.
  • phoneNumber: Số điện thoại của khách hàng. Bạn nên dùng định dạng E.164.

Tìm hiểu về mối liên kết loyaltyTier

API không sử dụng tên tuỳ chỉnh. Giá trị enum loyaltyTier (TIER1 đến TIER7) là nhãn ngữ nghĩa. Các chương trình này không sử dụng tên tuỳ chỉnh (ví dụ: "Phần thưởng vàng") hoặc nhãn tuỳ chỉnh (ví dụ: "gold_tier") mà bạn đã chỉ định trong giao diện người dùng của Merchant Center. Thay vào đó, các giá trị này liên kết chặt chẽ với thứ tự mà bạn xác định các cấp trong chế độ cài đặt chương trình khách hàng thân thiết trong Merchant Center:

  • TIER1: Tương ứng với cấp đầu tiên được liệt kê trong cấu hình chương trình khách hàng thân thiết của bạn trong Merchant Center.
  • TIER2: Tương ứng với cấp thứ hai trong cấu hình chương trình khách hàng thân thiết của bạn trong Merchant Center.
  • TIER3 đến TIER7: Tương ứng với cấp thứ ba đến cấp thứ bảy trong cấu hình chương trình khách hàng thân thiết của bạn trên Merchant Center.

Ví dụ:

Nếu chương trình khách hàng thân thiết của bạn trong Merchant Center có các cấp được xác định theo thứ tự sau:

  1. Tên cấp: "Hạng Bạc", Nhãn phân cấp: "bạc"
  2. Tên cấp: "Thành viên vàng", Nhãn phân cấp: "vàng"
  3. Tên cấp: "Platinum Elite", Nhãn phân cấp: "platinum"

Sau đó, trong các lệnh gọi API accounts.loyaltyCustomers.manage:

  • Để chỉ định một khách hàng có "Trạng thái bạc", bạn phải sử dụng loyaltyTier: TIER1.
  • Để chỉ định một khách hàng là "Thành viên vàng", bạn phải sử dụng loyaltyTier: TIER2.
  • Để chỉ định một khách hàng vào cấp "Platinum Elite", bạn phải sử dụng loyaltyTier: TIER3.

Giá trị enum LoyaltyTier

  • TIER1
  • TIER2
  • TIER3
  • TIER4
  • TIER5
  • TIER6
  • TIER7
  • NON_MEMBER (Dùng để báo hiệu việc xoá mối liên kết với chương trình khách hàng thân thiết của khách hàng)

Tìm hiểu nội dung phản hồi của ManageLoyaltyCustomerMatch

Phương thức ManageLoyaltyCustomerMatch trả về một đối tượng ManageLoyaltyCustomerMatchResponse:

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

Những điểm quan trọng cần lưu ý đối với câu trả lời

  • Thêm hoặc cập nhật thành công (dữ liệu được lưu trữ): Để lưu trữ hoặc cập nhật thành công mối liên kết cấp độ khách hàng thân thiết của khách hàng, hãy đáp ứng các điều kiện sau:

    • bạn so khớp một người dùng Google với userIdentifier được cung cấp
    • bạn đặt loyaltyTier trong yêu cầu thành một giá trị hợp lệ khác NON_MEMBER
    • người dùng trùng khớp đã đồng ý cho phép sử dụng dữ liệu về khách hàng thân thiết

Nội dung phản hồi chứa đối tượng loyaltyCustomer trong yêu cầu của bạn, cho biết rằng dịch vụ đã xử lý và lưu trữ dữ liệu thành công:

{
  "loyaltyCustomer": {
    "userIdentifier": {
     "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
    }
}
  • Xoá thành công: Để xoá thành công mọi mối liên kết hiện có giữa khách hàng và người bán này về chương trình khách hàng thân thiết, bạn phải đáp ứng các điều kiện sau:
    • bạn so khớp một người dùng Google với userIdentifier được cung cấp
    • bạn đặt loyaltyTier trong yêu cầu thành NON_MEMBER

Phản hồi là một đối tượng JSON trống:

{}
  • Không khớp/không đồng ý (thành công thầm lặng): Nếu userIdentifier được cung cấp không khớp với Tài khoản Google hoặc nếu người dùng khớp chưa đồng ý sử dụng dữ liệu khách hàng thân thiết, thì API sẽ trả về trạng thái HTTP 200 OK kèm theo một đối tượng JSON trống: {}. Điều này xảy ra cho cả nỗ lực chèn và xoá.

Ví dụ

TIER1 tương ứng với cấp đầu tiên được xác định (ví dụ: "Basic") và TIER2 tương ứng với cấp thứ hai (ví dụ: "Premium").

Để thêm khách hàng vào TIER2 hoặc cập nhật trạng thái của họ bằng địa chỉ email, hãy gửi yêu cầu sau:

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

Khi người dùng được so khớp thành công và đã đồng ý, API sẽ trả về phản hồi sau:

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

Khi không có kết quả trùng khớp hoặc người dùng chưa đồng ý, API sẽ trả về phản hồi sau:

{}

Để xoá mối liên kết với chương trình khách hàng thân thiết của khách hàng bằng số điện thoại, hãy gửi yêu cầu sau:

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

Bất kể bản ghi có tồn tại hay không, API đều trả về phản hồi thành công sau:

{}

Để thêm hoặc cập nhật khách hàng bằng nhiều giá trị nhận dạng, hãy gửi yêu cầu sau:

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

Phản hồi tương tự như ví dụ đầu tiên, tuỳ thuộc vào kết quả so khớp và sự đồng ý.

Xử lý lỗi

API này sử dụng mã HTTP tiêu chuẩn. Sau đây là các chuỗi lỗi thường gặp:

Mã HTTP Error String Nội dung mô tả
400 INVALID_ARGUMENT Thiếu user_identifier hoặc loyalty_tier, hoặc giá trị nhận dạng trống.
401 UNAUTHENTICATED Thông tin đăng nhập không hợp lệ hoặc bị thiếu.
403 PERMISSION_DENIED Người dùng đã xác thực không có quyền truy cập vào tài khoản Merchant Center được chỉ định.
404 NOT_FOUND Nhãn phân cấp khách hàng thân thiết được chỉ định không tồn tại trong cấu hình của bạn.
412 FAILED_PRECONDITION Bạn chưa thiết lập chương trình khách hàng thân thiết trong tài khoản của mình.
429 RESOURCE_EXHAUSTED Đã đạt đến hạn mức.

Các ví dụ về lỗi

Ví dụ về 404 NOT_FOUND:

Mọi yêu cầu hợp lệ đối với một mã tài khoản không có chương trình khách hàng thân thiết được định cấu hình.

API trả về phản hồi lỗi sau:

{
  "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"
        }
      }
    ]
  }
}

Lý do: Tài khoản nhà bán hàng trong đường dẫn không có chương trình khách hàng thân thiết nào đang hoạt động.

Ví dụ về 400 INVALID_ARGUMENT:

Lỗi xảy ra nếu yêu cầu chứa giá trị không hợp lệ cho trường loyaltyTier:

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

API trả về phản hồi lỗi sau:

{
  "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\""
          }
        ]
      }
    ]
  }
}

Lý do: TIER11 không phải là giá trị enum hợp lệ cho loyaltyTier. Lỗi tương tự có thể xảy ra khi bạn cố gắng chỉ định TIER2 khi chỉ có một cấp.

Lỗi sẽ xảy ra nếu thiếu trường loyaltyTier bắt buộc trong nội dung yêu cầu:

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

API trả về phản hồi lỗi sau:

{
  "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"
        }
      }
    ]
  }
}

Lý do: Trường loyaltyTier là trường bắt buộc.

Lỗi sẽ xảy ra nếu giá trị nhận dạng địa chỉ không đầy đủ, chẳng hạn như khi thiếu trường postalCode:

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

API trả về phản hồi lỗi sau:

{
  "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"
        }
      }
    ]
  }
}

Lý do: Bạn đã cung cấp địa chỉ nhưng thiếu trường postalCode bắt buộc, nên địa chỉ này không được coi là giá trị nhận dạng hợp lệ.

Lỗi sẽ xảy ra nếu bạn yêu cầu một chỉ mục cấp nằm ngoài giới hạn của chương trình đã định cấu hình:

Trường hợp: Người bán chỉ định cấu hình một cấp trong Merchant Center.

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

API trả về phản hồi lỗi sau:

{
  "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"
        }
      }
    ]
  }
}

Lý do: Bạn yêu cầu TIER2, nhưng chương trình khách hàng thân thiết được liên kết với tài khoản không có cấp thứ hai được xác định.

Lỗi sẽ xảy ra nếu yêu cầu chứa emailAddress không đúng định dạng:

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

API trả về phản hồi lỗi sau:

{
  "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"
        }
      }
    ]
  }
}

Lý do: Định dạng địa chỉ email không hợp lệ.

Lỗi sẽ xảy ra nếu đối tượng userIdentifier trống:

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

API trả về phản hồi lỗi sau:

{
  "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"
        }
      }
    ]
  }
}

Lý do: Đối tượng userIdentifier có tồn tại nhưng không chứa trường giá trị nhận dạng thực tế nào.

Lưu ý: Xác thực giá trị nhận dạng.:

  • API này thực hiện các bước kiểm tra định dạng cơ bản đối với giá trị nhận dạng (ví dụ: cấu trúc email, sự hiện diện của postalCode trong địa chỉ).
  • Tuy nhiên, một số giá trị nhận dạng vượt qua quy trình kiểm tra ban đầu có thể không khớp với bất kỳ tài khoản người dùng nào trên Google hoặc có thể không ở định dạng mà hệ thống so khớp phụ trợ nhận dạng được. Trong những trường hợp như vậy, bạn sẽ nhận được phản hồi trống thành công thầm lặng {} với trạng thái HTTP 200 OK.

Các phương pháp hay nhất

Hãy làm theo các phương pháp hay nhất sau đây để tối ưu hoá quy trình tích hợp.

  • Đối với việc tích hợp quy mô lớn: Vì API hoạt động theo từng yêu cầu, nên cần có tính năng song song phía máy khách để đạt được thông lượng cần thiết cho các tập dữ liệu lớn. Bạn nên thiết kế quy trình tích hợp để quản lý nhiều yêu cầu đồng thời. Để được hướng dẫn về cách cấu trúc quá trình triển khai nhằm xử lý khối lượng lớn hơn thông qua tính năng song song hoá, hãy tham khảo hướng dẫn của chúng tôi về cách gửi nhiều yêu cầu.

  • Quản lý hạn mức: Hạn mức mặc định là 1.000.000 yêu cầu/ngày và 10.000 yêu cầu/phút. Để tìm hiểu cách theo dõi và kiểm tra hạn mức, hãy xem bài viết Hạn mức và giới hạn.

  • Ưu tiên địa chỉ email: Bất cứ khi nào có thể, hãy thêm emailAddress của khách hàng vào userIdentifier. Địa chỉ email thường là giá trị nhận dạng chính xác và đáng tin cậy nhất để so khớp người dùng với Tài khoản Google của họ.

  • Xử lý phản hồi trống: Thiết kế ứng dụng để diễn giải chính xác phản hồi trống {} là thành công, hiểu rằng điều đó có nghĩa là dữ liệu không được lưu trữ vì lý do quyền riêng tư (không khớp hoặc không có sự đồng ý). Đừng thử gửi lại yêu cầu.

  • Xác minh thứ tự cấp: Luôn xác nhận thứ tự của các cấp khách hàng thân thiết trong giao diện người dùng Merchant Center để đảm bảo bạn đang sử dụng đúng giá trị enum từ TIER1 đến TIER7 trong lệnh gọi API. Việc liên kết này dựa trên thứ tự đã xác định trong giao diện người dùng, chứ không phải tên của các thành phần.

  • Theo dõi lỗi: Ghi nhật ký và theo dõi các phản hồi của API, chú ý đến mọi lỗi 4xx để phát hiện các vấn đề về việc tích hợp, đặc biệt là lỗi 404 có thể cho thấy sự không khớp trong việc hiểu cấp độ.