README.md

metadata

title: CAPS04 FE REFACTOR
emoji: 🚀
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false

CAPS04 FE REFACTOR

A Syududu

Embed Widget — Integration Guide

RAG Hub menyediakan widget chat berbasis <iframe> yang dapat diintegrasikan ke situs web pihak ketiga manapun. Widget ini mendukung autentikasi berbasis API Key, kustomisasi tampilan penuh melalui query string, serta komunikasi dua arah dengan halaman induk melalui postMessage.

---

Table of Contents

1. Quick Start
2. Authentication
3. URL Parameters Reference
4. Theming & Customization
5. postMessage Events
6. Session Persistence
7. Full Integration Examples
8. Troubleshooting

---

1. Quick Start

Tambahkan <iframe> berikut ke halaman HTML Anda:

<iframe
  src="https://your-raghub-domain.com/embed?api_key=YOUR_API_KEY"
  width="420"
  height="680"
  style="border: none; border-radius: 16px;"
  allow="clipboard-write"
></iframe>

Ganti YOUR_API_KEY dengan API Key yang digenerate dari halaman Admin → API Keys.

---

2. Authentication

Widget menggunakan API Key untuk autentikasi. Saat pertama kali dimuat, widget menukar API Key dengan bearer token melalui endpoint /auth/login/api-key, lalu menyimpan token tersebut ke cookie browser selama 7 hari.

/embed?api_key=sk-xxxxxxxxxxxxxxxx

Selama cookie masih valid, widget tidak akan login ulang meski halaman di-refresh. Cookie otomatis dihapus setelah 7 hari atau jika browser cookie dibersihkan.

Token Resolution Priority

Widget menyelesaikan autentikasi dengan urutan berikut:

1. Cek cookie — jika token sudah tersimpan dan belum expired, langsung digunakan.
2. Cek parameter ?api_key di URL, tukar dengan token via API, simpan ke cookie.
3. Jika tidak ada keduanya → widget menampilkan pesan error autentikasi.

---

3. URL Parameters Reference

Semua konfigurasi dilakukan melalui query string pada URL src iframe.

3.1 Authentication

Parameter	Tipe	Keterangan
api_key	string	API Key dari Admin Panel. Widget otomatis login dan menyimpan token ke cookie.

3.2 Behavior

Parameter	Tipe	Default	Keterangan
course_id	string	—	Pra-pilih mata kuliah tertentu. Widget langsung menggunakan course ini tanpa perlu user memilih.
session_id	string	—	Buka riwayat sesi chat tertentu langsung saat widget dimuat.
user_name	string	User	Nama yang ditampilkan di greeting ("Good Morning, ..."). Jika tidak diisi, diambil dari data user saat login via api_key.

3.3 Appearance

Parameter	Tipe	Default	Keterangan
title	string	RAG Hub	Judul widget (tab browser & empty state).
subtitle	string	(default text)	Teks deskripsi di bawah judul pada empty state.

---

4. Theming & Customization

Semua warna dikustomisasi via query string. Format nilai warna: hex 3-digit (#fff) atau 6-digit (#ffffff), dengan atau tanpa # di depan.

Format radius: nilai numerik diikuti unit px atau rem (maks. 2 digit), contoh: 20px, 1rem.

Parameter	Default	Keterangan
primary	#2764eb	Warna utama — tombol kirim, avatar asisten, border composer.
primary_gradient	#ccdcff	Warna lembut primary — background avatar user & aksen gradient.
background	#ffffff	Background utama widget.
background_profile	#ffffff	Background bubble chat asisten dan composer.
text_primary	#0a0a0a	Warna teks utama.
text_secondary	#737373	Warna teks sekunder / placeholder.
border	#739af1	Warna border composer dan bubble.
danger	#ef4444	Warna aksi destruktif (tombol hapus sesi).
radius	20px	Border radius bubble chat dan composer.

Contoh URL dengan tema gelap:

/embed?api_key=YOUR_KEY
  &background=1a1a2e
  &background_profile=16213e
  &text_primary=e0e0e0
  &text_secondary=8892b0
  &primary=4f8ef7
  &primary_gradient=1e3a6e
  &border=2a3f6f
  &danger=ff6b6b
  &radius=16px

---

5. postMessage Events

Widget berkomunikasi dengan halaman induk melalui window.postMessage. Dengarkan event ini di halaman yang meng-embed iframe untuk mendapat notifikasi dari widget.

5.1 Events yang Dikirim Widget (Outbound)

Event type	Kapan dikirim
sevima-raghub:close	User menekan tombol ✕ di sudut kanan atas widget.

Contoh listener di halaman induk:

window.addEventListener('message', (event) => {
  // Selalu validasi origin di produksi
  if (event.origin !== 'https://your-raghub-domain.com') return;

  if (event.data?.type === 'sevima-raghub:close') {
    // Sembunyikan atau hancurkan iframe
    document.getElementById('raghub-iframe').style.display = 'none';
  }
});

---

6. Session Persistence

Widget menyimpan data sesi di cookie browser dengan masa berlaku 7 hari. Cookie diset pada domain RAG Hub (domain iframe), sehingga tidak dapat diakses oleh halaman induk.

Cookie name	Isi	TTL
sevima_raghub_embed_token	Bearer token aktif.	7 hari
sevima_raghub_embed_user	Objek user JSON (id, name, email, role).	7 hari

Selama cookie masih valid, widget tidak akan memanggil ulang /auth/login/api-key meski halaman di-refresh atau tab ditutup lalu dibuka kembali.

Untuk memaksa login ulang (reset sesi), reload iframe dengan mengganti src — cookie lama akan diabaikan saat API Key baru ditukar.

---

7. Full Integration Examples

7.1 Embed Sederhana

<!DOCTYPE html>
<html lang="id">
<head>
  <meta charset="UTF-8" />
  <title>My App</title>
</head>
<body>

  <iframe
    id="raghub-widget"
    src="https://your-raghub-domain.com/embed?api_key=sk-xxxx&user_name=Budi&title=Asisten+Akademik"
    width="420"
    height="680"
    style="border: none; border-radius: 20px; box-shadow: 0 8px 32px rgba(0,0,0,0.15);"
    allow="clipboard-write"
  ></iframe>

  <script>
    window.addEventListener('message', (event) => {
      if (event.origin !== 'https://your-raghub-domain.com') return;
      if (event.data?.type === 'sevima-raghub:close') {
        document.getElementById('raghub-widget').style.display = 'none';
      }
    });
  </script>

</body>
</html>

7.2 Floating Chat Button

<style>
  #raghub-fab {
    position: fixed;
    bottom: 24px;
    right: 24px;
    width: 56px;
    height: 56px;
    border-radius: 50%;
    background: #2764eb;
    border: none;
    cursor: pointer;
    color: #fff;
    font-size: 24px;
    box-shadow: 0 4px 16px rgba(39,100,235,0.4);
    z-index: 1000;
  }

  #raghub-container {
    display: none;
    position: fixed;
    bottom: 96px;
    right: 24px;
    width: 420px;
    height: 680px;
    z-index: 1000;
    border-radius: 20px;
    overflow: hidden;
    box-shadow: 0 12px 48px rgba(0,0,0,0.2);
  }

  #raghub-container iframe {
    width: 100%;
    height: 100%;
    border: none;
  }
</style>

<button id="raghub-fab" onclick="toggleWidget()">💬</button>

<div id="raghub-container">
  <iframe
    id="raghub-iframe"
    src="https://your-raghub-domain.com/embed?api_key=sk-xxxx&primary=2764eb&radius=16px"
    allow="clipboard-write"
  ></iframe>
</div>

<script>
  function toggleWidget() {
    const container = document.getElementById('raghub-container');
    container.style.display = container.style.display === 'none' ? 'block' : 'none';
  }

  window.addEventListener('message', (event) => {
    if (event.origin !== 'https://your-raghub-domain.com') return;
    if (event.data?.type === 'sevima-raghub:close') {
      document.getElementById('raghub-container').style.display = 'none';
    }
  });
</script>

7.3 Pra-pilih Mata Kuliah & Langsung ke Sesi Tertentu

<iframe
  src="https://your-raghub-domain.com/embed
    ?api_key=sk-xxxx
    &course_id=COURSE_UUID
    &session_id=SESSION_UUID
    &user_name=Mahasiswa+A"
  width="420"
  height="680"
  style="border: none; border-radius: 20px;"
></iframe>

---

8. Troubleshooting

Widget menampilkan "Token iframe tidak tersedia"

Pastikan parameter ?api_key= ada di URL src iframe dan API Key tersebut masih aktif serta belum direvoke di Admin Panel.

Jika cookie lama ada tapi sudah expired, hapus cookie sevima_raghub_embed_token dari browser lalu reload.

Mata kuliah tidak muncul di dropdown

Pastikan akun yang terkait dengan api_key memiliki akses ke setidaknya satu course. Periksa di Admin Panel bahwa course sudah berstatus active.

Widget tidak merespons tombol ✕ di halaman induk

Pastikan listener message event sudah terpasang sebelum iframe dimuat, dan validasi event.origin sesuai domain RAG Hub.

Token expired di tengah sesi

Widget tidak melakukan refresh token otomatis. Jika token expired, cukup reload iframe — widget akan menukar api_key yang sama dengan token baru dan menyimpannya ke cookie:

const iframe = document.getElementById('raghub-iframe');
iframe.src = iframe.src; // trigger reload

Warna tidak berubah setelah mengubah query string

Pastikan nilai warna dalam format hex yang valid: 3 atau 6 digit, dengan atau tanpa #. Karakter selain 0-9 dan a-f akan diabaikan dan diganti nilai default.

---