Widget'ı Herhangi Bir Siteye Ekleyin

Tek bir <script> etiketi, widget'ınızı HTML ekleyebildiğiniz her siteye yerleştirir — bu sayfa o snippet'in tam referansıdır: tüm data-* öznitelikleri, ayrıca düz HTML siteleri, tek sayfa uygulamaları (SPA) ve Google Tag Manager için notlar.

Henüz bir widget oluşturmadıysanız Web Sitesi Widget'ları ile başlayın. Platforma özel adımlar için bkz. WordPress, Wix ve Shopify.

Snippet

Widget'ın Install ekranı, markalamanız gömülü olarak yapıştırmaya hazır bir snippet üretir. En sade haliyle:

<script src="https://api.bess-ai.com/embed.js"
        data-widget-id="bess_pk_live_XXXXXXXXXXXX"
        async></script>

Widget'ın görünmesini istediğiniz her sayfada, kapanış </body> etiketinden hemen önce yapıştırın. Tüm seçenekleriyle bir örnek:

<script src="https://api.bess-ai.com/embed.js"
        data-widget-id="bess_pk_live_XXXXXXXXXXXX"
        data-locale="tr"
        data-position="bl"
        data-accent="#0EA5E9"
        data-label="Asistanımızla konuşun"
        data-waves="0"
        async></script>

Nasıl çalışır: script, yalnızca yüzen başlatıcı düğmesini çizen minik bir yükleyicidir. Panelin kendisi — mikrofon izni, ses bağlantısı ve oturum dahil — ziyaretçi ilk kez tıkladığında bir iframe içinde tembel (lazy) olarak yüklenir; snippet sayfa ağırlığınıza neredeyse hiçbir şey eklemez. Sayfa başına tek snippet yeterlidir; aynı sayfadaki ikinci bir kopya yok sayılır.

not

Snippet'teki publishable key'in herkese açık olması güvenlidir — Stripe'ın pk_ anahtarı gibi, yalnızca bu widget'ın ajanı için oturum başlatabilir ve izin verilen domainleriniz, hız sınırlarınız, günlük limitleriniz ve kredi bakiyenizle sınırlıdır. Anahtarı kontrol panelinden döndürürseniz (rotate) snippet'i güncelleyin — eski anahtar anında çalışmayı durdurur.

Tüm data-* öznitelikleri

Öznitelik	Değerler	Varsayılan	Ne yapar
data-widget-id	bess_pk_live_…	— (zorunlu)	Install ekranındaki publishable key. Bu olmadan widget yüklenmez.
data-locale	tr, en	tr	Widget arayüzünün dili (düğme etiketleri, durum metinleri, varsayılan başlıklar).
data-position	br, bl	br	Başlatıcı balonunun köşesi: sağ alt veya sol alt.
data-accent	hex renk, ör. #0EA5E9	#C2A14E	Başlatıcı ve panel vurgu rengi — Install ekranı, kontrol panelindeki vurgu renginizi buraya gömer. Yalnızca hex (3–8 hane, # isteğe bağlı); diğer biçimler yok sayılır.
data-label	serbest metin	yok	Başlatıcının yanındaki metin etiketi (ör. "Asistanımızla konuşun"). Yalın düğme için boş bırakın.
data-waves	1, 0	1	Başlatıcının etrafındaki nabız halkası. Kapatmak için 0.
data-mode	voice, chat, hybrid	widget'ın modu	Bir hybrid widget'ı bu gömme için tek yüzeye sabitler. Widget'ın izin vermediği bir modu asla açmaz — platform, widget yapılandırmasını sunucu tarafında uygular.
data-title	serbest metin	widget markalaması	Yalnızca bu gömme için panel başlığını değiştirir.
data-subtitle	serbest metin	widget markalaması	Yalnızca bu gömme için panel alt başlığını değiştirir.
data-transcript	1, 0	1	Sesli paneldeki canlı transkripti gizlemek için 0.
data-page-tools	1, 0	0	Ajanın, sayfanızın kaydettiği araçları kullanmasına izin verir — bkz. Sayfa Araçları (Beta). Ayrıca kontrol panelinde widget'ın Allow page tools ayarı da gerekir.

Öznitelikler yalnızca üzerinde bulundukları gömmeyi etkiler — aynı widget birden fazla sitede farklı markalamayla yaşıyorsa kullanışlıdır. Kontrol panelinde yapılandırdığınız her şey (izin verilen domainler, limitler, hız sınırları, mod, rozet) özniteliklerden bağımsız olarak sunucu tarafında uygulanır.

Platform notları

• WordPress — kod gerektirmeyen yol resmi eklentidir: WordPress'e Kurulum. Eklenti olmadan, bir header/footer kod eklentisiyle (ör. WPCode) veya child theme'inizde </body> etiketinden hemen önce snippet'i site geneline yapıştırın.
• Wix — Settings → Custom Code, All pages + Body - end: Wix'e Kurulum. Bağlı domaini olan bir Premium site gerektirir.
• Shopify — layout/theme.liquid içinde </body> etiketinden hemen önce: Shopify'a Kurulum. Custom pixels kullanmayın — sandbox içinde çalışırlar ve widget'ı çizemezler.
• Google Tag Manager — GTM kullanan her platformda: snippet'i içeren bir Custom HTML etiketi oluşturun, All Pages tetikleyicisine bağlayın ve container'ı yayınlayın. Tıklama tıklama sürümü widget'ın Install ekranındadır.
• Düz HTML siteleri — snippet'i ortak footer include'unuza veya sayfa şablonunuza </body> öncesine yapıştırın ki her sayfada bulunsun.
• Diğer site kurucuları — widget'ın Install ekranı (Siteniz nerede?) daha fazla platform için adım adım talimat içerir. Genel sayfalarınızda çalışan bir HTML/script bloğu ekleyebildiğiniz her yerde aynı snippet çalışır.

Tek sayfa uygulamaları (React, Vue, Next.js, …)

Snippet'i uygulama kabuğunda (app shell) bir kez yükleyin — index.html'de veya kök layout/document bileşeninde — yönlendirilen (routed) bir sayfa bileşeninin içinde değil:

• Kabukta yüklendiğinde widget, istemci tarafı gezinmelerde hayatta kalır: ziyaretçi rotalar arasında dolaşırken konuşmaya veya sohbete devam edebilir.
• Bir rotanın içine yerleştirildiğinde başlatıcı yalnızca o rotada var olur ve her gezinmede yeniden yüklemek boşa iştir (yükleyici mükerrer eklemeleri yok sayar, ama onları oluşturmanın da bir anlamı yoktur).

Kendi sitemizde de böyle çalıştırıyoruz — bess-ai.com üzerindeki widget, oturumlar gezinmelerde kopmasın diye kabuğa bir kez yerleştirilmiştir.

Etiketi programatik olarak ekliyorsanız data-* özniteliklerini oluşturduğunuz öğeye kopyalamayı unutmayın:

const s = document.createElement("script");
s.src = "https://api.bess-ai.com/embed.js";
s.async = true;
s.setAttribute("data-widget-id", "bess_pk_live_XXXXXXXXXXXX");
document.body.appendChild(s);

Hiçbir şey görünmüyor mu?

1. Sayfanın domaini, kontrol panelinde widget'ın Allowed domains listesinde olmalı — eşleşen domaini olmayan widget hiçbir yerde görüntülenmez.
2. Widget kontrol panelinde Active (devre dışı değil) olmalı.
3. data-widget-id güncel anahtarla eşleşmeli — döndürülen bir anahtar eski snippet'leri anında geçersiz kılar.
4. Snippet sayfada gerçekten bulunmalı (sayfa kaynağını görüntüleyip embed.js arayın) — bazı site kurucuları kod değişikliklerini ancak siteyi yeniden yayınladığınızda uygular.

Snippet'i taşıyan herhangi bir sayfa yüklendiğinde, kontrol panelindeki Install ekranı otomatik olarak alan adınızda "widget algılandı" durumuna geçer.