RAQSKurulum & Entegrasyon
RAQS kurulumu: tek satır embed ile sesli asistan
RAQS'ı herhangi bir web sitesine eklemek tek bir <script> satırıyla başlar. Bu rehber, sesli asistanını sıfırdan canlıya almanın altı adımını anlatır: embed kodunu yapıştırmak, paneldeki siteni eklemek, bilgi tabanını oluşturmak, izinli domainleri belirlemek, maskot ile persona/ses seçmek ve son olarak konuşarak test etmek. Kod yazmaya, sunucu kurmaya veya yapay zeka altyapısı yönetmeye gerek yok — her şey yönetilen bulutta çalışır.
Adım 1 — Tek satır embed kodunu sitene yapıştır
Kurulum, sitenin her sayfasında çalışacak tek bir script etiketiyle başlar. Bu satırı sitenin <head> bölümüne (veya body kapanışından hemen önceye) yapıştırırsın. data-raqs özniteliği, paneldeki sitene ait benzersiz anahtardır; script bu anahtarla doğru bilgi tabanını ve ayarları yükler. Etiket async olduğu için sayfanın yüklenme hızını yavaşlatmaz; asistan arka planda hazırlanır ve hazır olunca orb veya 3D maskot olarak belirir.
WordPress, Shopify, Wix, Webflow veya kendi yazdığın HTML — fark etmez. Tema düzenleyicisinde 'özel kod / header script' alanı olan her platforma aynı satırı eklersin. Tek satır eklemenin güzel yanı, sitenin geri kalanına dokunmadan asistanı açıp kapatabilmen ve istediğin an anahtarı değiştirebilmendir.
Nereye eklenir
Tüm sayfalarda çalışsın diye <head> veya body sonu.
Site anahtarı
data-raqs panelden gelen benzersiz anahtardır.
async yükleme
Sayfa hızını etkilemez; arka planda hazırlanır.
Platform bağımsız
WordPress, Shopify, Webflow, ham HTML — hepsi.
<!-- RAQS sesli asistan — tek satır embed -->
<script async src="https://raqs.ai/v1/raqs.js"
data-raqs="SITE_ANAHTARINIZ"></script>Adım 2 — Paneldeki siteni ekle ve anahtarını al
Embed kodundaki SITE_ANAHTARINIZ değerini almak için panele giriş yapıp 'Site ekle' dersin. Sitenin adını ve ana adresini (örneğin https://magazam.com) girersin; RAQS bu site için bir kayıt ve benzersiz bir anahtar oluşturur. Bu anahtarı embed satırına yapıştırdığında script, hangi müşteriye ve hangi bilgi tabanına ait olduğunu bilir.
RAQS çok kiracılı bir mimaride çalışır: her sitenin verisi satır düzeyi güvenlik (row-level security) ile diğerlerinden tamamen izole edilir. Yani aynı panelde birden çok site yönetsen bile bir sitenin bilgi tabanı, konuşmaları ve ayarları asla başka bir siteye sızmaz. Panelde her site için ayrı bilgi tabanı, ayrı analitik ve ayrı ayarlar görürsün.
Site ekle
Ad + ana adres gir; anahtar otomatik oluşur.
Çok kiracılı
Her sitenin verisi RLS ile izole edilir.
Tek panel
Birden çok siteyi tek yerden yönet.
Adım 3 — Bilgi tabanını oluştur: sitende tara veya içerik yükle
RAQS asla uydurmaz; yalnızca senin verdiğin bilgi tabanından cevap verir ve içerikte yoksa açıkça 'bilmiyorum' der. Bu yüzden en kritik adım bilgi tabanını doldurmaktır. En hızlı yol site taramadır: panele sitenin adresini verirsin, RAQS sitemap'i ve sayfaları gezer. JavaScript ile render edilen tek sayfa uygulamalar (SPA) başlıksız kalmasın diye headless tarayıcıyla işlenir; metin trafilatura ile menü/footer gürültüsünden arındırılarak temiz çıkarılır. Crawler robots.txt kurallarına uyar ve SSRF korumalıdır; her plan için bir sayfa kotası vardır. Tarama derinliğini panelden ayarlar, dilediğinde yeniden tarama (re-crawl) başlatırsın.
Alternatif olarak ya da ek olarak içerik yapıştırabilir veya dosya yükleyebilirsin: PDF, Word, TXT, MD ve CSV desteklenir; sık sorulan soruları doğrudan metin olarak da girebilirsin. Hangi yöntemi seçersen seç, içerik parçalara ayrılır, Azure embeddings (text-embedding-3-small) ile vektöre çevrilir ve pgvector'da saklanır. E-ticaret sitelerinde ürün sayfalarındaki schema.org JSON-LD verisi (isim, marka, fiyat, stok, kategori) ayrıca çıkarılır — böylece ziyaretçi 'bu ürün stokta mı, kaç para?' diye sorduğunda doğru yanıt alır.
Site tarama
Sitemap + sayfalar; SPA için headless render.
Dosya & metin
PDF, Word, TXT, MD, CSV veya doğrudan SSS.
Temiz çıkarım
trafilatura ile menü/footer gürültüsü temizlenir.
Ürün verisi
JSON-LD'den fiyat/stok/marka/kategori.
Adım 4 — İzinli domainleri belirle (allowlist)
Asistanının yalnızca senin sitende çalışmasını istersin — başka birinin anahtarını kopyalayıp kendi sitesinde kullanmasını değil. Panelde izinli domain listesi (origin allowlist) tanımlarsın: RAQS sadece bu domainlerden gelen istekleri kabul eder. Bu, hem kullanımı senin sitelerinle sınırlar hem de kötüye kullanımı engeller.
İzinli domain listesinin yanında Cloudflare Turnstile anti-abuse koruması da devrededir; bu, otomatik botların asistanı suistimal etmesini önler. Altyapı Azure'un Avrupa bölgesinde barındırılır ve KVKK ile GDPR uyumludur. Geliştirme yaparken localhost gibi adresleri de listeye ekleyebilir, canlıya geçince üretim domainini bırakırsın.
Origin allowlist
Asistan yalnızca izinli domainlerde çalışır.
Anti-abuse
Cloudflare Turnstile bot suistimalini engeller.
Geliştirme + canlı
localhost ve üretim domainini ayrı yönet.
Adım 5 — Maskot, persona, ses ve adı seç
Asistanının görünümünü ve karakterini panelden tek tıkla belirlersin. Klasik dokun-konuş orb'unu kullanabilir ya da sayfada gezinen bir 3D maskot seçebilirsin: amiral gemisi geyik, evrensel 'Spark' kıvılcımı, stilize karakterler ve 30'dan fazla hayvan havuzundan biri. Maskot, sayfanın gerçek DOM elemanlarını zemin olarak görür; koşar, zıplar ve ziyaretçiyi doğru bölüme yönlendirir.
Karakterin yanında sesini, tonunu ve adını da ayarlarsın. Asistan Türkçe ve İngilizce konuşur; STT/TTS Azure Speech ile, beyin ise Azure OpenAI gpt-4o-mini üzerinde Pipecat pipeline'ı ile çalışır. Persona ayarı, asistanın markanın diliyle konuşmasını sağlar — resmi mi samimi mi, kısa mı detaylı mı, hangi isimle selam veriyor; hepsi senin elinde.
Maskot havuzu
Orb, geyik, Spark, karakterler + 30'dan fazla hayvan.
DOM zemini
Maskot sayfanın elemanlarında gezinip yönlendirir.
Ses & persona
Türkçe/İngilizce; ton, isim ve üslup ayarlanır.
Adım 6 — Konuşarak test et ve canlıya al
Son adım en keyiflisi: sitene gidip orb'a veya maskota dokun, mikrofona izin ver ve konuş. 'Şu ürün stokta mı?', 'İade politikanız nedir?' veya 'beni iletişim sayfasına götür' gibi gerçek sorular sor. Asistan, bilgi tabanından hibrit arama (anlamsal vektör + Postgres tam-metin anahtar kelime + RRF füzyon + benzerlik eşiği) ile yanıtı bulur, sesli cevaplar ve gerektiğinde seni doğru sayfaya yönlendirir veya 'bunu göster', 'sepete ekle' gibi aksiyonları tetikler.
Ödeme, hesap veya silme gibi hassas işlemler için asistan her zaman açık kullanıcı onayı ister — bu güvenlik katmanı varsayılan olarak devrededir. Test sırasında eksik gördüğün cevapları panelden bilgi tabanına ekler veya yeniden tarama yaparsın. Konuşmaları ve analitiği panelden izleyerek asistanını zamanla iyileştirirsin. Hazır olduğunda yapacak başka bir şey yok: embed satırı zaten canlı olduğu için asistan tüm ziyaretçilerine açıktır.
Gerçek sorularla dene
Stok, iade, yönlendirme — sesle test et.
Onay kalkanı
Ödeme/hesap/silme kullanıcı onayı ister.
İyileştir
Konuşmaları izle, eksik içeriği bilgi tabanına ekle.
Sık sorulan sorular
Sesli asistanı siteme nasıl eklerim?
Tek bir <script> satırını sitenin <head> bölümüne yapıştırır, panelden siteni ekleyip anahtarını embed koduna koyarsın. Sonra bilgi tabanını tarar ve dakikalar içinde canlıya alırsın.
Kurulum için kod bilgisi gerekir mi?
Hayır. Tek satır embed'i kopyala-yapıştır yeterli; geri kalan her şey (site ekleme, tarama, maskot seçimi) panelden tıklayarak yapılır.
Kurulum ne kadar sürer?
Embed satırı saniyeler alır. Sitenin boyutuna göre tarama biraz zaman alabilir ama tipik bir site dakikalar içinde sorulara yanıt verir hâle gelir.
Bilgi tabanını nasıl güncellerim?
Panelden istediğin an yeniden tarama (re-crawl) başlatır, yeni dosya yükler veya metin eklersin. Değişiklikler bilgi tabanına işlenir ve asistan güncel cevap verir.
Asistan yalnızca benim sitemde mi çalışır?
Evet. İzinli domain listesi (origin allowlist) ve Cloudflare Turnstile sayesinde asistan yalnızca senin belirlediğin domainlerde çalışır; başkası anahtarını kullanamaz.
Kuruluma başlayalım mı?
Tek satır kodla siteni ekle, içeriğini tarat ve dakikalar içinde konuşmaya başla.
Ücretsiz başla