Access Tags

Ringkasan

Tidak semua konten untuk semua orang: dokumen khusus anggota, materi khusus wilayah, sumber daya tingkat berbayar. Dengan Access Tags, satu chatbot melayani audiens berbeda dengan aman. Anda memberi tag pada item pengetahuan, dan sejak saat itu item tersebut tak terlihat bagi setiap pengunjung — kecuali mereka yang halamannya menunjukkan tag itu, ditandatangani oleh server Anda sendiri. Pembatasan ditegakkan dalam kueri pengambilan kami, bahkan sebelum model AI terlibat. Pengunjung tanpa tag tidak bisa memancing konten dengan pertanyaan cerdik, karena bagi mereka konten itu tidak pernah diambil.

Cara Kerjanya

1. Anda memberi tag pada item pengetahuan - di halaman Access Tags atau langsung lewat API; item tanpa tag tetap berfungsi untuk semua orang
2. Server Anda menandatangani tag setiap pengunjung - saat anggota yang login memuat halaman Anda, back-end menentukan haknya dan menandatanganinya dengan kunci rahasia yang hanya Anda miliki
3. Widget mengirim bukti bertanda tangan - ikut dengan setiap pesan chat; browser hanya mengangkutnya dan tidak bisa mengubahnya tanpa merusak tanda tangan
4. Kami memverifikasi dan menyaring - tanda tangan valid membuka item dengan tag yang cocok; bukti yang hilang, diubah, atau kedaluwarsa berarti pengunjung hanya mendapat konten publik

Cara mengaturnya

Aktifkan fitur di halaman Access Tags di dasbor — kunci penandatanganan dibuat otomatis. Simpan hanya di server Anda; siapa pun yang memilikinya dapat membuat bukti yang valid.

Beri tag konten di halaman yang sama, atau saat mengirim item lewat API:

POST /api/v1/knowledge/text/
{
  "title": "Members-only price list",
  "content": "...",
  "website_id": "123",
  "access_tags": ["premium"]
}

Lalu minta server Anda mencetak bukti bertanda tangan di samping snippet widget. Pesan yang ditandatangani adalah daftar tag yang dipisahkan koma, digabung dengan garis tegak ke waktu kedaluwarsa jika Anda memakainya:

<?php
$tags    = "members,premium";          // this visitor's entitlements
$expires = time() + 3600;              // unix seconds, optional but recommended
$sig     = hash_hmac("sha256", $tags . "|" . $expires, $SECRET);
?>
<script>
window.Asyntai = window.Asyntai || {};
window.Asyntai.accessTags = "<?php echo $tags; ?>";
window.Asyntai.accessTagsExpires = "<?php echo $expires; ?>";
window.Asyntai.accessTagsSignature = "<?php echo $sig; ?>";
</script>

Tanda tangan yang sama di Node.js dan Python:

// Node.js
const crypto = require("crypto");
const sig = crypto.createHmac("sha256", SECRET)
                  .update(tags + "|" + expires).digest("hex");

# Python
import hmac, hashlib
sig = hmac.new(SECRET.encode(), f"{tags}|{expires}".encode(),
               hashlib.sha256).hexdigest()

Tanpa kedaluwarsa, cukup tanda tangani string tag saja. Dengan kedaluwarsa, bukti berhenti berfungsi begitu lewat waktunya — berguna saat hak bisa dicabut, karena pengunjung harus memuat ulang halaman yang Anda kendalikan untuk mendapat bukti baru.

Logika tag

Tag pada sebuah item digabungkan dengan DAN: item hanya bisa diambil ketika setiap tag padanya muncul dalam bukti pengunjung. Bukti pengunjung boleh membawa sebanyak apa pun hak, dan pencocokan dilakukan pada semuanya sekaligus.

DAN memang disengaja. Dengan pencocokan «salah satu», menambahkan tag kedua pada item justru memperluas siapa yang bisa melihatnya, sehingga mempersempit dokumen ke dua kelompok sebenarnya menerbitkannya utuh untuk keduanya. Dengan pencocokan «semua», setiap tag yang Anda tambahkan hanya bisa mempersempit lebih jauh, sehingga kesalahan jatuh ke sisi yang aman.

Menyatakan «salah satu dari»

Hilangkan dimensi itu dari item. Jika bukti setiap pengunjung membawa wilayahnya, maka dokumen tanpa tag wilayah tersedia untuk semua wilayah, sementara tag lainnya tetap berlaku. Jadi item yang hanya bertag premium berarti «wilayah mana pun, hanya pelanggan premium».

Untuk pilihan lintas dimensi yang sesungguhnya — misalnya utara-dengan-dasar atau selatan-dengan-premium, dan tidak yang lain — tambahkan item dua kali dengan satu kombinasi masing-masing, atau beri kedua audiens satu tag bersama yang disertakan server Anda dalam bukti mereka.

Batas

• Hingga 20 tag per item pengetahuan
• Hingga 50 tag dalam bukti satu pengunjung
• 50 karakter per tag; koma dan garis tegak tidak diizinkan, karena bukti adalah string yang dipisahkan koma

Mengubah tag di kemudian hari

Tag dapat diganti pada item yang sudah ada tanpa mengunggahnya lagi. Perubahan berlaku mulai pertanyaan berikutnya — kontennya sendiri tidak diproses ulang.

POST /api/v1/knowledge/<id>/tags/
{
  "access_tags": ["premium"]
}

Kirim daftar kosong untuk menjadikan item publik kembali. Anda juga bisa menyunting tag secara manual di halaman Access Tags pada dasbor.

Apa yang dijamin

• Penegakan sisi server - filter berjalan di dalam kueri basis data saat pengambilan; bagi pengunjung tak berwenang, item bertag sama sekali tidak masuk konteks AI, jadi tidak ada yang bisa bocor
• Fail-closed di mana-mana - tanpa tanda tangan, tanda tangan salah, bukti kedaluwarsa, fitur mati, paket diturunkan: dalam setiap kasus itu pengunjung hanya mendapat konten publik, tidak pernah lebih
• Browser tidak bisa memalsukan akses - mengedit tag di alat pengembang merusak tanda tangan; kunci hanya ada di server Anda
• Logika hak Anda tetap milik Anda - kami tidak pernah tahu bagaimana Anda memutuskan siapa mendapat tag apa; kami hanya memverifikasi bahwa server Anda menyatakannya

Perlu diketahui

• Access Tags adalah otorisasi, User Context adalah personalisasi - gunakan User Context untuk memberi tahu AI tentang anggota; gunakan Access Tags untuk mengontrol pengetahuan mana yang boleh dipakai AI
• Konten situs yang dirayapi selalu publik - berasal dari situs publik Anda, jadi tidak ada yang perlu dibatasi; tag berlaku untuk item teks, berkas, dan API
• Tag pada item digabungkan dengan DAN - lihat Logika tag di atas; setiap tag item harus ada dalam bukti pengunjung
• Membuat ulang kunci membatalkan semua bukti lama - lakukan jika kunci mungkin bocor, lalu perbarui halaman agar menandatangani dengan yang baru
• Nama tag terserah Anda - hingga 20 per item, masing-masing 50 karakter, tanpa koma atau garis tegak; tidak pernah muncul di chat yang dilihat pengunjung