Ringkasan Layanan Customer Match Loyalitas

Panduan ini menjelaskan cara menggunakan Layanan Customer Match Loyalitas di Merchant API. Layanan ini memungkinkan penjual mengelola data loyalitas pelanggan, seperti ID pengguna dan informasi tingkat, untuk personalisasi organik di Google Penelusuran, tanpa memerlukan akun Google Ads yang aktif.

Ringkasan

Gunakan Layanan Customer Match Loyalitas untuk mengupload data loyalitas, yang kemudian digunakan untuk menyediakan fitur personalisasi loyalitas organik di Google Penelusuran, seperti menampilkan harga khusus anggota. Anda menggunakan ManageLoyaltyCustomerMatch metode kustom untuk mengaitkan pelanggan dengan tingkat program loyalitas, sehingga Anda dapat menyisipkan, memperbarui, atau menghapus status loyalitas mereka berdasarkan ID pengguna.

Konsep utama

  • Antarmuka terpadu: Endpoint unik untuk menambahkan, memperbarui, atau menghapus detail tingkat loyalitas pelanggan
  • Desain yang mengutamakan privasi: Untuk melindungi privasi pengguna dan mencegah probing akun yang tidak sah, API tidak mendukung operasi GET atau LIST , sehingga data dikelola tanpa pengambilan atau audit.
  • Identifikasi fleksibel: Cocokkan pengguna menggunakan setidaknya satu ID yang valid, seperti alamat email, alamat fisik, atau nomor telepon.
  • Pemrosesan berbasis izin: Layanan menyimpan dan menggunakan data pelanggan hanya jika pengguna akhir telah memberikan izin yang diperlukan kepada Google. Untuk melindungi dan mencegah probing keberadaan akun atau status izin, layanan akan menampilkan keberhasilan senyap jika tidak ada kecocokan atau izin tidak diberikan.

Prasyarat

Ikuti persyaratan berikut untuk menggunakan Layanan Customer Match Loyalitas:

  • Penyiapan akun: Pastikan Anda memiliki akun Merchant Center yang aktif. Anda tidak perlu membuat akun Google Ads untuk menggunakan Layanan Customer Match Loyalitas.
  • Konfigurasi program loyalitas: Aktifkan program loyalitas di akun Merchant Center Anda, dan pastikan Anda telah menentukan tingkat loyalitas.
  • Pengetahuan tentang urutan tingkat: Ketahui urutan tingkat loyalitas Anda yang ditentukan di UI Merchant Center. API menggunakan urutan yang sama persis untuk pemetaan enum-nya.

Metode: ManageLoyaltyCustomerMatch

Metode ManageLoyaltyCustomerMatch berfungsi sebagai antarmuka pusat untuk mengelola pengaitan loyalitas pelanggan. Berdasarkan input yang diberikan, layanan akan otomatis menentukan apakah akan menyisipkan, memperbarui, atau menghapus status tingkat loyalitas pelanggan. Operasi ini bersifat idempoten: permintaan identik yang berulang akan memiliki efek yang sama seperti permintaan tunggal.

Permintaan berikut menunjukkan cara mengelola pengaitan loyalitas pelanggan melalui API:

POST https://merchantapi.googleapis.com/{api_version}/accounts/{account_id}/loyaltyCustomers:manage

Permintaan ini menentukan parameter jalur wajib berikut:

  • api_version: Versi API seperti v1.
  • account_id: ID akun Merchant Center.

Sertakan objek loyaltyCustomer dalam isi permintaan.

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

Kolom loyaltyCustomer

  • userIdentifier: Kumpulan ID yang digunakan untuk mencocokkan pelanggan. Setidaknya satu kolom dalam userIdentifier harus diberikan dan valid.
  • loyaltyTier: Tingkat loyalitas yang akan dikaitkan dengan pelanggan. Dipetakan ke urutan tingkat dalam penyiapan Merchant Center. Untuk mengetahui detailnya, lihat Memahami pemetaanloyaltyTier. Gunakan NON_MEMBER untuk menghapus pengaitan yang ada.
  • pointBalance: Saldo poin pelanggan saat ini.

Kolom userIdentifier

Setidaknya salah satu kolom berikut harus diberikan:

  • emailAddress: Alamat email pelanggan.
  • address: Alamat fisik pelanggan. PostalCode wajib diisi.
  • phoneNumber: Nomor telepon pelanggan. Format E.164 direkomendasikan.

Memahami pemetaan loyaltyTier

API tidak menggunakan nama kustom. Nilai enum loyaltyTier (TIER1 hingga TIER7) adalah label semantik. Nilai tersebut tidak menggunakan nama kustom (misalnya, "Gold Rewards") atau label kustom (misalnya, "gold_tier") yang Anda tetapkan di UI Merchant Center. Sebagai gantinya, nilai tersebut dipetakan secara ketat ke urutan tingkat yang Anda tentukan di setelan program loyalitas di Merchant Center:

  • TIER1: Sesuai dengan tingkat pertama yang tercantum dalam konfigurasi program loyalitas Merchant Center Anda.
  • TIER2: Sesuai dengan tingkat kedua yang tercantum dalam konfigurasi program loyalitas Merchant Center Anda.
  • TIER3 hingga TIER7: Sesuai dengan tingkat ketiga hingga ketujuh yang tercantum dalam konfigurasi program loyalitas Merchant Center Anda.

Contoh:

Jika program loyalitas Merchant Center Anda memiliki tingkat yang ditentukan dalam urutan ini:

  1. Nama Tingkat: "Silver Status", Label Tingkat: "silver"
  2. Nama Tingkat: "Gold Member", Label Tingkat: "gold"
  3. Nama Tingkat: "Platinum Elite", Label Tingkat: "platinum"

Kemudian, dalam accounts.loyaltyCustomers.manage panggilan API:

  • Untuk menetapkan pelanggan ke "Silver Status", Anda harus menggunakan loyaltyTier: TIER1.
  • Untuk menetapkan pelanggan ke "Gold Member", Anda harus menggunakan loyaltyTier: TIER2.
  • Untuk menetapkan pelanggan ke "Platinum Elite", Anda harus menggunakan loyaltyTier: TIER3.

Nilai enum LoyaltyTier

  • TIER1
  • TIER2
  • TIER3
  • TIER4
  • TIER5
  • TIER6
  • TIER7
  • NON_MEMBER (Digunakan untuk menandakan penghapusan pengaitan loyalitas pelanggan)

Memahami isi respons ManageLoyaltyCustomerMatch

Metode ManageLoyaltyCustomerMatch menampilkan ManageLoyaltyCustomerMatchResponse objek:

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

Pertimbangan penting tentang kemungkinan respons:

  • Upsert berhasil (data disimpan): Untuk berhasil menyimpan atau memperbarui pengaitan tingkat loyalitas pelanggan, penuhi kondisi berikut:

    • Anda mencocokkan pengguna Google dengan userIdentifier yang diberikan
    • Anda menetapkan loyaltyTier dalam permintaan ke nilai yang valid selain NON_MEMBER
    • pengguna yang cocok telah memberikan izin untuk penggunaan data loyalitas

Respons berisi objek loyaltyCustomer dari permintaan Anda, yang menunjukkan bahwa data berhasil diproses dan disimpan:

{
  "loyaltyCustomer": {
    "userIdentifier": {
     "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
    }
}
  • Penghapusan berhasil: Untuk berhasil menghapus pengaitan loyalitas yang ada untuk pelanggan dengan penjual ini, kondisi berikut harus dipenuhi:
    • Anda mencocokkan pengguna Google dengan userIdentifier yang diberikan
    • Anda menetapkan loyaltyTier dalam permintaan ke NON_MEMBER

Responsnya adalah objek JSON kosong:

{}
  • Tidak ada kecocokan / tidak ada izin (keberhasilan senyap): Jika userIdentifier yang diberikan tidak cocok dengan Akun Google, atau jika pengguna yang cocok belum memberikan izin untuk penggunaan data loyalitas, API akan menampilkan status HTTP 200 OK dengan objek JSON kosong: {}. Hal ini terjadi untuk upaya upsert dan penghapusan upaya.

Contoh

TIER1 sesuai dengan tingkat pertama yang ditentukan oleh penjual, yang disebut "Basic", dan TIER2 sesuai dengan tingkat kedua - "Premium"

Untuk menambahkan pelanggan ke TIER2 atau memperbarui statusnya menggunakan alamat email, kirim permintaan berikut:

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

Jika pengguna berhasil dicocokkan dan telah memberikan izin, API akan menampilkan respons berikut:

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

Jika tidak ada kecocokan atau pengguna belum memberikan izin, API akan menampilkan respons berikut:

{}

Untuk menghapus pengaitan loyalitas pelanggan menggunakan nomor telepon, kirim permintaan berikut:

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

Terlepas dari apakah data ada atau tidak, API akan menampilkan respons keberhasilan berikut:

{}

Untuk menambahkan atau memperbarui pelanggan menggunakan beberapa ID, kirim permintaan berikut:

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

Responsnya mirip dengan contoh pertama, bergantung pada kecocokan dan izin.

Penanganan error

API menggunakan kode HTTP standar. String error umum mencakup:

Kode HTTP String Error Deskripsi
400 INVALID_ARGUMENT user_identifier atau loyalty_tier tidak ada, atau ID kosong.
401 UNAUTHENTICATED Kredensial tidak valid atau tidak ada.
403 PERMISSION_DENIED Pengguna yang diautentikasi tidak memiliki akses ke akun Merchant Center yang ditentukan.
404 NOT_FOUND Label tingkat loyalitas yang ditentukan tidak ada dalam konfigurasi Anda.
412 FAILED_PRECONDITION Anda belum mengonfigurasi program loyalitas di akun Anda.
429 RESOURCE_EXHAUSTED Batas kuota tercapai.

Contoh error

Contoh untuk 404 NOT_FOUND:

Permintaan valid apa pun ke ID akun yang tidak memiliki program loyalitas yang dikonfigurasi.

API menampilkan respons error berikut:

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

Alasan: Akun penjual di jalur tidak memiliki program loyalitas yang aktif.

Contoh 400 INVALID_ARGUMENT:

Error akan terjadi jika permintaan berisi nilai yang tidak valid untuk kolom loyaltyTier:

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

API menampilkan respons error berikut:

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

Alasan: TIER11 bukan nilai enum yang valid untuk loyaltyTier. Error yang sama dapat terjadi saat Anda mencoba menentukan TIER2 jika hanya ada satu tingkat yang tersedia.

Error akan terjadi jika kolom loyaltyTier yang wajib diisi tidak ada dalam isi permintaan:

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

API menampilkan respons error berikut:

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

Alasan: Kolom loyaltyTier wajib diisi.

Error akan terjadi jika ID alamat tidak lengkap, seperti saat kolom postalCode tidak ada:

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

API menampilkan respons error berikut:

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

Alasan: Alamat diberikan, tetapi kolom postalCode yang wajib diisi tidak ada, sehingga tidak dianggap sebagai ID yang valid.

Error akan terjadi jika Anda meminta indeks tingkat yang berada di luar batas untuk program yang dikonfigurasi:

Skenario: Penjual hanya memiliki satu tingkat yang dikonfigurasi di Merchant Center.

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

API menampilkan respons error berikut:

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

Alasan: TIER2 diminta, tetapi program loyalitas yang ditautkan ke akun tidak memiliki tingkat kedua yang ditentukan.

Error akan terjadi jika permintaan berisi emailAddress yang salah format:

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

API menampilkan respons error berikut:

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

Alasan: Format alamat email tidak valid.

Error akan terjadi jika objek userIdentifier kosong:

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

API menampilkan respons error berikut:

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

Alasan: Objek userIdentifier ada, tetapi tidak berisi kolom ID yang sebenarnya.

Catatan tentang validasi ID:

  • API melakukan pemeriksaan format dasar pada ID (misalnya, struktur email, keberadaan postalCode di alamat).
  • Namun, beberapa ID yang lulus pemeriksaan awal mungkin tidak cocok dengan akun pengguna Google mana pun atau mungkin tidak dalam format yang dikenali oleh sistem pencocokan backend. Dalam kasus tersebut, Anda akan menerima respons kosong keberhasilan senyap {} dengan status HTTP 200 OK.

Praktik terbaik

Ikuti praktik terbaik ini untuk mengoptimalkan integrasi Anda.

  • Untuk integrasi skala besar: Karena API beroperasi berdasarkan per permintaan, paralelisme sisi klien diperlukan untuk mencapai throughput yang diperlukan untuk set data besar. Anda harus mendesain integrasi untuk mengelola beberapa permintaan serentak. Untuk mendapatkan panduan tentang cara menyusun implementasi Anda untuk menangani volume yang lebih tinggi melalui paralelisme, lihat panduan kami tentang cara mengirim beberapa permintaan.

  • Pengelolaan kuota: Kuota default adalah 1.000.000 permintaan/hari dan 10.000 permintaan/menit. Untuk melihat cara memantau dan memeriksa kuota Anda, lihat Kuota dan batas.

  • Prioritaskan alamat email: Jika memungkinkan, sertakan emailAddress pelanggan di userIdentifier. Alamat email umumnya merupakan ID yang paling akurat dan andal untuk mencocokkan pengguna dengan Akun Google mereka.

  • Tangani respons kosong: Desain aplikasi Anda untuk menafsirkan respons {} kosong dengan benar sebagai keberhasilan, dengan memahami bahwa respons tersebut berarti data tidak disimpan karena alasan privasi (tidak ada kecocokan atau tidak ada izin). Jangan coba lagi permintaan tersebut.

  • Verifikasi urutan tingkat: Selalu konfirmasi urutan tingkat loyalitas Anda di UI Merchant Center untuk memastikan Anda menggunakan nilai enum TIER1 hingga TIER7 yang benar dalam panggilan API Anda. Pemetaan ini didasarkan pada urutan yang ditentukan di UI, bukan namanya.

  • Pantau error: Catat dan pantau respons API, dengan memperhatikan error 4xx untuk menangkap masalah integrasi, terutama error 404 yang mungkin menunjukkan ketidakcocokan dalam pemahaman tingkat.