> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supportly.com.tr/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget'ı Sitenize Kurun

> Supportly AI sohbet widget'ını tek bir betik etiketiyle sitenize ekleyin: embed kodu, parametreler, widget davranışı ve kurulum doğrulaması.

Supportly AI asistanını sitenize eklemek tek bir betik etiketinden ibarettir. Kurulum üç adımdan oluşur: public key'i alın, betik etiketini sitenize yerleştirin ve kurulumu doğrulayın.

## Kurulum adımları

**1. Public key'i alın**

Site kaydınız oluşturulurken size özel bir public key atanır. Anahtar `sp_pub_` ile başlar ve widget'ı sitenize bağlamak için kullanılır. Gizli bir bilgi değildir; herkese açık widget uçlarında tanımlayıcı görevi görür.

**2. Betik etiketini sitenize ekleyin**

Aşağıdaki kodu sitenizin ortak şablonuna ekleyin ve `data-supportly-id` değerini kendi public key'inizle değiştirin.

```html theme={null}
<script
  src="https://widget.supportly.com.tr/supportly-chat-widget.js"
  data-supportly-id="sp_pub_xxx"
  async
></script>
```

Betiği tüm sayfalarda göstermek istiyorsanız ortak bir şablon bölümüne yerleştirmeniz yeterlidir. Betik asenkron yüklendiği için sayfa açılışını engellemez.

**3. Kurulumu doğrulayın**

Panelde sitenizin kurulum akışını açın. Akış iki adımı izler: betik yükleme (`install_script`) ve doğrulama (`verify_widget`). Doğrulama çalıştığında sunucu sitenizi ziyaret eder ve kod içinde anahtarınızı bulursa kurulum `completed` durumuna geçer.

## Betik etiketi öğeleri

| Öğe | Zorunlu | Açıklama |
| - | - | - |
| `src` | Evet | Widget betiği adresi: `https://widget.supportly.com.tr/supportly-chat-widget.js` |
| `data-supportly-id` | Evet | Sitenizin public key'i (`sp_pub_` ile başlar). Eksikse widget başlamaz ve tarayıcı konsoluna hata yazılır. |
| `data-key`, `data-site-id`, `data-widget-id` | Hayır | Aynı işi görür; üç yedek adın herhangi biri varsa o okunur. |
| `data-api` / `data-api-base` | Hayır | API temel adresini değiştirir. Varsayılan kurulumda API istekleri `https://api.supportly.com.tr/api` altına gider. |
| `async` | Önerilir | Betik sayfa yüklemesini engellemeden çalışır. |

> [!NOTE]
>
> Widget şu yollarda kendini başlatmaz: `/checkout`, `/odeme`, `/payment` ve `/cart/checkout` ile başlayan sayfalar. Ödeme adımlarında sohbet penceresi görünmez.

## Widget davranışı

> [accordion] Yapılandırma yüklemesi
>
> Sayfa her açıldığında widget, `GET /api/widget/config/{publicKey}` çağrısıyla renk, metin ve konum ayarlarını indirir. Sunucu yanıt veremezse yerleşik yedek ayarlarla çalışmaya devam eder; yedek yanıtta `fallback_active: true` işareti vardır.

> [accordion] Yükleme zamanlaması
>
> `widgetLoadMode` iki değer alır: `after_page_load` (sayfa yüklendikten sonra açılır, gecikme süresi `widgetLoadDelaySeconds`) veya `eager` (hemen). Proaktif mesaj `proactiveDelaySeconds` süresinden sonra gösterilir; `autoOpenDelaySeconds` tanımlıysa pencere otomatik açılır.

> [accordion] Konuşma geçmişi
>
> İlk mesajdan sonra sunucu, site ve ziyaretçiye bağlı yedi gün geçerli bir konuşma token'ı üretir. Widget bu token ile `GET /api/widget/conversation` uç noktasından geçmişi okuyup sohbeti sayfalar arası sürdürür. Token olmadan geçmiş okunamaz.

> [accordion] Hassas veri kuralları
>
> Widget, sayfa URL'sini bilgi olarak gönderirken sorgu parametrelerini temizler: `token`, `key`, `secret`, `password`, `code`, `reset`, `auth`, `session`, `api_key` ve `access_token` değerleri silinir. Böylece sayfa adreslerinde taşınan gizli değerler sohbet isteklerine sızmaz.

> [accordion] Origin doğrulama
>
> Sitenizde izinli origin listesi (`allowed_origins`) tanımlıysa widget'ı başka sitelerde çalıştırmaya çalışan istekler `ORIGIN_DENIED` hatasıyla engellenir. Listede wildcard da geçerlidir, örn. `*.supportly.com.tr`. Liste boşsa origin doğrulaması yapılmaz ve widget her sitede açılır.

## Sorun giderme

> [accordion] Widget hiç görünmüyor
>
> 1. Tarayıcı konsolunu açın: `data-supportly-id eksik` uyarısı, anahtar özniteliğinin eksik veya boş olduğu anlamına gelir.
> 2. Public key'inizde yazım hatası olmadığını ve `sp_pub_` ile başladığını doğrulayın.
> 3. `<script>` etiketinin yayında gerçekten göründüğünden emin olun; bazı şablon motorları etiketleri bozabilir.

> [accordion] Doğrulama başarısız
>
> `WIDGET_NOT_FOUND` yanıtı, sunucunun sitenin kodunda anahtarınızı bulamadığı anlamına gelir; betik etiketini yeniden kontrol edin. `SITE_UNREACHABLE` yanıtı, sunucunun siteye hiç ulaşamadığı anlamına gelir; sitenin dışarıdan erişilebilir olduğundan emin olun.

> [accordion] ORIGIN\_DENIED hatası
>
> Sitenizde `allowed_origins` listesi tanımlıysa farklı bir domainde widget açılmaz. Bu sitenin kendi domainini listeye ekleyin veya liste kapsamını wildcard ile genişletin.

Widget görünümünü markanıza uydurmak için [Widget Özelleştirme](https://docs.supportly.com.tr/widget/ozellestirme) sayfasına, API istekleri için [API Temelleri](https://docs.supportly.com.tr/api/baslangic) sayfasına bakabilirsiniz.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.