Kartu Voucher (alias Voucher)

Catatan: Ini adalah versi uji coba.

Peringatan: Dokumen ini adalah dokumen yang Masih Dalam Proses. Informasi dapat sering berubah.

Panduan ini menguraikan persyaratan, rekomendasi pemodelan data, dan praktik terbaik untuk menerapkan kartu voucher (juga dikenal sebagai voucher) di feed penawaran Anda. Rekomendasi ini melengkapi dokumentasi Pusat Tindakan standar dan membahas aspek integrasi khusus kartu voucher.

Mode dan Kategorisasi Penawaran

Saat mengirimkan inventaris kartu voucher, pastikan atribut inti berikut dikonfigurasi dengan benar:

• Mode Penawaran: offer_modes harus selalu ditetapkan sebagai array singleton yang berisi "OFFER_MODE_GIFT_CARD_PURCHASE":

  "offer_modes": ["OFFER_MODE_GIFT_CARD_PURCHASE"]
  

• Voucher Nilai Tersimpan vs. Diskon Langsung di Toko:

  • gift_card_info secara ketat dicadangkan untuk voucher dan kartu voucher nilai tersimpan yang dibeli di muka (OFFER_MODE_GIFT_CARD_PURCHASE).
  • Jika pelanggan membayar langsung di konter toko fisik di tempat untuk mendapatkan diskon langsung tanpa membeli kode voucher untuk diklaim atau ditukarkan nanti, modelkan penawaran sebagai diskon langsung di toko standar (OFFER_MODE_WALK_IN) dan hapus pesan gift_card_info sepenuhnya.

• Pemodelan Nominal: Nominal kartu voucher harus mewakili nilai voucher (nilai yang dapat ditukarkan), bukan nilai yang dibayar pengguna (pengguna membayar harga diskon).

• Menggabungkan Beberapa Nominal: Beberapa voucher yang memiliki persentase dan persyaratan diskon yang sama persis, tetapi berbeda dalam nilai nominal, harus dikelompokkan ke dalam satu entri penawaran. Karena denomination_type beroperasi sebagai oneof, partner harus memilih antara menetapkan fixed_denominations atau custom_range:

  • Nominal Tetap: Gunakan saat jumlah kartu voucher diskrit dan preset ditawarkan (misalnya, ₹500, ₹1.000, dan ₹2.000, semuanya dengan diskon tetap 10%). Pastikan bahwa setiap nominal tetap yang terjual habis atau tidak tersedia di halaman landing dikecualikan secara eksplisit dari pengiriman feed.
  • Rentang Kustom: Gunakan secara ketat saat pengguna dapat dengan bebas memasukkan nilai nominal arbitrer apa pun dalam batas yang ditentukan di halaman pembelian (misalnya, nilai apa pun antara ₹100 dan ₹5.000 dengan diskon 5%). Jika halaman landing tujuan menawarkan jumlah diskrit dan preset, modelkan inventaris secara ketat di bagian fixed_denominations. Selain itu, jika nominal tetap dan nominal kustom tersedia untuk penawaran, partner harus menetapkan rentang kustom yang fleksibel.

Fitur yang Tidak Didukung: Batas Pembelian Minimum / Tagihan Minimum (min_spend_value)

Peringatan: Penawaran Batas Pembelanjaan Minimum Kartu Voucher (min_spend_value) tidak didukung. Anda tidak boleh menetapkan min_spend_value pada penawaran yang dimodelkan dengan OFFER_MODE_GIFT_CARD_PURCHASE.

Alasan Voucher Tagihan Minimum Tidak Didukung

Penawaran yang memerlukan jumlah transaksi minimum untuk menukarkan voucher nilai tersimpan (misalnya: "Beli voucher ₹800 seharga ₹150 yang hanya dapat ditukarkan dengan tagihan minimum ₹5.000 atau lebih") berada di luar cakupan integrasi Penawaran Pusat Tindakan saat ini karena alasan berikut:

1. Pengalaman Pengguna yang Menyesatkan &Tidak Intuitif: Menghitung persentase diskon (discount_percent) dengan menggabungkan harga pembelian voucher di muka dengan tagihan checkout minimum hipotetis akan membuat klaim penghematan yang menyesatkan dan tidak intuitif bagi pengguna akhir.
2. Struktur Feed yang Tidak Kompatibel: Feed kartu voucher standar mengasumsikan bahwa nilai nominal (fixed_denominations atau custom_range) dapat digunakan sepenuhnya untuk pembelian di toko mana pun tanpa batasan tagihan bersyarat.
3. Volume Industri Rendah: Penawaran voucher tagihan minimum bersyarat ini mewakili volume keseluruhan yang rendah dan memerlukan penanganan khusus yang berbeda dari kartu voucher nilai tersimpan standar.

Tindakan yang Diperlukan untuk Partner

Jika inventaris Anda menyertakan promosi voucher tagihan minimum bersyarat:

• Hapus dari Feed: Jangan kirimkan voucher hadiah tagihan minimum bersyarat menggunakan OFFER_MODE_GIFT_CARD_PURCHASE (atau mencoba mengabaikan hal ini dengan mengirimkannya di bagian OFFER_MODE_WALK_IN). Hapus promosi tertentu ini dari ekspor feed Anda sepenuhnya.
• Permintaan Pertimbangan Ulang Fitur: Jika Anda yakin bahwa voucher tagihan minimum bersyarat ini mewakili nilai bisnis yang signifikan, Anda dapat membagikan data yang menjelaskan dampaknya terhadap cakupan penjual, rasio konversi transaksi, dan volume keseluruhan kepada Kontak Google (POC) Anda. Tim teknik kami dapat meninjau metrik ini untuk mengevaluasi potensi dukungan di masa mendatang; namun, perhatikan bahwa penyediaan data tidak menjamin bahwa fitur ini akan diprioritaskan atau didukung.

Menangani Rantai Multi-Lokasi

Untuk voucher hadiah yang berlaku di seluruh rantai ritel atau restoran besar yang persyaratannya sama di beberapa tempat menarik (POI), jangan berikan objek Penawaran terpisah untuk setiap lokasi toko. Sebagai gantinya, gunakan pendekatan pemberian feed gabungan dengan memberikan satu objek Penawaran yang berisi daftar semua ID entity toko yang berpartisipasi (entity_ids).

Catatan: Pengecualian berlaku jika URL halaman landing tujuan (offer_url) unik untuk setiap outlet toko. Dalam hal ini, partner harus mengirimkan satu objek Penawaran terpisah per outlet.

Branding Portal (brand_id)

Beberapa voucher ditawarkan melalui portal bank atau loyalitas tertentu (misalnya, program loyalitas bank atau platform partner), bukan situs penjual utama. Untuk memastikan branding yang akurat untuk portal ini, partner harus mengisi kolom brand_id pada objek Penawaran tingkat atas.

Meskipun penghapusan brand_id akan ditetapkan secara default ke merek utama akun (dan brand_id tidak diperlukan saat menggunakan merek default akun), pengisian brand_id secara eksplisit akan mengaitkan inventaris dengan portal bermerek yang sesuai secara akurat, sehingga memastikan bahwa logo dan nama khusus partner yang benar ditampilkan kepada pengguna. Petunjuk lebih lanjut tentang cara mengonfigurasi merek dapat ditemukan di Konfigurasi Merek.

Struktur Validitas (ValidityScope)

Kartu voucher memiliki struktur validitas unik yang membedakan jangka waktu untuk membeli penawaran dari durasi untuk menukarkan kartu. Partner harus selalu menggunakan nilai enum ValidityScope yang relevan:

• VALIDITY_SCOPE_CLAIM: Menentukan jangka waktu penawaran kartu voucher tersedia untuk dibeli di platform partner. Entri ini harus selalu ada. Saat mengirimkan feed, isi periode validitas klaim mulai dari tanggal pengiriman feed yang tepat. Selain itu, jangan pernah membiarkan periode klaim terbuka jika halaman landing secara eksplisit mengiklankan tanggal akhir kampanye; cocokkan valid_through_time dengan tanggal habis masa berlaku yang diiklankan.
• VALIDITY_SCOPE_REDEEM: Menentukan durasi penukaran pasca-pembelian (jangka waktu yang dimiliki pengguna untuk menukarkan voucher di toko setelah membelinya, yang dapat ditentukan sebagai durasi atau jangka waktu).

Pemetaan Jenis Tindakan

Partner sering mengategorikan voucher menggunakan konstruksi seperti "dapat ditukarkan secara online/offline", "online/outlet", atau "di toko". Dalam pengiriman feed, hal ini harus dipetakan ke enum ActionType untuk menentukan secara akurat cara produk digunakan:

• Vertical Restoran / Makanan: Petakan kartu voucher "Makan di tempat" ke ACTION_TYPE_DINING. Petakan kartu voucher "Pengiriman" ke ACTION_TYPE_FOOD_DELIVERY. Petakan kartu voucher "Bawa pulang" ke ACTION_TYPE_FOOD_TAKEOUT.
• Vertical Ritel Belanja: Petakan kartu voucher "Di toko" ke ACTION_TYPE_SHOPPING_IN_STORE. (Catatan: Voucher ritel khusus online tidak didukung).
• Pemetaan Satu Channel: Setiap offer_id hanya dapat dimiliki oleh satu ActionType. Jika item inventaris mendukung beberapa channel pemenuhan (misalnya, pengiriman makanan dan bawa pulang), buat objek Penawaran yang berbeda dengan ID unik untuk setiap mode.

Diskon Bertingkat dan Penawaran Add-On

• Diskon Bertingkat di Seluruh Metode Pembayaran: Jika persentase diskon yang berbeda ditawarkan berdasarkan instrumen pembayaran tertentu yang digunakan (misalnya, diskon yang lebih tinggi untuk e-wallet dibandingkan Kartu Kredit), diskon tersebut harus dimodelkan sebagai objek Penawaran terpisah. Partner harus memberikan cakupan promosi yang lengkap di semua instrumen pembayaran yang didukung (misalnya, e-wallet, Kartu Kredit, Kartu Debit, Net Banking) untuk memastikan pengalaman penghematan yang andal. Jika penawaran berlaku secara universal untuk semua metode pembayaran yang diterima di platform, kolom instrumen pembayaran tidak boleh ditetapkan.
• Konstruksi Penawaran Add-On: Untuk mewakili manfaat bertumpuk, seperti poin reward khusus bank atau cashback tambahan yang berlaku untuk pembelian kartu voucher, kirimkan sebagai penawaran Add-On yang sepenuhnya terpisah menggunakan enum yang sesuai - OFFER_CATEGORY_ADD_ON_PAYMENT_OFFER.OfferCategory Jelaskan reward di dalam OfferDetails.other_offer_details_text (misalnya, "Poin Reward hingga 5X"), dan tautkan ke penawaran kartu voucher dasar dengan mengisi OfferRestrictions.combinable_offer_ids dengan kartu voucher dasar's offer_id.

Persyaratan dan Kondisi Khusus

Partner harus mengandalkan terms.terms_and_conditions untuk memberikan Persyaratan &Ketentuan hukum lengkap dari kartu voucher atau voucher. Gabungkan semua petunjuk dan panduan penggunaan yang ditampilkan kepada pengguna ke dalam kolom ini.

Jika batasan penting memerlukan penonjolan UI khusus (seperti masa berlaku saldo sekali pakai, tidak dapat dikembalikan, atau batas penggabungan transaksi seperti "Maksimum 2 voucher dapat digabungkan per tagihan"), tandai batasan tersebut di offer_restrictions.special_conditions.

Penting: Kondisi penting apa pun yang diisi di special_conditions juga harus disertakan secara lengkap dalam string terms.terms_and_conditions utama.

Rekomendasi Judul Penawaran

Panjang judul penawaran harus tetap kurang dari 40 karakter. Hapus nama merek penjual dari offer_display_text, karena penawaran ditampilkan langsung di kartu tempat khusus penjual. Sebaiknya gunakan format judul berikut:

Kasus penggunaan	Judul yang Direkomendasikan
Diskon tetap untuk voucher	X% off on Gift Cards
Diskon variabel berdasarkan metode pembayaran	X% off on Gift Cards using {e-wallet}
Diskon variabel untuk nominal yang berbeda	X% off on Gift Cards (Kirim diskon yang berbeda sebagai penawaran terpisah)
Kartu voucher B2B2C	X% off on Gift Cards (Branding ditampilkan melalui thumbnail menggunakan brand_id)
Penawaran add-on	Flat/Up to 5X reward points/ <Platform> coins

Persyaratan halaman landing

Setiap offer_url yang diiklankan harus menampilkan HTTP 200 OK secara langsung tanpa pengalihan perantara dan mengarah ke halaman tujuan aktif yang membuktikan penawaran tersebut.

Feed tidak boleh menyertakan nominal yang terjual habis atau tidak tersedia. Pertahankan sinkronisasi inventaris yang ketat antara kolom nominal feed dan opsi pembelian langsung di halaman landing tujuan.

Halaman landing tujuan harus menyebutkan dengan jelas bahwa penawaran berlaku khusus untuk kartu voucher atau voucher.

Misalnya, jika halaman landing partner hanya menampilkan ajakan (CTA) pembayaran umum seperti "Bayar tagihan" tanpa menyatakan secara eksplisit di muka bahwa penyelesaian transaksi akan menerbitkan voucher kartu voucher nilai tersimpan, pengguna yang dialihkan dari Google dan berharap untuk membeli kartu voucher dapat mengalami kebingungan atau pembatalan. Meskipun pemberitahuan voucher muncul pada langkah checkout berikutnya, kejelasan di muka pada halaman landing awal diperlukan.

Penawaran dengan kode kupon

Penawaran tertentu memerlukan entri kode kupon oleh pengguna, seperti "Terapkan kode HEMAT20 untuk mendapatkan diskon 20% dari total tagihan". Perlu diperhatikan bahwa Google tidak menampilkan kode kupon dari definisi kupon. Partner dapat menyertakan informasi ini dalam OfferDetails.offer_display_text untuk ditampilkan kepada pengguna. Penawaran berbasis kupon umumnya dibagi menjadi dua kategori:

• Penawaran yang kuponnya otomatis ditampilkan saat checkout kepada pengguna yang datang dari Google. Penawaran ini diizinkan.
• Penawaran yang mengharuskan pengguna memasukkan kode kupon saat checkout, tetapi tidak memberikan petunjuk tentang cara menerapkan kode kupon di halaman landing URL penawaran, atau tidak otomatis menerapkan kupon saat mengikuti URL penawaran, tidak diizinkan.

Contoh JSON Penawaran Kartu Voucher

{
  "data": [
    {
      "offer_id": "example-dining-gift-card-10off",
      "entity_ids": [
        "dining-1",
        "dining-2"
      ],
      "offer_modes": [
        "OFFER_MODE_GIFT_CARD_PURCHASE"
      ],
      "action_type": "ACTION_TYPE_DINING",
      "offer_source": "OFFER_SOURCE_AGGREGATOR",
      "offer_category": "OFFER_CATEGORY_BASE_OFFER",
      "offer_details": {
        "offer_display_text": "10% off on Gift Cards",
        "discount_percent": 10.0,
        "gift_card_info": {
          "fixed_denominations": {
            "amounts": [
              {
                "units": 500,
                "currency_code": "INR"
              },
              {
                "units": 1000,
                "currency_code": "INR"
              },
              {
                "units": 2000,
                "currency_code": "INR"
              }
            ]
          }
        }
      },
      "offer_restrictions": {
        "combinable_with_other_offers": false,
        "special_conditions": [
          "Single-use balance expiration applies",
          "Maximum 2 gift card vouchers can be combined per bill",
          "No cash refund will be provided against this voucher"
        ]
      },
      "terms": {
        "restricted_to_certain_users": false,
        "terms_and_conditions": "1. Redeemable exclusively at participating dining outlets.\n2. Single-use balance expiration applies.\n3. Maximum 2 gift card vouchers can be combined per bill.\n4. No cash refund will be provided against this voucher."
      },
      "validity_periods": [
        {
          "valid_period": {
            "valid_from_time": {
              "seconds": "1774934350"
            },
            "valid_through_time": {
              "seconds": "1806470350"
            }
          },
          "validity_scope": "VALIDITY_SCOPE_CLAIM"
        },
        {
          "validity_duration_in_days": 365,
          "validity_scope": "VALIDITY_SCOPE_REDEEM"
        }
      ],
      "offer_url": "https://www.example-portal.com/dining-gift-cards/buy"
    }
  ]
}