Ringkasan Layanan Customer Match Loyalitas

Panduan ini menjelaskan cara menggunakan Layanan Customer Match Loyalitas di Merchant API. Layanan ini memungkinkan penjual dan penyedia program loyalitas pihak ketiga yang bertindak atas nama penjual untuk 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 Program Loyalitas untuk mengupload data loyalitas, yang kemudian digunakan untuk menyediakan fitur personalisasi loyalitas organik di Google Penelusuran, seperti menampilkan harga khusus anggota. Anda menggunakan metode kustom ManageLoyaltyCustomerMatch 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 penyelidikan akun yang tidak sah, API tidak mendukung operasi GET atau LIST, sehingga memastikan bahwa data dikelola tanpa pengambilan atau audit.
• Identifikasi yang fleksibel: Cocokkan pengguna menggunakan minimal 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 penyelidikan 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 (atau akses yang diizinkan ke akun penjual jika Anda adalah penyedia program loyalitas pihak ketiga). 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 tingkatan loyalitas.
• Urutan tingkat: Perhatikan urutan tingkat loyalitas Anda ditetapkan di UI Merchant Center. API menggunakan urutan persis ini untuk pemetaan enum-nya.

Metode: ManageLoyaltyCustomerMatch

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

Permintaan berikut menunjukkan cara mengelola asosiasi 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 dikaitkan dengan pelanggan. Dipetakan ke urutan tingkat di penyiapan Merchant Center. Untuk mengetahui detailnya, lihat Memahami pemetaan loyaltyTier. Gunakan NON_MEMBER untuk menghapus pengaitan yang ada.
• pointBalance: Saldo poin pelanggan saat ini.

Kolom userIdentifier

Berikan setidaknya salah satu kolom berikut:

• 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. Mereka tidak menggunakan nama kustom (misalnya, "Penghargaan Emas") atau label kustom (misalnya, "tingkat_emas") yang Anda tetapkan di UI Merchant Center. Sebagai gantinya, tingkat ini dipetakan secara ketat ke urutan saat Anda menentukan tingkat 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 Tingkatan: "Silver Status", Label Tingkatan: "silver"
2. Nama Tingkat: "Gold Member", Label Tingkat: "gold"
3. Nama Tingkat: "Platinum Elite", Label Tingkat: "platinum"

Kemudian, di panggilan API accounts.loyaltyCustomers.manage:

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

Penting: Untuk menggunakan nilai enum API yang benar, periksa urutan tingkat dalam setelan program loyalitas Merchant Center Anda.

Nilai enum LoyaltyTier

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

Memahami isi respons ManageLoyaltyCustomerMatch

Metode ManageLoyaltyCustomerMatch menampilkan objek ManageLoyaltyCustomerMatchResponse:

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

Pertimbangan penting untuk respons

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

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

Respons berisi objek loyaltyCustomer dari permintaan Anda, yang menunjukkan bahwa layanan berhasil memproses dan menyimpan data:

{
  "loyaltyCustomer": {
    "userIdentifier": {
     "emailAddress": "[e-mail]"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
    }
}

• Penghapusan berhasil: Agar berhasil menghapus semua asosiasi 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 (berhasil tanpa pemberitahuan): Jika userIdentifier yang diberikan tidak cocok dengan Akun Google, atau jika pengguna yang cocok belum memberikan izin untuk penggunaan data program loyalitas, API akan menampilkan status HTTP 200 OK dengan objek JSON kosong: {}. Hal ini terjadi untuk upaya upsert dan penghapusan.

Penting: Ini bukan error. Tindakan ini merupakan langkah privasi yang disengaja untuk mencegah penyimpulan keberadaan akun pengguna atau status izin. Dalam hal ini, sistem tidak menulis atau menghapus data apa pun.

Contoh

TIER1 sesuai dengan tingkat yang ditentukan pertama (misalnya, 'Basic'), dan TIER2 sesuai dengan tingkat kedua (misalnya, '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": "[e-mail]"
      },
      "loyaltyTier": "TIER2",
      "pointBalance": 1500
  }'

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

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "[e-mail]"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
  }
}

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

{}

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

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

Terlepas dari apakah ada data, API akan menampilkan respons berhasil 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": "[e-mail]",
        "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 meliputi:

Kode HTTP	Error String	Deskripsi
400	INVALID_ARGUMENT	user_identifier atau loyalty_tier tidak ada, atau ID kosong.
401	TIDAK DIAUTENTIKASI	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.

Catatan: Jika pengguna tidak dapat dicocokkan (misalnya, karena tidak ada izin atau pengguna tidak ditemukan), API akan menampilkan status 200 OK dengan resource loyaltyCustomer default. Tindakan ini adalah langkah privasi untuk mencegah penyelidikan keberadaan akun.

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 aktif.

Contoh 400 INVALID_ARGUMENT:

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

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "[e-mail]"
    },
    "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 padahal hanya ada satu tingkat yang tersedia.

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

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "[e-mail]"
    },
    "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 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 tidak memiliki kolom postalCode yang wajib diisi, 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 mengonfigurasi satu tingkat di Merchant Center.

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "[e-mail]"
    },
    "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 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: Validasi ID.:

• API melakukan pemeriksaan format dasar pada ID (misalnya, struktur email, keberadaan postalCode dalam 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 tanpa pemberitahuan {} dengan status HTTP 200 OK.

Praktik terbaik

Ikuti praktik terbaik berikut 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, lihat Kuota dan batas.

• Prioritaskan alamat email: Jika memungkinkan, sertakan emailAddress pelanggan dalam 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 hal itu berarti data tidak disimpan karena alasan privasi (tidak ada kecocokan atau tidak ada izin). Jangan coba lagi permintaan.

• 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. Pemetaan ini didasarkan pada urutan yang ditentukan di UI, bukan namanya.

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