Widget untuk developer

Halaman ini ditujukan untuk developer: detail teknis kode sematan, mengendalikan widget dari JavaScript, dan mengenali pengguna yang sudah masuk ke situs Anda. Untuk langkah pemasangan di HTML, WordPress, atau Shopify, lihat Pasang chat.

Kode sematan

Setiap situs punya kunci sendiri. Salin kode sematan dari Situs → situs Anda lalu tempel sebelum </body>:

html

<script src="https://cdn.sealreply.com/widget.js" data-site-key="sk_…" async></script>

Widget hanya dimuat di domain yang diizinkan untuk situs tersebut (beserta subdomainnya), setelah domain pertama diverifikasi. Di domain lain, widget tetap tidak terlihat.
Widget dirender di dalam Shadow DOM, sehingga CSS halaman Anda tidak mengubahnya dan CSS widget tidak bocor ke halaman Anda.
Widget mengikuti bahasa browser pengunjung kecuali situs menetapkan satu bahasa, dan mengingat pengunjung yang kembali di localStorage.

Content Security Policy

Jika situs Anda mengirim header CSP, izinkan:

script-src https://cdn.sealreply.com;
connect-src https://api.sealreply.com wss://rt.sealreply.com;
img-src https://api.sealreply.com;

API JavaScript

Setelah skrip dimuat, window.SealReply mengendalikan widget:

Panggilan	Fungsinya
`SealReply.open()`	Membuka jendela chat.
`SealReply.close()`	Menutupnya.
`SealReply.on(event, handler)`	Memanggil `handler` saat terjadi event (lihat di bawah).
`SealReply.off(event, handler)`	Berhenti memanggilnya.
`SealReply.identify(identity)`	Memberi tahu widget siapa pengguna Anda yang sudah masuk (lihat Mengenali pengguna yang sudah masuk).
`SealReply.reset()`	Melupakan pengunjung, misalnya saat mereka keluar. Chat berikutnya dimulai dari awal.
`SealReply.version`	Versi widget.

Event	Kapan	`handler` menerima
`ready`	Widget sudah dimuat	tidak ada
`open` / `close`	Jendela chat dibuka atau ditutup, oleh pengunjung atau oleh kode Anda	tidak ada
`message`	Pesan dari agen (atau dari integrasi Anda) masuk	`{ id, text, content_type, created_at }`

Skrip dimuat secara async, jadi tunggu sampai selesai sebelum memanggil SealReply. Dengarkan event sealreply:ready di window, atau periksa apakah skrip sudah dimuat:

html

<button id="help">Chat with us</button>
<script>
  function whenReady(fn) {
    if (window.SealReply) fn();
    else window.addEventListener("sealreply:ready", fn, { once: true });
  }
  whenReady(() => {
    document.getElementById("help").onclick = () => SealReply.open();
    SealReply.on("message", (m) => console.log("New reply:", m.text));
  });
</script>

Error yang dilempar oleh handler Anda ditangkap, sehingga tidak bisa merusak chat.

Tanpa tombol chat: buka dari tombol Anda sendiri

Untuk membuka chat dari tombol atau menu Anda sendiri (misalnya menu "Bantuan"), tambahkan data-launcher="none" ke kode sematan:

html

<script src="https://cdn.sealreply.com/widget.js" data-site-key="sk_…" data-launcher="none" async></script>

Tidak ada tombol yang muncul di pojok dan tidak ada gelembung yang muncul; chat hanya terbuka saat Anda memanggil SealReply.open(). Untuk menampilkan titik di tombol Anda saat balasan masuk ketika chat sedang tertutup, dengarkan event message.

Mengenali pengguna yang sudah masuk

Jika situs Anda punya sistem login sendiri, widget bisa memberi tahu agen Anda dengan siapa mereka sedang berbicara: pengunjung tampil dengan namanya sendiri, ditandai Terverifikasi, dan dikenali sebagai pengunjung yang sama di setiap perangkat. Agar tidak ada yang bisa menyamar sebagai orang lain, ID setiap pengguna ditandatangani di server Anda dengan rahasia yang hanya diketahui oleh Anda dan SealReply.

Di Situs → situs Anda → Verifikasi identitas pengunjung, pilih Aktifkan dan salin rahasianya. Rahasia hanya ditampilkan sekali; simpan di server Anda seperti kata sandi.

Di server Anda, hitung identity_hash pengguna: HMAC-SHA256 dalam format hex dari ID mereka, dengan rahasia sebagai kuncinya.

Node.jsPHPPythonGo

import { createHmac } from "node:crypto";

const identityHash = createHmac("sha256", process.env.SEALREPLY_IDENTITY_SECRET)
  .update(String(user.id))
  .digest("hex");

php

$identityHash = hash_hmac('sha256', (string) $user->id, getenv('SEALREPLY_IDENTITY_SECRET'));

python

import hmac, hashlib, os

identity_hash = hmac.new(os.environ["SEALREPLY_IDENTITY_SECRET"].encode(), str(user.id).encode(), hashlib.sha256).hexdigest()

mac := hmac.New(sha256.New, []byte(os.Getenv("SEALREPLY_IDENTITY_SECRET")))
mac.Write([]byte(userID))
identityHash := hex.EncodeToString(mac.Sum(nil))

Di halaman tempat pengguna sudah masuk, kirimkan ke widget sebelum widget.js:

html

<script>
  window.sealreplySettings = {
    identity: {
      external_id: "42",            // the user's ID on your site (up to 128 characters)
      identity_hash: "<from your server>",
      name: "Ana López",            // optional, shown to agents
      email: "ana@example.com",     // optional
    },
  };
</script>
<script src="https://cdn.sealreply.com/widget.js" data-site-key="sk_…" async></script>

Di aplikasi satu halaman (SPA), panggil SealReply.identify({ external_id, identity_hash, name, email }) setelah pengguna masuk (widget dimuat ulang sebagai pengguna tersebut), dan SealReply.reset() saat mereka keluar.

Yang terjadi:

Dengan tanda tangan yang valid, pengunjung terikat ke external_id: percakapan mereka mengikuti mereka di semua perangkat. external_id diperiksa persis seperti yang Anda tandatangani (tanpa pemangkasan spasi atau perubahan huruf besar/kecil).
Hanya external_id yang ditandatangani. name dan email mengisi detail pengunjung jika belum ada yang dicatat, dan tidak pernah menggantikan apa yang dimasukkan agen Anda; anggap keduanya sebagai informasi dari halaman, bukan data yang terverifikasi.
Tanda tangan yang tidak ada atau salah, atau situs yang verifikasinya nonaktif, hanya membuat pengunjung tetap anonim; widget tetap berfungsi.
Setelah pengguna keluar, ID anonim di browser tidak lagi bisa membuka percakapan mereka; hanya tanda tangan yang valid yang bisa. Tetap panggil SealReply.reset() saat pengguna keluar: jika tidak, chat anonim yang dimulai setelahnya di komputer bersama akan terhubung ke pengguna berikutnya yang masuk di sana.
Pengunjung yang sudah masuk bisa membuka chat mereka sebelumnya di situs Anda dari menu widget, di perangkat mana pun. Hanya chat yang dimulai sejak mereka pertama kali masuk yang ditampilkan, sehingga apa pun yang dilakukan seseorang secara anonim di komputer bersama sebelumnya tidak ikut tampil. Perlakukan identity_hash seperti kata sandi: siapa pun yang memilikinya bisa membaca riwayat chat pengguna tersebut, jadi tandatangani di server Anda dan jangan pernah menaruhnya di URL atau halaman yang bisa dilihat orang lain (di halaman chat untuk aplikasi, bagian setelah # tidak pernah dikirim ke server: lihat Tambahkan chat ke aplikasi Anda).
Tanda tangan tidak memiliki masa berlaku. Jika ada yang mungkin bocor, buat rahasia baru.
Buat rahasia baru langsung menonaktifkan rahasia lama, jadi perbarui server Anda terlebih dahulu. Matikan membuat semua pengunjung kembali anonim.

Peringatan

Hitung identity_hash hanya di server Anda. Jangan pernah menaruh rahasia di halaman atau aplikasi Anda.

Mengirim detail anggota

Anda juga bisa menampilkan detail kepada agen, seperti paket keanggotaan, jumlah pesanan, atau total belanja seorang anggota: detail ini muncul di tab Pengunjung di samping percakapan, sehingga tidak ada yang perlu mencarinya. Agar pengunjung tidak bisa mengubahnya di browser (misalnya menjadi "Diamond"), detail ini juga ditandatangani di server Anda.

Siapkan atributnya: kunci maksimal 40 karakter, tanpa = atau baris baru; value maksimal 200 karakter, tanpa baris baru; paling banyak 30 atribut.
Susun teks yang akan ditandatangani: ID pengguna, lalu satu baris key=value per atribut diurutkan berdasarkan kunci, semuanya digabung dengan baris baru \n. Untuk pengguna 42 dan { plan: "Gold", orders: "12" }:
text
```
42
orders=12
plan=Gold
```

Tandatangani teks tersebut dengan HMAC-SHA256 dan rahasia yang sama untuk mendapatkan attributes_hash:

Node.jsPHPPythonGo

const attributes = { plan: "Gold", orders: "12" };
const message = [String(user.id), ...Object.keys(attributes).sort().map((k) => `${k}=${attributes[k]}`)].join("\n");
const attributesHash = createHmac("sha256", process.env.SEALREPLY_IDENTITY_SECRET).update(message).digest("hex");

php

$attributes = ['plan' => 'Gold', 'orders' => '12'];
ksort($attributes, SORT_STRING);
$lines = [(string) $user->id];
foreach ($attributes as $k => $v) { $lines[] = "$k=$v"; }
$attributesHash = hash_hmac('sha256', implode("\n", $lines), getenv('SEALREPLY_IDENTITY_SECRET'));

python

attributes = {"plan": "Gold", "orders": "12"}
message = "\n".join([str(user.id)] + [f"{k}={attributes[k]}" for k in sorted(attributes)])
attributes_hash = hmac.new(os.environ["SEALREPLY_IDENTITY_SECRET"].encode(), message.encode(), hashlib.sha256).hexdigest()

keys := make([]string, 0, len(attributes))
for k := range attributes { keys = append(keys, k) }
sort.Strings(keys)
lines := []string{userID}
for _, k := range keys { lines = append(lines, k+"="+attributes[k]) }
mac := hmac.New(sha256.New, []byte(os.Getenv("SEALREPLY_IDENTITY_SECRET")))
mac.Write([]byte(strings.Join(lines, "\n")))
attributesHash := hex.EncodeToString(mac.Sum(nil))

Kirimkan bersama identitas:

window.sealreplySettings = {
  identity: {
    external_id: "42",
    identity_hash: "<signature of the user ID>",
    attributes: { plan: "Gold", orders: "12" },
    attributes_hash: "<signature of the attributes>",
  },
};

Dengan tanda tangan yang valid, atribut tersebut menggantikan detail anggota pengunjung secara keseluruhan; dengan tanda tangan yang salah atau tidak ada, atribut diabaikan dan identifikasi tetap berjalan seperti biasa. Gunakan hanya huruf ASCII, angka, dan garis bawah untuk kunci (misalnya total_spent), agar pengurutan bawaan di setiap bahasa pemrograman menghasilkan urutan yang sama; value boleh berisi teks apa pun.

Widget untuk developer ​

Kode sematan ​

Content Security Policy ​

API JavaScript ​

Tanpa tombol chat: buka dari tombol Anda sendiri ​

Mengenali pengguna yang sudah masuk ​

Mengirim detail anggota ​

Kode sematan

Content Security Policy

API JavaScript

Tanpa tombol chat: buka dari tombol Anda sendiri

Mengenali pengguna yang sudah masuk

Mengirim detail anggota