Ringkasan Layanan Customer Match Loyalitas

Panduan ini menjelaskan cara menggunakan Layanan Customer Match Loyalitas di Merchant API. Layanan ini memungkinkan penjual dan penyedia 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 pemeriksaan akun yang tidak sah, API tidak mendukung operasi GET atau LIST, sehingga memastikan bahwa 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 ini menyimpan dan menggunakan data pelanggan hanya jika pengguna akhir telah memberikan izin yang diperlukan kepada Google. Untuk melindungi dan mencegah pemeriksaan keberadaan akun atau status izin, layanan akan menampilkan keberhasilan otomatis jika kecocokan tidak dibuat atau izin tidak diberikan.

Prasyarat

Ikuti persyaratan berikut untuk menggunakan Layanan Customer Match Program Loyalitas:

• Penyiapan akun: Pastikan Anda memiliki akun Merchant Center yang aktif (atau akses yang diizinkan ke akun penjual jika Anda adalah penyedia 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, dan pastikan Anda telah menentukan tingkat loyalitas.
• Perhatikan urutan tingkatan: Perhatikan urutan tingkatan loyalitas Anda yang ditentukan di UI Merchant Center. API menggunakan urutan yang sama persis ini 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 memiliki efek yang sama dengan satu permintaan.

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 yang diperlukan 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 pemetaan loyaltyTier. Gunakan NON_MEMBER untuk menghapus atribusi 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. Atribut ini tidak menggunakan nama kustom (misalnya, "Gold Rewards") atau label kustom (misalnya, "gold_tier") yang Anda tetapkan di UI Merchant Center. Namun, 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, di panggilan API accounts.loyaltyCustomers.manage:

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

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

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 objek ManageLoyaltyCustomerMatchResponse:

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

Pertimbangan penting untuk respons

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

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

Contoh

TIER1 sesuai dengan tingkat pertama yang ditentukan (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 pengaitan 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 data ada atau tidak, 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 ini menggunakan kode HTTP standar. String error umum meliputi:

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.

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. Ini adalah tindakan privasi untuk mencegah pemeriksaan keberadaan akun.

Contoh error

Contoh untuk 404 NOT_FOUND:

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

API akan 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 akan terjadi jika permintaan berisi nilai yang tidak valid untuk kolom loyaltyTier:

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "[e-mail]"
    },
    "loyaltyTier": "TIER11",
    "pointBalance": 100
  }
}

API akan 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 diperlukan tidak ada dalam isi permintaan:

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "[e-mail]"
    },
    "pointBalance": 100
  }
}

API akan 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, misalnya saat kolom postalCode tidak ada:

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

API akan 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 memiliki satu tingkat yang dikonfigurasi di Merchant Center.

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

API akan 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 akan 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 akan 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 yang berhasil tanpa pesan {} dengan status HTTP 200 OK.

Praktik terbaik

Ikuti praktik terbaik berikut untuk mengoptimalkan integrasi Anda.

• Untuk integrasi skala besar: Karena API beroperasi berdasarkan 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 guna menangani volume yang lebih tinggi melalui paralelisasi, lihat panduan kami tentang cara mengirim beberapa permintaan.

• Pengelolaan kuota: Kuota default adalah 1.000.000 permintaan/hari dan 10.000 permintaan/menit. Untuk mengetahui cara memantau dan memeriksa kuota, 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.

• Menangani respons kosong: Desain aplikasi Anda untuk menafsirkan respons {} kosong dengan benar sebagai keberhasilan, dengan memahami bahwa hal ini berarti data tidak disimpan karena alasan privasi (tidak ada kecocokan atau tidak ada izin). Jangan mencoba 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. Pemetaan ini didasarkan pada urutan yang ditentukan di UI, bukan namanya.

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