Web SDK

Web SDK'sı hiçbir bağımlılığı olmayan tek bir JavaScript dosyasıdır. Sitenizin neyle inşa edildiğini önemsemez ve Flutter SDK'sı ile aynı protokolü konuşur: aynı bileşenler, yönetim panelindeki aynı aksiyonlar, aynı persona. Yönetim panelindeki tek bir uygulama, aynı anahtarla hem mobil uygulamanıza hem de web sitenize hizmet verebilir.

Yapay zekâ ile kurulum onu ekler: yapay zekâ kodlama aracınız etiketi her sayfaya yerleştirir, girişi bağlar, ekranları kaydeder ve yönetim panelini doldurur. Bu sayfa, daha sonra değiştireceğiniz durumlar için bunun sitenizde ne bıraktığını ve SDK'nın nasıl davrandığını açıklar. Canlı anahtar, uygulama canlıya geçtiğinde çalışır; kurulum, kontrolleri geçtiğinde bunu kendiliğinden yapar; o zamana kadar app_not_live ile reddedilir ve site test anahtarı üzerinde çalışır.

Bunlardan herhangi birini değiştirmek için bir görevden başlayın: her biri yapay zekâ kodlama aracınıza yönelik istemle açılır. Bu sayfa, söz konusu istemin dayandığı temeli oluşturur.

Etiket

<!-- Inside <head>, on every page. Swap in the live key when the site goes live.
     data-app-key: your app's key — Rendel console → Settings → Keys & environments → Copy.
     data-languages: "tr" Turkish only, "tr,en" Turkish or English,
     "en" English only. Leave it out to answer in whatever the visitor writes. -->
<script
  src="https://rendel.ai/sdk/web/0.27.0/rendel.js"
  data-app-key="rd_pk_test_…"
  data-languages="tr"
></script>

Her sayfada <head> içinde yer alır; Next.js'te kök düzendeki strategy="beforeInteractive" özelliğine sahip bir <Script> bileşenidir. Etiket ayrıca data-locale ve data-api-base-url değerlerini de okur; data-launcher="false" ise Rendel'i açan köşe butonunu gizler.

Sabitleme

Sürüm adreste yer alır. Bir sonraki sürüm yayınlandıktan sonra da 0.27.0 sürümü 0.27.0 olarak kalır; böylece siteniz yalnızca siz numarayı değiştirdiğinizde değişir. Değişiklik günlüğü, her sürümün ne getirdiğini belirtir.

Giriş yapan kullanıcı

// Right after your sign-in succeeds:
Rendel.identify({ userId: user.id });

// On every page: the signed-in person's current token, or null, so
// Rendel can reach your API as them — no API key.
Rendel.setUserToken(() => getAccessToken());

// When the user signs out:
Rendel.reset();

setUserToken, bir API anahtarı vermeye gerek kalmadan Rendel'in kendi API'nizden — “siparişim”, “rutinim” — soruyu soran kişi olarak yanıt vermesini sağlar: yönetim panelinde bu uç noktalar giriş yapmış kullanıcının belirteci olarak ayarlanır. Fonksiyon her sorudan önce çağrılır; böylece geçerli belirteci (süresi dolmuşsa orada yenilenmiş olarak) veya kimse giriş yapmadığında null döndürür. Uç noktalarınıza Authorization: Bearer olarak iletilir, asla saklanmaz ve her kişi yalnızca kendi belirtecinin açtığı verilere erişir. Yüklemeler arasında bir fonksiyon hatırlanamayacağı için her sayfada çağrılır.

Bir şeyi değiştiren uç nokta — “bana salı gününe randevu al” — önce bir onay kartında sorulur. Kişi onayladıktan sonra Rendel çağrıyı onun adına yapar ve ne olduğunu yanıtlar; sayfada yazılacak herhangi bir işleyici yoktur.

userId, kendi arka ucunuzun kişiyi tanıdığı kimliktir; mobil uygulamanızın ilettiğiyle aynıdır, bu sayede bir kişinin her ikisinde de tek bir geçmişi olur. SDK, sayfa yüklemeleri ve ziyaretler boyunca bu kişiyi hatırlar; dolayısıyla geri dönen bir ziyaretçi için ikinci bir çağrıya gerek kalmaz. traits ({ plan: "pro" }), Rendel'in onlar hakkında bilmesi gereken her şeyi taşır ve kimlik doğrulama açık olduğunda userHmac gerekir.

Bunlar olmadan her ziyaretçi anonimdir ve sohbetleri tarayıcıya aittir. Giriş yapılmayan bir site için doğru varsayılan budur.

Sohbet, sekme içinde sayfadan sayfaya ziyaretçiyi takip eder: sitenizin başka bir sayfasına giden bir bağlantı sohbeti baştan başlatmaz.

İzin verilen alan adları

Test anahtarı localhost ve 127.0.0.1 üzerinde, herhangi bir bağlantı noktasında doğrudan çalışır. Site canlıya geçmeden önce alan adını yönetim panelinde Settings → Security → Allowed domains altından ekleyin. Bir web sayfasındaki anahtarı kaynağını açan herkes okuyabilir; listenin amacı anahtarın onların sitesinde çalışmasını engellemektir. Alan adı listelenene kadar canlı anahtar söz konusu siteye origin_not_allowed ile yanıt verir.

musteri.com, https://musteri.com anlamına gelir. www.musteri.com ayrı bir kayıttır ve *.musteri.com tüm alt alan adlarını kapsar. Mobil uygulamalarınız alan adı göndermez ve bu listeden etkilenmez.

Karanlık mod

Varsayılan themeMode: "system" ile panel önce sayfanızı, ardından tarayıcıyı takip eder: çoğu sitenin kendi görünüm anahtarlarının ayarladığı <html> (veya <body>) üzerindeki bir data-theme="light" ya da data-theme="dark" değeri ve bu yoksa ziyaretçinin prefers-color-scheme tercihi. Her ikisi de izlenir, bu nedenle bir değişiklik paneli yeniden çizer. "light" veya "dark" kesindir ve Rendel.setThemeMode(...) sayfa çalışırken modu değiştirir. Karanlık renkler darkTheme'dir veya belirtilmediğinde theme üzerinden türetilir; bkz. Markanızı kataloğa eşleme.

İzinler

Hiçbir dosyaya bir şey eklemenize gerek yoktur. “+” simgesi, tarayıcının kendi dosya seçicisini açan Fotoğraflar ve Dosyalar'ı (resimler; PDF'ler ve metin dosyaları) ve ilk kez kullanıldığında tarayıcının ziyaretçiden izin istediği Kamera'yı sunar. Mikrofon, tarayıcının konuşma tanıma özelliğini kullanır — ilk basıldığında tarayıcı ziyaretçiden mikrofon izni ister. Ses modunu açar: ziyaretçinin söyledikleri, konuştukça panelin ortasında yazılır ve konuşmayı bıraktığında kendiliğinden gönderilir.

• Mikrofon https gerektirir (localhost geçerlidir). Firefox'ta konuşma tanıma özelliği yoktur, bu nedenle orada gösterilmez; diğer her şey çalışır.
• Bir <iframe> içinde çerçevenin allow="microphone; camera" iznine ihtiyacı vardır.
• Siteniz bir Content-Security-Policy gönderiyorsa direktiflerine şu kaynakları ekleyin:

script-src https://rendel.ai;
connect-src https://api.rendel.ai https://tiles.openfreemap.org;
img-src https: blob:;
worker-src blob:;

tiles.openfreemap.org ve worker-src blob:, map bloğu içindir (0.20.0 ve sonrası). Harita motoru, rendel.js'in yanındaki rendel.ai adresinden yüklenir ve bir tarayıcı başka bir kaynaktan worker başlatmayacağı için worker'ını bir blob: URL'sinden çalıştırır. Politikanız style-src veya default-src de tanımlıyorsa haritanın stil sayfası için oraya https://rendel.ai adresini ekleyin. img-src içindeki blob: ise fotoğraf önizlemeleri ve logonuz içindir.

Actions

Yönetim panelinde bağladığınız aksiyonlar sunucularımızda çalışır ve web sitesinde kod gerektirmeden çalışır. Giriş yapmış ziyaretçi olarak sayfa içinde çalışması gereken bir aksiyon, Flutter SDK'sının kaydettiği şekilde kaydedilir:

Rendel.registerAction({
  name: "get_order_status",
  description: "Fetch the delivery status of an order",
  params: {
    type: "object",
    properties: { order_id: { type: "string" } },
    required: ["order_id"],
  },
  risk: "read",
  handler: async ({ order_id }) => {
    const response = await fetch(`/api/orders/${order_id}`);
    return response.json();
  },
});

params JSON Schema biçimindedir. Rendel'in bilmesi gerekenleri döndürün veya başarısız olduğunu belirtmek için hata fırlatın; sonucu 16 KB'ın altında tutun. write ve destructive aksiyonları telefondaki gibi sunucunun oluşturduğu aynı onay kartını alır ve confirmTemplate bunu metne döker.

İki alan daha bu kartı şekillendirir:

• editable: ["quantity"], ziyaretçinin onaylamadan önce kart üzerinde değiştirebileceği parametreleri adlandırır. Sunucu, değişen bir değeri modelinkini denetlediği gibi denetler ve kartı bununla yeniden çizer. Bunu bir adet, bir not veya birkaç seçenekten biri için kullanın; asla bir kimlik veya uygulamanızın hesapladığı bir tutar için kullanmayın. En fazla on iki adet. Bkz. Kullanıcının kart üzerinde değiştirebileceği değerler.
• undoable: true, paketlenirken iptal edilebilen bir sipariş gibi ziyaretçinin sonradan geri alabileceği destructive bir aksiyon içindir: kartında “Bu işlem geri alınamaz” yazmaz.
• Bir parametrenin title alanı kart üzerindeki satırını etiketler ve titles bu etiketi dil bazında verir ({ tr: "Adet" }), confirmTemplates gibi seçilir. Bkz. Bölgesel ayarlar.

Rendel.registerAction({
  name: "add_to_cart",
  description: "Add a product to the cart",
  params: {
    type: "object",
    properties: {
      product_id: { type: "string" },
      quantity: { type: "integer", minimum: 1, maximum: 10, title: "Quantity", titles: { tr: "Adet" } },
    },
    required: ["product_id", "quantity"],
  },
  risk: "write",
  confirmTemplate: "Add {quantity} to your cart?",
  editable: ["quantity"],
  handler: async (params) => cart.add(params),
});

Ekranlar

Rendel'in bir screens kartında sunabileceği sitenize ait bir ekran:

Rendel.registerRoute({
  name: "order_detail",
  title: "My orders › Order",
  description: "One order: its items, delivery and payment.",
  params: { order_id: { type: "string", required: true, fromActions: true } },
  open: ({ order_id }) => router.push(`/orders/${order_id}`),
});

Dokunulduğunda panel küçülerek bir balona dönüşür ve open çağrılır. Balon paneli geri getirir. bubbleOffset (px; telefon genişliğindeki bir sayfada 104, aksi takdirde 24) balonu kendi alt çubuğunuzun üzerinde tutar.

0.15.0 sürümünden itibaren. fromActions olarak işaretlenen bir parametre, bu sohbette aksiyonlarınızdan birinin döndürdüğü bir değere eşit olmalıdır. Adlar snake_case biçimindedir; başlık 1–60 karakter, açıklama en fazla 300 karakterdir; en fazla 8 parametre ve 50 rota tanımlanabilir.

Seçenekler

Veri öznitelikleri yaygın senaryoları kapsar. Geri kalanı için etiketten data-app-key özniteliğini çıkarın ve init fonksiyonunu kendiniz çağırın:

Rendel.init({
  appKey: "rd_pk_test_…",
  languages: ["tr"],
  assistantName: "Pati",
  suggestions: ["Milo bugün nasıl?", "Aşı takvimini göster"],
  launcher: false, // your own button: Rendel.open()
});

Yönetim panelinden yayınlanan Appearance ve açılış yüzeyi, yeni bir sürüm yayınlamaya gerek kalmadan hem web sitesinde hem de uygulamada bunları geçersiz kılar.

Rendel.on("opened" | "closed" | "messageSent" | "actionExecuted", fn) olan bitene abone olur; Rendel.deviceId, bir destek talebinde belirtilecek anonim kimliktir. Rendel.isOpen, Rendel.isInitialized ve Rendel.version durumu bildirir. Rendel.refreshConfig() yayınlanan görünümü yeniden okur. Rendel.pair(code) bir test tarayıcısını yönetim paneliyle eşleştirir (Bir test uygulamasını eşleme).

Log kodları

record.code içinde onLog fonksiyonunun aldığı değerler. Kod kararlıdır ve switch ile kontrol edilmesi güvenlidir; message insanlar içindir ve yeniden ifade edilebilir.

Sunucunun hatayla sonlandırdığı bir tur, söz konusu hatanın kendi kodu altında günlüğe kaydedilir (bkz. Hatalar). Anahtar olmayan bir anahtar, onLog ne olursa olsun tarayıcı konsolunda invalid_key olarak bildirilir, çünkü Rendel başlatılmaz.

TypeScript

Tipler dosyanın yanında yayınlanır. rendel.d.ts dosyasını kaynaklarınızın içine kaydedin; window.Rendel tiplenmiş olur.