star

Artikel disunting oleh: OOOPEN Lab | 2026-09-15

Atur pengiriman data kegiatan merek

Atur pengiriman data kegiatan merek

Pengiriman data kegiatan mengirim aktivitas dari proyek yang dipilih ke CRM, sistem keanggotaan, atau layanan penukaran Anda. Platform menentukan format peristiwa dan cara pengirimannya. Fitur ini tidak menjamin kompatibilitas tanpa pengaturan dengan setiap CRM, dan pengiriman data itu sendiri tidak otomatis memberi tag CRM, menerbitkan kupon, atau menulis data anggota. Anda tidak memerlukan ruang data anggota untuk membuatnya; keberadaan ruang tersebut hanya menentukan peristiwa yang dapat diterima. Setiap koneksi pengiriman memiliki secret penandatanganan khusus dan tidak pernah menggunakan API Key akun Anda.

Pengiriman data kegiatan tersedia untuk semua akun. Untuk membuat koneksi, akun harus memiliki paket berbayar aktif, sama seperti Webhooks. Keduanya dapat digunakan secara bersamaan.

Perlu memperbarui tag anggota SHOPLINE atau memberikan hadiah? Pilih jalur pengaturan dahulu

Untuk memberi tag anggota SHOPLINE berdasarkan hasil kuis, atau memberikan kredit toko, poin anggota, dan kupon yang dapat diklaim, pemilik proyek yang memiliki akses Beta otomatisasi SHOPLINE dapat memeriksa apakah fitur bawaan Otomatisasi kampanye SHOPLINE sesuai. Tindakan bawaan ini tidak memerlukan sistem penerima Webhook tersendiri. Ikuti panduan login anggota SHOPLINE dan otomatisasi kampanye, lalu periksa persyaratan proyek dan otorisasi toko.

Untuk mengirim jawaban atau data kegiatan ke CRM dan sistem keanggotaan sendiri, atau menyerahkan pemrosesan bisnis berikutnya kepada sistem sendiri, gunakan pengiriman data kegiatan. Login anggota merek, otomatisasi SHOPLINE, dan pengiriman data kegiatan memiliki pengaturan serta persyaratan akses yang terpisah.

Jika penerima Webhook sendiri sudah memberikan hadiah yang sama, tentukan pihak yang bertanggung jawab sebelum mengaktifkan otomatisasi bawaan. Jangan sampai kedua sistem masing-masing memberikan hadiah tersebut.

Sebelum memulai

  • Siapkan endpoint HTTPS publik pada port 443. Endpoint tidak boleh mengalihkan permintaan atau mengarah ke jaringan privat.
  • Pastikan penerima dapat menyimpan eventId serta menerapkan deduplikasi dan pembaruan bisnis dalam satu transaksi basis data.
  • Hanya ingin menerima peristiwa Jawaban selesai? Anda tidak memerlukan ruang data anggota. Langsung lanjutkan ke pembuatan koneksi di bawah.
  • Ingin menerima Misi selesai, Poin benar-benar ditambahkan, atau Penukaran platform, atau mengenali pemain yang sama lintas kuis? Buat ruang data anggota dan koneksi login anggota terlebih dahulu, lalu aktifkan login tersebut pada setidaknya satu proyek. Kartu loyalitas atau Halaman acara harus terikat ke ruang data anggota tersebut untuk mengirim peristiwa ini.

Buat pengiriman data kegiatan

  1. Buka Pengaturan akun, lalu Pengembang.
  2. Pada Pengiriman data kegiatan, pilih identitas yang digunakan koneksi ini: ruang data anggota atau Tanpa identitas anggota.
  3. Masukkan nama dan endpoint HTTPS port 443.
  4. Pilih Format baru (disarankan) atau Format Webhook yang sudah ada. Format tidak dapat diubah setelah pembuatan; buat koneksi lain untuk menggunakan format berbeda.
  5. Pilih peristiwa serta proyek yang boleh mengirimnya. Jika Tanpa identitas anggota dipilih, hanya Jawaban selesai yang benar-benar dipicu; tiga peristiwa lainnya memerlukan ruang data anggota.
  6. Buat koneksi dan segera simpan secret penandatanganannya. Secret hanya ditampilkan sekali.
  7. Kirim peristiwa uji dan pastikan status Terkirim. HTTP 200 hanya membuktikan pengiriman, bukan penerbitan kupon, pemberian label, poin, atau tindakan bisnis lainnya.

Empat peristiwa yang tersedia adalah Jawaban selesai, Misi selesai, Poin benar-benar ditambahkan, dan Penukaran platform. Peristiwa Dimulai tidak tersedia. Jika memilih Tanpa identitas anggota, jawaban dari pemain yang tidak login menggunakan ID anonim yang diturunkan dari jawaban itu. Jawaban dari pemain yang memakai login platform menggunakan ID stabil player:v1: yang dapat mengenali login yang sama lintas proyek dan dapat menyertakan playerLoginId. Login platform ini tidak memverifikasi identitas anggota merek. Untuk mengandalkan identitas anggota merek, gunakan ruang data anggota dan koneksi login yang sama pada proyek terkait.

Misi selesai, Poin benar-benar ditambahkan, dan Penukaran platform dikirim oleh proyek penghasil peristiwa. Proyek itulah yang perlu dicentang pada daftar proyek yang diizinkan, bukan kuis yang dimainkan pemain untuk suatu misi:

  • Kartu loyalitas atau Halaman acara yang berdiri sendiri: centang kartu itu sendiri dan pastikan terikat ke ruang data anggota yang dipilih. Jika tidak terikat, ketiga peristiwa tidak dikirim.
  • Grup proyek kegiatan: centang kedua proyek permainan dalam grup untuk Misi selesai dan Poin benar-benar ditambahkan, serta proyek kartu loyalitas grup untuk Penukaran platform.

Daftar proyek yang diizinkan hanya menampilkan proyek yang dapat menghasilkan peristiwa yang dicentang. Centang Jawaban selesai, atau jangan centang apa pun, untuk menampilkan semua proyek. Jika proyek yang dibutuhkan tidak muncul, periksa terlebih dahulu apakah loginnya sudah diserahkan ke ruang data anggota tersebut.

Maggie menjalankan kuis merek kecantikan dan belum menyiapkan ruang data anggota. Ia memilih Tanpa identitas anggota, hanya mengaktifkan Jawaban selesai, dan menggunakan answerId untuk mengelompokkan pemain berdasarkan hasil. Kevin menjalankan kampanye loyalitas dua tahap dan membutuhkan Misi selesai serta Poin benar-benar ditambahkan. Ia membuat ruang data anggota terlebih dahulu, memilihnya sebagai identitas koneksi ini, dan mencentang kedua proyek permainan dalam grup proyek kegiatan, sehingga penerima dapat mencatat bukti penyelesaian serta poin yang benar-benar dibukukan secara terpisah. Daniel menjalankan alur kupon hari anggota dan mengaktifkan Jawaban selesai serta Penukaran platform. Ia juga memerlukan ruang data anggota, mencentang proyek kartu loyalitas yang menjalankan penukaran, melakukan deduplikasi berdasarkan eventId terlebih dahulu, dan menyerahkan keputusan penerbitan kupon kepada sistem keanggotaannya sendiri.

Body dan tanda tangan Format baru

Format baru mengirim peristiwa otoritatif secara lengkap:

{
  "brandId": "brand_123",
  "campaignId": "campaign_123",
  "eventId": "64-character-sha256-event-id",
  "externalUserId": "brand:v2:canonical-member-id",
  "occurredAt": "2026-09-15T08:00:00.000Z",
  "payload": { "answerId": "answer_123" },
  "schemaVersion": 2,
  "source": {
    "firebaseProject": "ooopen-project",
    "path": "answers/answer_123",
    "id": "answer_123"
  },
  "sourceProjectId": "quiz_123",
  "type": "finish",
  "webhookConnectionId": "connection_123"
}

Jika memilih Tanpa identitas anggota, brandId selalu bernilai khusus __no-brand__ dan campaignId selalu __no-campaign__. Untuk pemain yang tidak login, externalUserId adalah kode anonim yang diturunkan dari answerId (anon:v1:...). Untuk pemain yang memakai login platform, nilainya adalah player:v1:... dan peristiwa mungkin menyertakan playerLoginId. Nilai khusus tersebut bukan data merek atau kegiatan sebenarnya, dan identitas login platform bukan identitas anggota merek terverifikasi. Jika memilih ruang data anggota, externalUserId adalah ID brand:v2:... yang dibuat platform, bukan LINE userId asli. Jika dokumen identitas memuat ID anggota asli, peristiwa juga dapat menyertakan brandMemberId; dokumen identitas lama dan peristiwa uji mungkin tidak memiliki kolom itu.

Baca body permintaan yang belum diurai. Gabungkan X-OOOPEN-Webhook-Timestamp, satu tanda titik, dan seluruh byte body mentah. Hitung HMAC-SHA256 dengan secret penandatanganan koneksi dan enkode sebagai base64url. Tolak timestamp yang lebih lama dari lima menit. Bandingkan hasilnya dengan X-OOOPEN-Webhook-Signature, lalu pastikan X-OOOPEN-Webhook-Event-Id sama dengan eventId pada body.

const signedBytes = Buffer.concat([
  Buffer.from(timestamp + '.', 'utf8'),
  rawBody
]);
const expected = crypto
  .createHmac('sha256', signingSecret)
  .update(signedBytes)
  .digest('base64url');

Isi payload finish

payload hanya membawa kolom catatan respons yang sudah ada saat respons selesai. Sistem tidak pernah membaca isi kuis saat ini: tidak ada nama kuis, label hasil, maupun teks pertanyaan atau pilihan. Alasannya, body ini ditandatangani dan dapat dikirim ulang. Jika pengiriman ulang membaca isi kuis “hari ini”, peristiwa lama yang diputar ulang setelah kreator menyunting kuis akan melaporkan isi yang sebenarnya tidak terjadi pada waktu itu. Untuk menampilkan nama yang mudah dibaca, cari sendiri menggunakan quizId dan result melalui Creator Data API di /api/v1/quizzes/{quizId}/answers/{answerId}.

  • answerId: ID respons ini. Selalu ada.
  • quizId: proyek tempat respons ini berada. Selalu ada.
  • startedAt: waktu peserta mulai menjawab, bukan waktu selesai. Hanya ada jika diatur.
  • ref: kode perujuk yang dicatat pada respons. Hanya ada jika diatur.
  • result: pengenal hasil, tidak pernah berupa label. Hanya ada jika diatur.
  • answers: jawaban yang dikirim, persis seperti yang disimpan. Hanya ada jika diatur.
  • answersTruncated: true jika isi dihapus karena ukurannya. Tidak pernah muncul bersama answers.
  • utm: data atribusi, hanya ada jika akun memiliki fitur ekspor UTM berbayar.

Kolom kontak tidak pernah disertakan: tidak ada email, dan utm.code (kode penukaran) tidak dikirim.

Body dan tanda tangan Format Webhook yang sudah ada

Pilih Format Webhook yang sudah ada hanya jika penerima membutuhkan pembungkus data, type, dan timestamp. Format ini tetap menggunakan secret khusus koneksi baru. OOOPEN Lab tidak memanggil Webhook lama atau membuat-buat kolom kartu, anggota, maupun saldo lama. Aturan identitas khusus sama dengan Format baru: jika Tanpa identitas anggota dipilih, brandId dan campaignId tetap bernilai __no-brand__ dan __no-campaign__.

{
  "data": {
    "wireSchema": "ooopen-brand-activity-webhook-legacy-envelope/1",
    "eventId": "64-character-sha256-event-id",
    "type": "finish",
    "occurredAt": "2026-09-15T08:00:00.000Z",
    "brandId": "brand_123",
    "sourceProjectId": "quiz_123",
    "campaignId": "campaign_123",
    "webhookConnectionId": "connection_123",
    "externalUserId": "brand:v2:canonical-member-id",
    "payload": { "answerId": "answer_123" }
  },
  "type": "finish",
  "timestamp": "2026-09-15T08:00:00.000Z"
}

Hitung HMAC-SHA256 atas byte JSON data terserialisasi yang persis, enkode sebagai heksadesimal huruf kecil, lalu bandingkan dengan x-ooopenlab-signature. Setelah tanda tangan terverifikasi, wajibkan type luar sama dengan data.type dan timestamp sama dengan data.occurredAt. Terakhir, validasi wireSchema, jenis peristiwa, dan payload bertipenya. Jangan menjalankan verifikator Format baru pada body ini atau verifikator ini pada body Format baru.

Lakukan deduplikasi sebelum tindakan bisnis

  1. Verifikasi tanda tangan dan format.
  2. Cari eventId dalam transaksi basis data.
  3. Jika sudah diproses, kembalikan HTTP 200 tanpa menerbitkan kupon atau menambahkan poin lagi.
  4. Jika belum, simpan eventId dan hasil bisnis dalam transaksi yang sama.
  5. Kembalikan HTTP 200 hanya setelah transaksi berhasil dikomit.

Percobaan ulang otomatis maupun pengiriman ulang manual mempertahankan body pertama, eventId, deliveryId, dan format. Status Pengiriman tidak diketahui berarti penerima mungkin sudah memproses peristiwa; periksa eventId sebelum mengirim ulang. Catatan pengiriman hanya dapat diputar ulang selama masa retensinya.

Rotasi atau nonaktifkan koneksi

Rotasi secret penandatanganan langsung mencabut secret lama. Perbarui penerima dan kirim pengujian lagi dengan secret baru. Koneksi yang dinonaktifkan tidak dapat mengirim pengujian, mengirim peristiwa, atau mengirim ulang suatu pengiriman.

Beralih dari Webhook yang sudah ada

Webhook yang sudah ada secara bawaan berlaku untuk seluruh akun: dipicu untuk setiap kuis pada akun Anda kecuali diarahkan ke satu kuis tertentu. Pengiriman data kegiatan mewajibkan Anda memilih secara eksplisit proyek sumbernya saat pembuatan, hingga 50 proyek per koneksi. Webhook yang sudah ada memiliki peristiwa Dimulai; pengiriman data kegiatan sama sekali tidak menyediakannya. Beralih berarti menghapus peristiwa tersebut tanpa peristiwa pengganti.

Kunci penandatanganan berubah: gunakan endpoint baru selama peralihan

Webhook yang sudah ada menandatangani data dengan API Key akun Anda. Jika koneksi pengiriman data kegiatan menggunakan Format Webhook yang sudah ada, nama header tetap x-ooopenlab-signature, tetapi kunci penandatanganannya adalah secret khusus koneksi tersebut, bukan API Key akun Anda. Jika penerima tetap memverifikasi header menggunakan API Key akun, setiap pengiriman dari koneksi baru gagal verifikasi tanda tangan. Jika Webhook lama dan koneksi baru sama-sama mengirim POST ke endpoint yang sama selama peralihan, sementara penerima hanya memercayai satu kunci, salah satu sisi pasti gagal.

Jika keduanya harus ditangani pada satu endpoint, bedakan melalui body: pengiriman baru dengan Format Webhook yang sudah ada selalu memiliki wireSchema dan eventId dalam data; payload Webhook lama tidak memiliki keduanya. Pilihan yang lebih sederhana dan aman adalah memberi koneksi pengiriman data kegiatan endpoint URL baru sendiri selama peralihan, alih-alih menggunakan kembali URL Webhook lama. Dengan begitu, setiap sisi memverifikasi kuncinya sendiri dan penerima tidak perlu menentukan “lama atau baru” pada jalur kode yang sama. Hapus pengaturan Webhook lama pada Webhook yang sudah ada (hanya pengelolaan) hanya setelah koneksi baru dipastikan berfungsi.

Memilih Format baru sepenuhnya menghindari masalah ini: format tersebut selalu mengirim tiga header berbeda (X-OOOPEN-Webhook-Timestamp, X-OOOPEN-Webhook-Event-Id, X-OOOPEN-Webhook-Signature), tanda tangan mencakup timestamp yang digabungkan dengan body mentah, timestamp lebih lama dari lima menit ditolak, dan tidak ada yang tumpang tindih dengan header Webhook lama.

Langkah peralihan

  1. Tambahkan verifikator tanda tangan baru dan deduplikasi eventId transaksional pada penerima. Jika pengiriman lama dapat tumpang tindih, lakukan juga deduplikasi berdasarkan answerId.
  2. Pilih kembali identitas (ruang data anggota atau Tanpa identitas anggota), proyek, peristiwa, dan format pada Pengiriman data kegiatan.
  3. Simpan secret baru dan pastikan pengiriman uji berhasil.
  4. Aktifkan koneksi baru terlebih dahulu dan pantau penerimaan.
  5. Hapus pengaturan lama hanya setelah alur baru berfungsi.

Peralihan tidak dapat menjamin tanpa peristiwa duplikat. Selesaikan deduplikasi penerima sebelum menghentikan pengaturan lama.


Anda mungkin juga menyukai…

  • Cara menghubungkan login anggota SHOPLINE dan otomatisasi kampanye
    Cara menghubungkan login anggota SHOPLINE dan otomatisasi kampanye
    Lihat selengkapnya
  • Tes psikologi, multifaktor, atau berbasis skor? Panduan lengkap pemetaan hasil
    Tes psikologi, multifaktor, atau berbasis skor? Panduan lengkap pemetaan hasil
    Lihat selengkapnya
  • Apa yang terjadi saat paket berakhir? Daftar periksa data dan publikasi
    Apa yang terjadi saat paket berakhir? Daftar periksa data dan publikasi
    Lihat selengkapnya

Buat komunikasi merek lebih seru

BerandaTentang OOOPEN LabTentangKetentuan layanan dan kebijakan privasiPengungkapan transmisi eksternalLaporkan penyalahgunaan

Copyright © 2026 OOOPEN Lab