Uygulamanızın verisi.
Kullanıcınızın yetkisi.

01Nasıl çalışır?

1. Script, genel sitelerdekiyle aynıdır. Sayfa açıldığında uygulamanızın /context ucundan giriş yapan kullanıcının takma adını ve izinli araçlarını alır.
2. Kullanıcı bir soru sorduğunda Dijital Asistan soruyu anlar ve hangi aracın hangi parametrelerle çalışacağını söyler (ör. borc, A blok 7).
3. Script bu çağrıyı uygulamanızın /run ucuna, kullanıcının kendi oturumuyla gönderir. Uygulamanız yetkiyi kontrol eder ve sonucu döner; sonuç kullanıcının ekranında gösterilir. Kayıt Dijital Asistan sunucusuna gelmez.
4. Genel sorular (kullanım, mevzuat, sık sorulanlar) asistanın kaynaklarından cevaplanır.
5. Asistan "Hangi daire?" diye sorarsa kullanıcının sonraki cevabı ('a blok daire 7') o soruyla birleştirilir.

02Kurulum adımları

1. Panelde "Uygulama paneli" türünde bir asistan oluşturun.
2. Kurulum sekmesinde uygulamanızın adresini yazın; oluşan script'i giriş sonrası sayfaların ortak yerleşimine ekleyin. Sayfa bir kez açıldığında kurulum kendini doğrular.
3. Aynı yerde veri ucunun yolunu yazın ve gizli anahtar oluşturun; anahtarı uygulamanızın ortam değişkenine kaydedin.
4. Uygulamanıza /context ve /run uçlarını ekleyin (aşağıdaki örnek).
5. Asistanı yayınlayın, giriş yapıp bir kayıt sorusu ve bir genel soru sorarak deneyin.

031. Script

Giriş sonrası tüm sayfalarda bir kez yüklenir. Kurulum kimliği ve doğrulama kodu Kurulum sekmesinden kopyalanır.

<script src="https://asistan.tasci.cloud/embed.js"
        data-installation="<kurulum-id>" data-verification="<kod>" defer></script>

042. /context: kim ve hangi araçlar

Takma ad, gizli anahtarınızla üretilir; kim olduğunu bize söylemez, konuşma geçmişini kullanıcıya bağlar. İmza, oturumun gerçekten giriş yapmış bir kullanıcıya ait olduğunu kanıtlar. Araç listesi kullanıcının rolüne göre değişir; yeni bir veri türü açmak için listeye bir araç ekleyin.

DA_SECRET=das_…   # Kurulum sekmesi → Uygulama verisi → Gizli anahtar

// POST /api/dijital-asistan/context — kullanıcı giriş yapmamışsa 401
import { createHmac } from "node:crypto";
const sign = (text) => createHmac("sha256", process.env.DA_SECRET).update(text).digest("base64url");

app.post("/api/dijital-asistan/context", requireLogin, (req, res) => {
  const subject = sign(req.user.tenantId + ":" + req.user.id);      // takma ad
  const expires = Date.now() + 10 * 60 * 1000;                      // en çok 1 saat
  res.json({
    version: 1, subject, expires, locale: "tr",
    signature: sign("dijital-asistan:v1:" + subject + ":" + expires),
    tools: [                                                         // yalnız bu kullanıcının izinli araçları
      { name: "borc", title: "Borç durumu", keywords: ["borç", "bakiye", "aidat"], params: { unit: "unit" } },
      { name: "takvim", title: "Takvim", keywords: ["takvim", "toplantı"], params: { period: "period" } },
    ],
    screens: [{ title: "Borçlar", href: "/panel/borclar", keywords: ["borç", "tahsilat"] }],
  });
});

053. /run: aracı çalıştırın

Script, Dijital Asistan'ın planladığı çağrıyı bu uca gönderir. Planı güvenilmez kabul edin: aracın kullanıcıya açık olduğunu ve kaydı görebildiğini her çağrıda kontrol edin. Değerleri biçimlenmiş metin olarak dönün (para birimi, tarih).

// POST /api/dijital-asistan/run — her çağrıda yetkiyi yeniden kontrol edin
app.post("/api/dijital-asistan/run", requireLogin, async (req, res) => {
  const { tool, args } = req.body;
  if (tool === "borc") {
    const units = await findUnits(req.user, args.unit);              // { block, number, name, id }
    if (!units.length) return res.json({ kind: "empty", message: "Kayıt bulunamadı." });
    if (units.length > 1) return res.json({ kind: "choose", message: "Hangisi?",
      options: units.map(u => ({ label: u.label, args: { unit: { id: u.id } } })) });
    const debt = await balance(req.user, units[0].id);
    return res.json({ kind: "result", title: units[0].label,
      fields: [{ label: "Kalan borç", value: money(debt.total) }],
      links: [{ label: "Borç dökümü", href: "/panel/borclar?daire=" + units[0].id }] });
  }
  res.status(404).json({ error: { message: "Bu araç yok." } });
});

06İçerik güvenlik politikası (CSP)

Uygulamanız CSP kullanıyorsa Dijital Asistan adresine şu yönergelerde izin verin:

script-src  … https://asistan.tasci.cloud
style-src   … https://asistan.tasci.cloud
connect-src … https://asistan.tasci.cloud
frame-src   … https://asistan.tasci.cloud

07Güvenlik

• Uygulama kayıtları kullanıcının tarayıcısında gösterilir; Dijital Asistan sunucusuna gönderilmez ve konuşma kaydına yazılmaz.
• /run ve /context uçları yalnız aynı adresten, kullanıcının oturum çereziyle çağrılır; uygulamanızın mevcut korumaları geçerlidir.
• Özel asistan yalnız geçerli imzayla açılır; imza en çok 1 saat geçerlidir. Gizli anahtarı yenilediğinizde eskisi hemen geçersiz olur.
• Kullanıcı ya da site değişince takma ad değişir ve sohbet temizlenir.
• Konuşmaların saklanıp saklanmayacağına ve ne kadar saklanacağına siz karar verirsiniz (Konuşmalar sekmesi).

08Sık sorulanlar