JS SDK

Previous Next
SUPSIS JS SDK v2.0 ● Web Widget Entegrasyonu

Supsis JavaScript SDK Referansı

Web sitenize canlı destek sohbet balonunu entegre edin, kullanıcı verilerini senkronize edin, sohbet durumlarını uzaktan yönetin ve özel ziyaretçi niteliklerini dinamik olarak güncelleyin.

1. Entegrasyon Kurulumu

Web sitenize Supsis Sohbet Aracını (Widget) eklemek için, aşağıdaki kodu sitenizdeki her sayfanın en üstüne (<head> alanına) eklemeniz gerekmektedir.

💡 SDK Avantajları & Özellikleri:
  • SUPSIS SDK asenkron olarak yüklenir ve sayfa yüklenme hızını etkilemez.
  • Yalnızca sohbet aracının görünmesini istediğiniz sayfalara ekleyebilirsiniz.
  • Supsis SDK yüklendikten ve uygulama hazır olduktan sonra widget otomatik olarak görüntülenecektir.

Entegrasyon Kodu

<script>
  window.supsis = window.supsis || function () {
    (supsis.q = supsis.q || []).push(arguments);
  };
  supsis.l = +new Date;
</script>

<script
  src="https://SITE_DOMAIN_NAME.visitor.supsis.live/static/js/loader.js"
  type="text/javascript"
  async
  defer>
</script>
📌 Domain Yapılandırması: SITE_DOMAIN_NAME kısmı, Supsis'e kayıt olurken belirttiğiniz alan adı (domain name) ile değiştirilmelidir.
Eğer IdeaSoft altyapısından geldiyseniz, IdeaSoft alan adınız Supsis alan adınız olacaktır. (Örneğin: market71.supsis.live üzerinden giriş yapıyorsanız, SITE_DOMAIN_NAME=market71 olacaktır).

2. SYNC API (Senkron API) & Metod Karşılaştırması

SYNC API supsis. sözdizimi ile kullanılır. ASYNC API ise supsis() sözdizimi ile kullanılır. API metodları hem senkron hem de asenkron olarak çağrılabilir.

METOD SYNC API Kullanımı ASYNC API Kullanımı
Sohbet Ekranını Aç supsis("open") supsis.open()
Sohbet Balonunu Küçült supsis("minimize") supsis.minimize()
Sohbet Balonunu Gizle supsis("hide") supsis.hide()
Görüşmeyi Sonlandır supsis("closechat") supsis.closeChat()
Kullanıcı Verilerini Ayarla supsis("setUserData",{name:'Ali',email:'a@a.com'}) supsis.setUserData({name:'Ali',email:'a@a.com'})
Kullanıcı İletişim Özellikleri supsis("setContactProperty",{badget:'gold-member'}) supsis.setContactProperty({badget:'gold-member'})
Ziyaretçiyi VIP Yap supsis("setVisitorVip", false) supsis.setVisitorVip(false) 
supsis("ready", (supsis) => {
    // supsis'i bu kapsam içinde senkron olarak kullanabilirsiniz
    supsis.open();
    supsis.setUserData({ name: "Ali", email: "a@a.com" });
});

Veya SDK'yı senkron olarak yükleyebilir ve kodunuzu bu satırdan sonra çalıştırabilirsiniz:

⚠️ Performans Notu: Senkron yükleme, sitenizin yüklenme hızına küçük bir ek yük getirebilir. 
<script src="https://SITE_DOMAIN_ADINIZ.visitor.supsis.live/static/js/loader.js" type="text/javascript">
    supsis.open()
    supsis.setUserData({name:'Ali',email:'a@a.com'})
</script>

3. ASYNC API (Asenkron API) Metodları

Supsis SDK asenkron olarak yüklendiğinden, API çağrılarınız SDK yüklendikten sonra çalışacaktır.

Yapılandırma Sözdizimi:

supsis(API_FUNCTION_NAME, payload);
  • "API_FUNCTION_NAME" bir string'tir ve çalıştırılacak fonksiyon adını temsil eder (Eşdeğeri: supsis.open() ===> supsis("open")).
  • payload, çağırdığınız fonksiyon parametre gerektiriyorsa kullanılır.

Ziyaretçi Yönetim Metodları

// Müşteriyi VIP Yap (false = VIP değil, true = VIP)
supsis("setVisitorVip", false);

// Sohbet Balonunu Küçült
supsis("minimize");

// Sohbet Balonunu Gizle
supsis("hide");

// Sohbet Ekranını Aç
supsis("open");

// Görüşmeyi Sonlandır
supsis("closeChat");

// Departman Değiştir
supsis("department", "$DEPARTMENT_TITLE");

Departman Sebebi

* Departman başlık değerleri tüm dillerde aynı olmalıdır.

4. Ziyaretçi ve Giriş Formu Bilgilerini Güncelleme

Ziyaretçilerinizin kişisel bilgilerini, onlar sohbet balonuna tıklayıp destek istemeden önce Supsis SDK'ya iletirseniz, bilgileri otomatik olarak ayarlanacaktır. Müşterileriniz sisteminizdeki isim ve e-posta adresini kullanarak doğrudan sohbete başlayabilirler.

ℹ️ Bilgilendirme: Eğer kullanıcı verisi sağlanmazsa, sohbet Supsis Giriş Formu (Login Form) üzerinden toplanan bilgilerle başlar.

Varsayılan Giriş Formu İçin Bilgi Güncelleme

supsis("setUserData", {
    name: "Giriş yapan kullanıcının adı ve soyadı",
    email: "Giriş yapan kullanıcının e-posta adresi",
});

Özel Giriş Formu İçin Bilgi Güncelleme

  • Özel giriş formlarında zorunlu alanlar: name, email
  • Diğer alanları dilediğiniz gibi genişletebilirsiniz. Her alanın bir adı olmalıdır.

Örnek özel giriş formu alanları: (name, email, phone, identityNumber)

Özel Giriş Formu

supsis("setUserData", {
    name: "John Doe",
    email: "jonh.doe@gmail.com",
    phone: "5396829048",
    identityNumber: "13451123445",
});

5. Özel Kullanıcı Verilerini Güncelleme (User Contact Properties)

Panel üzerinden oluşturulan özel kullanıcı etiketi veya verilerini SDK üzerinden güncelleyebilirsiniz. Bu özellik müşteri canlı desteğe bağlandığında üyelik seviyesi veya müşteri segmentini görüntülemek için idealdir.

Örnek Senaryo: Üyelik Seviyesi (User Rank) Tanımlama

Müşterinizin üyelik seviyesini iletmek için öncelikle panelde User Rank adında bir etiket oluşturun:

User Rank Etiketi

Ardından bu User Rank etiketini müşteriye atamak için SDK içerisinden setContactProperty metodunu çalıştırın:

supsis("ready", (supsis) => {
    // Supsis hazır olduğunda olay (event) dinleniyor.
    // Üye (member) verisi web sitenizden alınıyor.
    const member = {
        badget: "gold_member",
    };
    supsis.setContactProperty({ badget: member.badget });
});

6. Automation SDK ile Programatik Toplu WhatsApp Gönderimi & Kuyruk Yönetimi

Supsis Otomasyon Kod Blokları (Automation SDK / JS Scripting) içerisinde supsis.whatsapp ve supsis.queue metodları ile toplu WhatsApp şablon gönderimlerini güvenli arka plan kuyruk yapısında çalıştırabilirsiniz.

Önemli SDK Metodları ve Kullanım Mantığı

  • Kanal ve Şablon Doğrulama: supsis.channel.get(channelId) ve supsis.whatsapp.getTemplate({ channelId, templateId }) ile kanal aktifliği ve şablon varlığı denetlenir.
  • Hedef Kitle Segmentasyonu: supsis.contact.searchV2({ filters, cursor }) ile belirli platform, etiket ve telefon numarasına sahip kişiler süzülür.
  • Arka Plan Kuyruğu (Fire-and-Forget): supsis.queue.add(fn, "queue_name") fonksiyonu ile supsis.whatsapp.sendTemplateMessage istekleri sıralı işleme alınarak API sınırları korunur.
  • Kuyruk Durumu İnceleme: supsis.queue.status("queue_name") ile işlenen, bekleyen ve kalan kuyruk istatistikleri raporlanır.

7. Automation SDK ile Evrensel Kişi Arama, Oluşturma & Çok Kanallı Mesajlaşma

Automation SDK (JS Kod Blokları) içerisinde WhatsApp, Instagram, Telegram ve Messenger alıcı kimliklerine göre kişi sorgulama, eksik kişileri otomatik oluşturma ve doğrudan contact.sendTextMessage, contact.sendImageMessage ve contact.sendAssetMessage ile mesaj iletimi gerçekleştirilebilir.

Önemli Metodlar

  • Çok Kanallı Kişi Arama: supsis.contact.get(contactId), supsis.contact.searchV2({ filters }) (WhatsApp/Telefon) veya supsis.contact.search({ groups }) (Instagram instagramUserId, Telegram telegramUserId, Messenger messengerUserId).
  • Otomatik Kişi Oluşturma: Bulunamayan alıcılar için supsis.contact.create({ platform, fullname, phone, channelIds }) ile yeni kart açılır.
  • Mesaj İletimi: contact.sendTextMessage({ from, text }), contact.sendImageMessage({ from, url, caption }) ve contact.sendAssetMessage({ from, url, assetType, filename }).
Toplu Mesaj API