Hızlı Başlangıç

Widget Genel Bakışı

Widget uygulaması widget.companin.tech adresinde barındırılmakta ve web sitenize bir Müşteri Destek AI Ajanı gömmek için kolay bir yol sunmaktadır. Başlamak için bir ajan ve bir OAuth uygulaması oluşturmanız gerekecek.

Widget, web sitenizde izole bir iframe içinde çalışan hafif, kendi kendine yeterli bir uygulamadır. Bu mimari, widget'ın mevcut CSS veya JavaScript ile çelişmemesini sağlarken mükemmel performans ve güvenlik sunar.

1. Bir Ajan Oluşturun

Öncelikle, kontrol panelinizde bir Müşteri Destek AI Ajanı oluşturun:

Ajanınız, widget'ın arkasındaki AI beynidir. Kullanıcı mesajlarını işler, konuşma bağlamını korur ve akıllı yanıtlar üretir. Her ajan, kullanım durumunuza uygun belirli talimatlar, kişilik özellikleri ve bilgi tabanları ile özelleştirilebilir.

1. Kontrol panelinize gidin ve "Veri Kaynakları" sayfasına gidin
2. Ajanlar bölümünde "Ekle" butonuna tıklayın
3. Ajan detaylarını doldurun (isim, açıklama, ton, vb.)
4. Ajanı kaydedin ve ID'sini not edin

İpucu: Ajanınıza rolü ve sınırlamaları hakkında net, spesifik talimatlar verin. Örneğin: "Siz bir SaaS ürünü için yardımcı müşteri destek ajanısınız. Özellikler, fiyatlandırma ve hesap yönetimi hakkında soruları yanıtlayabilirsiniz. Teknik sorunlar için kullanıcıları bir destek bileti oluşturmaya yönlendirin."

2. Bir OAuth Uygulaması Oluşturun

Widget'ınızı kimlik doğrulamak için bir OAuth uygulaması oluşturun:

1. Kontrol panelinizdeki "OAuth" sayfasına gidin
2. "Uygulama Oluştur" butonuna tıklayın
3. Uygulama adını ve açıklamasını doldurun
4. Oluşturulan uygulamadan client_id'yi kopyalayın

3. Widget'ı Iframe ile Gömün

Widget'ı entegre etmenin en basit yolu, doğrudan bir iframe kullanarak gömmektir. Bu yöntem, JavaScript başlatma gerektirmeden çalışır ve kutudan çıkar çıkmaz çalışır. Bir sayfada birden fazla iframe için, her gömme işlemini kendi konteynerine ve parametrelerine göre ayarlayın.

<iframe src="https://widget.companin.tech/embed/session?key=YOUR_WIDGET_KEY&locale=en" style="border:none; width:100%; height:600px; border-radius:8px;" title="Customer Support AI Agent Widget"></iframe>

YOUR_WIDGET_KEY'yi widget'ınızın kurulum anahtarı ile değiştirin (widget sayfasından veya kontrol panelindeki Kurulum sayfasından kopyalayın). locale parametresi, sitenizin diline uyacak şekilde ayarlanabilir.

Gelişmiş: JavaScript Başlatma

Tavsiye edilen entegrasyon yöntemi, otomatik boyutlandırma, yapılandırma yönetimi ve duyarlı davranış sağlayan JavaScript widget yükleyicimizi kullanmaktır.

Script Entegrasyonu

HTML sayfanıza aşağıdaki script etiketini ekleyin:

<script  src="https://widget.companin.tech/widget.js"  data-widget-key="YOUR_WIDGET_KEY"  data-instance-id="support-widget"  data-locale="en"  data-theme="system"  async></script>

Script Nitelikleri

Her nitelik, widget'ınızı yapılandırmada belirli bir amaca hizmet eder:

• data-widget-key: Widget'ınızın Widget ID'si - Çoğu kurulumın ihtiyaç duyduğu tek değer. İstemcinizi, ajanınızı ve yapılandırmanızı sunucu tarafında çözer, böylece bunları ayrı ayrı yapıştırmazsınız.

Aşağıdaki üç nitelik, data-widget-key için gelişmiş bir alternatiftir - belirli bir istemciyi, ajanı veya yapılandırmayı hedeflemeniz gereken çoklu örnek kurulumları için kullanın:

• data-client-id: OAuth istemci ID'niz - Bu, uygulamanızı API'mizle kimlik doğrulamak için kullanılır. Bunu uygulamanızın parolası olarak düşünün.
• data-agent-id: Ajanınızın UUID'si - Bu, hangi Müşteri Destek AI Ajanının konuşmaları yönettiğini tanımlar.
• data-config-id: Widget yapılandırmanızın UUID'si - Bu, widget'ınızın nasıl göründüğünü ve davrandığını (renkler, boyut, konum vb.) belirler.
• data-instance-id: Her widget örneği için benzersiz ID - Aynı sayfada birden fazla widget gömüldüğünde çakışmaları önlemek ve örnek başına API hedeflemeyi etkinleştirmek için gereklidir.
• data-custom-css: Kullanımdan kaldırıldı. Bu niteliği ayarlamak, bir konsol uyarısı kaydeder ve hiçbir etkisi yoktur. Bunun yerine, widget yapılandırmanızda custom_css'yi panoda ayarlayın — bu, yapılandırmadan yüklenir ve iframe'e otomatik olarak enjekte edilir.
• data-locale: Dil kodu (örneğin, "en", "es", "fr") - Widget'ın görüntüleme dilini ayarlar. Ajan, kullanıcıların yazdığı herhangi bir dilde yanıt vermeye devam edecektir.
• data-theme: Tema modu - light, dark veya system (ziyaretçinin cihazını takip eder). Widget'ın gösterdiği renk paletini (panonuzda yapılandırılmış) seçer. Kaydedilmiş varsayılanınızı kullanmak için bunu atlayın.
• data-dev: Geliştirme modu (localhost) için "true" olarak ayarlayın - Bunu yerel olarak test ederken kullanın. Üretim için kaldırın veya "false" olarak ayarlayın.

Widget otomatik olarak:

• Yapılandırmayı config ID'sinden alır
• Kendini yapılandırmadaki widget boyutlarına göre boyutlandırır
• Kapatılmış düğmeyi yapılandırma ayarlarına göre konumlandırır
• Yapılandırmanın start_open ayarına göre açık veya kapalı başlar.

Notlar

• Widget, yapılandırma ayarlarınıza göre kendi boyutunu otomatik olarak yönetir
• Çökmüş buton konumu, widget yapılandırması aracılığıyla özelleştirilebilir
• Widget, yapılandırmanızdan start_open ayarını dikkate alır
• Tüm stil ayarları (renkler, yazı tipleri, boyutlar) widget yapılandırması aracılığıyla kontrol edilir
• Widget, duyarlı davranış için postMessage iletişimini kullanır
• Geliştirme modu, localhost testleri için data-dev="true" ile etkinleştirilebilir
• Sunucu tarafı token değişimi için /api/v1/auth/widget-token kullanın ve istemci gizli anahtarını yalnızca sunucunuzda tutun.
• Widget'ı bir iframe içinde gömmeden önce ana kökeninizin (örneğin http://localhost:3000) OAuth allowed_origins'ine dahil edildiğinden emin olun.