Jetlink JavaScript SDK kullanım rehberi

Jetlink Web Messenger’ı web sitenize eklemek, görünümünü ve davranışlarını özelleştirmek, kullanıcı bilgilerini aktarmak ve proaktif mesajlar göstermek için JavaScript SDK’yı kullanabilirsiniz.

Bu rehber; kurulum, Messenger ayarları, dil seçimi, kullanıcı aktarımı, iletişim bilgisi toplama kuralları, SDK fonksiyonları, olaylar ve proaktif mesaj örneklerini kapsar. Kullanıcı bilgilerini aktarmak için mevcut doğrudan aktarım yöntemi ve yeni JWT doğrulama yöntemi ayrı ayrı açıklanır.

Önerilen yöntem: JWT ile kullanıcı doğrulama. Giriş yapmış kullanıcıların kimlik ve profil bilgilerini Jetlink’e aktarırken JWT kullanmanızı öneriyoruz. Sunucunuzda imzalanan JWT, tarayıcıdan gönderilen kullanıcı bilgilerinin değiştirilerek geçerli bir kimlik gibi kabul edilmesini önlemeye yardımcı olur. Doğrudan alan aktarımına göre daha güvenli olan bu yöntemi yeni entegrasyonlarda tercih edin; mevcut entegrasyonlarınız için de JWT’ye geçiş planlayın.

1. Kurulum ve kanal bilgileri

App ID ve App Token / App Key nereden alınır?

Jetlink panelinde Ayarlar → Web Messenger ekranını açın. Ekrana bu bağlantıdan da ulaşabilirsiniz. Üst bölümdeki listeden ilgili Web Messenger kanalını seçin ve Web Sitenize Kurun sekmesine geçin.

Kurulum kodundaki Jetlink.Init(...) çağrısının birinci parametresi App ID, ikinci parametresi kanalın kurulum anahtarıdır. README’de ikinci parametre YOUR-APP-TOKEN olarak gösterilir; bu rehberde YOUR_APP_KEY adıyla kullanılır. İki yer tutucuyu paneldeki ilgili değerlerle değiştirin.

Kurulum anahtarı ile JWT gizli anahtarı farklıdır. App ID ve App Key tarayıcıdaki kurulum kodunda kullanılır. JWT gizli anahtarı yalnızca sunucuda saklanır ve kullanıcı token’ını imzalamak için kullanılır.

Temel kurulum

Aşağıdaki kodu Messenger’ın görünmesini istediğiniz tüm sayfalarda kapanış </body> etiketinden önce ekleyin. Ortak sayfa şablonu kullanıyorsanız bu şablona bir kez ekleyebilirsiniz. Aynı sayfaya birden fazla Jetlink kurulum kodu koymayın.

<script type="text/javascript">
  var jetlinkScript = document.createElement("script");
  jetlinkScript.src = "https://public.jetlink.io/Sdk/Jetlink.js?j=" + Date.now() / 1000;
  jetlinkScript.onload = function () {
    // Görünüm, dil ve kural ayarlarını bu noktada yapın.
    Jetlink.Init("YOUR_APP_ID", "YOUR_APP_KEY");
  };
  document.head.appendChild(jetlinkScript);
</script>

SDK’ya ait özelleştirme kodları, script yüklendikten sonra onload içinde ve Jetlink.Init çağrısından önce yazılmalıdır. Kullanıcı bilgisi gönderilmeden başlatılan Messenger anonim ziyaretçiler için kullanılabilir.

2. Messenger görünüm ayarları

Aşağıdaki özellikler Jetlink.Options üzerinden tanımlanır. Tablodaki değerler örnektir; varsayılan değerler anlamına gelmez. Görsel URL’lerini kendi HTTPS adreslerinizle değiştirin.

Görünüm özelleştirme örneği

// SDK yüklendikten sonra, Jetlink.Init çağrısından önce:
Jetlink.Options.LauncherImageUrl = "https://example.com/chat-icon.png";
Jetlink.Options.LauncherType = "circular";
Jetlink.Options.LauncherStyleBehaviour = "custom";
Jetlink.Options.LauncherHeight = "100";
Jetlink.Options.LauncherWidth = "100";
Jetlink.Options.Height = "500";
Jetlink.Options.FontFamily = "Arial";
Jetlink.Options.MessageTextBoxPlaceholder = "Mesajınızı yazın...";
Jetlink.Options.ShowEmojiButton = true;
Jetlink.Options.ShowAttachmentButton = true;
Jetlink.Options.HeaderGeneralBackgroundColor = "#08052e";
Jetlink.Options.HeaderGeneralFontColor = "#ffffff";

3. Dil ayarları

SDK referansında Türkçe için tr, İngilizce için en dil kodları belgelenmiştir. Dil seçimini Jetlink.Init çağrısından önce yapın.

Jetlink.Options.Language = "tr"; // Türkçe
// İngilizce için: Jetlink.Options.Language = "en";

4. Kullanıcı bilgilerinin aktarılması: iki yöntem

Web sitenize giriş yapmış kullanıcının kimlik ve profil bilgilerini Jetlink’e iki farklı şekilde aktarabilirsiniz: doğrudan kullanıcı alanları göndererek veya sunucuda imzalanmış JWT göndererek. Her iki yaklaşımda da SDK’ya bilgi aktarmak için Jetlink.SetUser kullanılır; verinin kaynağı ve doğrulanma biçimi farklıdır.

Kullanıcı aktarımında JWT’yi tercih edin. Yalnızca tarayıcıdan gelen bir kullanıcı kimliğine güvenmek yerine, kullanıcının kimliğini kendi backend’inizde doğrulayın ve Jetlink’e imzalı JWT ile aktarın. Gizli anahtarın yalnızca sunucuda saklanması bu güvenlik modelinin temelidir.

4.1. Yöntem 1 — Kullanıcı bilgilerinin doğrudan aktarılması

Bu yöntem, Kullanıcıları JWT ile doğrula seçeneği kapalıyken kullanılır. Uygulamanızdaki mevcut kullanıcının bilgilerini aşağıdaki nesneyle iletebilirsiniz.

var user = {
  SourceUserId: "54355353534",
  Email: "user@example.com",
  Phone: "+905321231212",
  Name: "Ayşe",
  Surname: "Yılmaz"
};
Jetlink.SetUser(user);

Alan adları büyük/küçük harfe duyarlı biçimde örnekteki gibi yazılmalıdır. Gerçek uygulamada örnek değerleri giriş yapmış kullanıcının bilgileriyle değiştirin.

Doğrudan aktarım için tam kurulum örneği

<script type="text/javascript">
  var jetlinkScript = document.createElement("script");
  jetlinkScript.src = "https://public.jetlink.io/Sdk/Jetlink.js?j=" + Date.now() / 1000;
  jetlinkScript.onload = function () {
    Jetlink.SetUser({
      SourceUserId: "54355353534",
      Email: "user@example.com",
      Phone: "+905321231212",
      Name: "Ayşe",
      Surname: "Yılmaz"
    });
    Jetlink.Init("YOUR_APP_ID", "YOUR_APP_KEY");
  };
  document.head.appendChild(jetlinkScript);
</script>

Güvenlik farkı: Doğrudan aktarımda kullanıcı bilgileri tarayıcı tarafında değiştirilebilir. Bu yöntemde alanların iletilmiş olması, sunucu tarafından imzalanmış bir kimlik kanıtı anlamına gelmez. Giriş yapmış kullanıcıların güvenilir şekilde tanınması için JWT yöntemine geçmenizi öneriyoruz.

4.2. Yöntem 2 — JWT ile güvenli kullanıcı aktarımı (önerilen)

JWT yönteminde kullanıcı kimliği ve profil bilgileri sunucunuzda hazırlanır, Jetlink gizli anahtarıyla HS256 algoritması kullanılarak imzalanır ve tarayıcıya tek bir token olarak iletilir. Jetlink, geçerli token üzerinden kullanıcıyı tanır; JWT doğrulaması açıkken kullanıcı bilgilerini yalnızca token’dan alır.

1. Kullanıcı uygulamanızda oturum açar.
   
2. Backend’iniz oturumu doğrular ve kullanıcı kaydını okur.
   
3. Backend’iniz kullanıcı bilgilerini JWT gizli anahtarıyla imzalar ve sayfayı oluştururken token’ı script içine yerleştirir.
   
4. Tarayıcı hazır token’ı Jetlink.SetUser({ Jwt: token }) çağrısıyla gönderir.
   
5. Messenger, Jetlink.Init ile başlatılır.
   

Gizli anahtarı bilmeyen bir istemci, payload içindeki kullanıcı kimliğini veya profil bilgilerini değiştirerek geçerli imzayı koruyamaz. Bu nedenle JWT, doğrudan alan aktarımına göre daha güvenli bir yöntemdir. JWT imzası şifreleme değildir; token içeriği okunabilir.

4.2.1. JWT ayarlarına ve gizli anahtara erişim

1. Ayarlar → Web Messenger ekranında ilgili kanalı seçin.
   
2. Messenger’ı Özelleştirin → Kullanıcı Doğrulama (JWT) bölümünü açın.
   
3. Kullanıcıları JWT ile doğrula seçeneğini etkinleştirin.
   
4. JWT geçerlilik süresi alanından süreyi belirleyin.
   
5. JWT gizli anahtarı alanının yanındaki kopyalama simgesiyle anahtarı alın.
   
6. Anahtarı yalnızca backend’inizin gizli değer yönetimine ekleyin. Aşağıdaki örneklerde JETLINK_JWT_SECRET ortam değişkeninden okunur.
   

Geçerlilik seçenekleri: 5 dakika, 10 dakika, 15 dakika, 30 dakika, 1 saat, 12 saat, 1 gün, 7 gün ve 30 gün. iat değeri seçili süreden eski token’lar reddedilir. Her sayfa yüklemesinde veya uygulama oturumunda yeni token üretin.

JWT gizli anahtarını istemciye koymayın. Bu anahtar HTML, JavaScript paketi, mobil uygulama kodu veya tarayıcıya dönen API yanıtlarında bulunmamalıdır. Tarayıcıya yalnızca imzalanmış kullanıcı token’ı gönderilir.

JWT açıkken token göndermeyen ziyaretçiler Messenger’ı anonim olarak kullanır. JWT kapalıyken kullanıcı bilgileri doğrudan alanlarla gönderilebilir.

4.2.2. JWT payload alanları

user_id ve iat zorunludur. Diğer alanlar isteğe bağlıdır. Alan adlarını aşağıdaki yazımlarıyla kullanın.

{
  "user_id": "100001",
  "email": "john.doe@example.com",
  "phone": "905551112233",
  "name": "John",
  "surname": "Doe",
  "avatar_url": "https://example.com/avatar.png",
  "custom_fields": { "role": "customer", "department": "sales" },
  "iat": 1790860807
}

Bu JSON’daki iat yalnızca yapıyı göstermek içindir. Üretimde sabit bir zaman değeri kullanmayın; her yeni token’da güncel sunucu zamanını kullanın. JavaScript ile elle hesaplanacaksa Math.floor(Date.now() / 1000) gerekir; Date.now() tek başına milisaniye üretir.

Aynı kullanıcı için kalıcı bir user_id kullanın; sayfa açılışında rastgele kimlik üretmeyin. Kullanıcının tarayıcıdan gönderdiği kimlik veya profil alanlarını doğrulamadan imzalamayın. custom_fields içindeki rol gibi bilgiler uygulamanızdaki yetki kontrollerinin yerine geçmez.

Doğrudan aktarım alanlarının JWT karşılıkları

JWT ayrıca avatar_url, custom_fields ve zorunlu iat alanını içerir. Mevcut kullanıcınızın SourceUserId değerini JWT’de user_id alanına tutarlı biçimde taşıyın.

4.2.3. Sunucuda token üretimi

Node.js ve jsonwebtoken

Token üretimi yalnızca backend uygulamasında yapılır. Projenize jsonwebtoken paketini ekleyin:

npm install jsonwebtoken

Aşağıdaki fonksiyon, sunucunun doğruladığı kullanıcı kaydını alır. id, firstName gibi alanlar örnek uygulama modeline aittir; kendi veri modelinizle eşleştirin.

const jwt = require("jsonwebtoken");

const secret = process.env.JETLINK_JWT_SECRET;
if (!secret) {
  throw new Error("JETLINK_JWT_SECRET tanımlanmalıdır.");
}

function createJetlinkUserJwt(user) {
  if (user.id === undefined || user.id === null || String(user.id) === "") {
    throw new Error("Kullanıcı kimliği zorunludur.");
  }

  const payload = {
    user_id: String(user.id),
    email: user.email,
    phone: user.phone,
    name: user.firstName,
    surname: user.lastName,
    avatar_url: user.avatarUrl,
    custom_fields: {
      role: user.role,
      department: user.department
    }
  };

  // jsonwebtoken, iat alanını güncel zamanla otomatik ekler.
  return jwt.sign(payload, secret, { algorithm: "HS256" });
}

Panelden kopyalanan gizli anahtarı, metin değeri olarak kullanın. Anahtara kendiliğinizden Base64 veya hex çözümleme uygulamayın. Örnekte iat otomatik eklenir; noTimestamp: true kullanmayın.

Node.js — Token’ı sayfa oluşturulurken üretme

Aşağıdaki örnek, Express ve EJS kullanan mevcut bir uygulama içindir. requireAuthenticatedSession uygulamanızın oturum doğrulama middleware’ini, req.user ise backend tarafından doğrulanmış kullanıcı kaydını temsil eder. Bu parçaları mevcut uygulamanızdaki karşılıklarıyla kullanın.

Kullanıcı giriş yaptıktan sonra hesap sayfası sunucuda hazırlanırken token üretilir ve sayfa şablonuna aktarılır. Tarayıcının token almak için ayrıca bir API çağrısı yapması gerekmez.

// Mevcut Express uygulamasında, yukarıdaki createJetlinkUserJwt ile birlikte:
// EJS görünüm motorunun uygulamada yapılandırıldığı varsayılır.
app.get("/account", requireAuthenticatedSession, (req, res) => {
  if (!req.user) return res.redirect("/login");

  // Kullanıcıya özel HTML ortak önbelleklere yazılmamalıdır.
  res.set("Cache-Control", "private, no-store");

  const userJwt = createJetlinkUserJwt(req.user);
  return res.render("account", { userJwt });
});

C# / ASP.NET Core — JWT üretimi

Aşağıdaki örnek ASP.NET Core MVC uygulaması içindir. Node.js örneğiyle aynı alanları, HS256 imzasını ve saniye cinsinden iat değerini üretir. JWT paketini projenize ekleyin:

dotnet add package System.IdentityModel.Tokens.Jwt

Token üretimini sunucu tarafındaki bir yardımcı sınıfta tutabilirsiniz. JetlinkUser bu örneğe ait veri modelidir; uygulamanızdaki doğrulanmış kullanıcı kaydından doldurulur.

using System;
using System.Collections.Generic;
using System.IdentityModel.Tokens.Jwt;
using System.Text;
using Microsoft.IdentityModel.Tokens;

public sealed record JetlinkUser(
    string Id,
    string? Email = null,
    string? Phone = null,
    string? Name = null,
    string? Surname = null,
    string? AvatarUrl = null,
    Dictionary<string, object>? CustomFields = null);

public static class JetlinkTokenFactory
{
    public static string Create(JetlinkUser user, string secret)
    {
        if (string.IsNullOrWhiteSpace(user.Id))
            throw new ArgumentException("Kullanıcı kimliği zorunludur.");
        if (string.IsNullOrWhiteSpace(secret))
            throw new ArgumentException("JWT gizli anahtarı zorunludur.");

        // Panelden alınan anahtarın metin değerini kullanın.
        var signingKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes(secret));
        var credentials = new SigningCredentials(
            signingKey, SecurityAlgorithms.HmacSha256);

        var payload = new JwtPayload
        {
            ["user_id"] = user.Id,
            ["iat"] = DateTimeOffset.UtcNow.ToUnixTimeSeconds()
        };

        // Boş opsiyonel alanları göndermeyin.
        if (!string.IsNullOrWhiteSpace(user.Email)) payload["email"] = user.Email;
        if (!string.IsNullOrWhiteSpace(user.Phone)) payload["phone"] = user.Phone;
        if (!string.IsNullOrWhiteSpace(user.Name)) payload["name"] = user.Name;
        if (!string.IsNullOrWhiteSpace(user.Surname)) payload["surname"] = user.Surname;
        if (!string.IsNullOrWhiteSpace(user.AvatarUrl)) payload["avatar_url"] = user.AvatarUrl;
        if (user.CustomFields is { Count: > 0 })
            payload["custom_fields"] = user.CustomFields;

        var token = new JwtSecurityToken(new JwtHeader(credentials), payload);
        return new JwtSecurityTokenHandler().WriteToken(token);
    }
}

iat sayısal Unix zamanı, custom_fields ise JSON nesnesi olarak yazılır. Gizli anahtar Encoding.UTF8.GetBytes ile doğrudan metinden alınır; Base64 veya hex çözümleme uygulanmaz. Anahtarı Node.js örneğinde olduğu gibi JETLINK_JWT_SECRET ortam değişkeninde veya sunucunuzun gizli değer yönetiminde saklayın.

C# — Controller içinde üretim ve ViewModel’e aktarım

Bu örnekte mevcut ASP.NET Core kimlik doğrulamasının yapılandırıldığı varsayılır. [Authorize], sayfayı oturum açmış kullanıcılara sınırlar. Kullanıcı alanları doğrulanmış User claim’lerinden okunur; claim adlarını kendi kimlik sisteminize göre uyarlayın. Profil bilgileriniz veritabanında tutuluyorsa kaydı doğrulanmış kullanıcı kimliğiyle backend’de okuyarak modeli doldurun.

using System;
using System.Security.Claims;
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

public sealed class AccountPageViewModel
{
    public string UserJwt { get; init; } = string.Empty;
}

[Authorize]
public sealed class AccountController : Controller
{
    [ResponseCache(NoStore = true, Location = ResponseCacheLocation.None)]
    public IActionResult Index()
    {
        // Bu kimlik, mevcut kimlik doğrulama mekanizmanızdan gelir.
        var userId = User.FindFirst(ClaimTypes.NameIdentifier)?.Value;
        if (string.IsNullOrWhiteSpace(userId)) return Forbid();

        var secret = Environment.GetEnvironmentVariable("JETLINK_JWT_SECRET")
            ?? throw new InvalidOperationException("JETLINK_JWT_SECRET tanımlanmalıdır.");

        var user = new JetlinkUser(
            Id: userId,
            Email: User.FindFirst(ClaimTypes.Email)?.Value,
            Phone: User.FindFirst(ClaimTypes.MobilePhone)?.Value,
            Name: User.FindFirst(ClaimTypes.GivenName)?.Value,
            Surname: User.FindFirst(ClaimTypes.Surname)?.Value);

        return View(new AccountPageViewModel
        {
            UserJwt = JetlinkTokenFactory.Create(user, secret)
        });
    }
}

Üretim ortamında bu sınıfları projenizin namespace yapısına yerleştirin. Avatar ve ek alanlar gerekiyorsa JetlinkUser nesnesinin AvatarUrl ve CustomFields özelliklerini sunucudaki kullanıcı kaydından doldurun. Token veya gizli anahtar değerlerini loglamayın.

4.2.4. Login sonrası tarayıcı entegrasyonu

Bu aşamada JWT’nin backend’de üretildiği varsayılır. Sunucu, HTML sayfasını oluştururken token değerini Jetlink scriptine yerleştirir. Tarayıcı yalnızca SDK’yı yükler ve hazır token’ı Jetlink.SetUser ile iletir; token almak için fetch, AJAX veya ayrı bir token API isteği kullanılmaz.

Node.js / EJS sayfa şablonu

Bu kodu views/account.ejs içinde kullanın. userJwt, yukarıdaki sayfa işleyicisinden şablona gelen sunucu üretimi JWT’dir. JSON.stringify token’ı JavaScript string değeri olarak yazar.

<script type="text/javascript">
  var userJwt = <%- JSON.stringify(userJwt) %>;
  var jetlinkScript = document.createElement("script");
  jetlinkScript.src = "https://public.jetlink.io/Sdk/Jetlink.js?j=" + Date.now() / 1000;
  jetlinkScript.onload = function () {
    Jetlink.SetUser({ Jwt: userJwt });
    Jetlink.Init("YOUR_APP_ID", "YOUR_APP_KEY");
  };
  document.head.appendChild(jetlinkScript);
</script>

C# / Razor sayfa şablonu

Bu kodu controller’ın döndürdüğü Views/Account/Index.cshtml görünümünde kullanın. AccountPageViewModel için gerekiyorsa projenizin namespace’ini @model satırına ekleyin.

@model AccountPageViewModel
@using System.Text.Json

<script type="text/javascript">
  var userJwt = @Html.Raw(JsonSerializer.Serialize(Model.UserJwt));
  var jetlinkScript = document.createElement("script");
  jetlinkScript.src = "https://public.jetlink.io/Sdk/Jetlink.js?j=" + Date.now() / 1000;
  jetlinkScript.onload = function () {
    Jetlink.SetUser({ Jwt: userJwt });
    Jetlink.Init("YOUR_APP_ID", "YOUR_APP_KEY");
  };
  document.head.appendChild(jetlinkScript);
</script>

Razor örneğinde JsonSerializer.Serialize token’ı JavaScript’e uygun bir string literaline dönüştürür. Html.Raw yalnızca bu serileştirilmiş, sunucunun ürettiği token değerini yazmak için kullanılır; doğrulanmamış kullanıcı girdisini doğrudan script içine basmayın.

Sunucunun oluşturacağı scriptin genel biçimi

Aşağıdaki SERVER_GENERATED_USER_JWT, sayfa oluşturulurken backend’in gerçek token değeriyle doldurduğu yeri temsil eder. Sabit bir token’ı tüm kullanıcılar için kullanmayın.

<script type="text/javascript">
  var jetlinkScript = document.createElement("script");
  jetlinkScript.src = "https://public.jetlink.io/Sdk/Jetlink.js?j=" + Date.now() / 1000;
  jetlinkScript.onload = function () {
    Jetlink.SetUser({ Jwt: "SERVER_GENERATED_USER_JWT" });
    Jetlink.Init("YOUR_APP_ID", "YOUR_APP_KEY");
  };
  document.head.appendChild(jetlinkScript);
</script>

Gizli kalan değer JWT imzalama anahtarıdır. Kullanıcı token’ı SDK’ya gönderildiği için oluşturulan sayfada ve tarayıcıda erişilebilir; ayrı token isteği yapılmaması token’ı tarayıcıdan gizlemez. Kullanıcıya özel HTML’yi ortak önbelleklere yazmayın ve HTTPS üzerinden sunun.

Bu örnekleri anonim kurulum koduyla birlikte çalıştırmayın. Giriş yapılmış sayfada uygun sunucu teknolojisine ait tek bir kurulum örneği kullanın.

Çağrı sırası ve alan yazımı

1. Backend, kullanıcının uygulama oturumunu doğrular.
   
2. Kullanıcı payload’u ve JWT backend’de oluşturulur.
   
3. Sunucu token’ı sayfanın Jetlink scriptine yazar.
   
4. Tarayıcıda Jetlink.js yüklenir.
   
5. Önce Jetlink.SetUser({ Jwt: token }), sonra Jetlink.Init çağrılır.
   

SDK alanı Jwt şeklinde büyük J ile yazılır. Token payload’undaki alanlar user_id, email ve custom_fields gibi küçük harfli adları kullanır. JWT doğrulaması açıkken profil bilgilerini ayrıca açık alanlar olarak göndermeyin; sunucudaki payload’a ekleyin.

4.2.5. Token süresi ve oturum yönetimi

Geçerlilik süresi nasıl değerlendirilir?

Jetlink, token’ın iat değerini panelde seçilen geçerlilik süresine göre değerlendirir. iat değeri bu süreden eski olan token’lar reddedilir. Örneğin 10 dakika seçildiyse, 10 dakikadan daha önce üretilmiş token’ı yeniden kullanmayın.

Her sayfa yüklemesinde veya uygulama oturumunda yeni token üretin. Sunucu saatini doğru tutun. Bu entegrasyonun belgelenmiş süre kuralı iat ve paneldeki süreye dayanır; yalnızca exp eklemek bu kontrolün yerine geçmez.

Tek sayfa uygulamaları ve kullanıcı değişimi

React, Vue veya Angular gibi tek sayfa uygulamalarında SDK yüklemesini merkezi bir noktadan yönetin; her bileşen render’ında veya rota değişiminde yeniden script eklemeyin. Kullanıcı çıkış yaptığında veya hesap değiştirdiğinde önceki kullanıcıya ait, sayfaya gömülmüş token’ı yeniden kullanmayın. Yeni kullanıcı oturumuna ait token’ı backend’de üretip ilgili sayfa çıktısına aktarın.

Bu rehberdeki örnek, SDK’nın ilk başlatılmasını kapsar. Daha önce anonim veya başka bir kullanıcıyla başlatılmış Messenger’da login/logout, hesap değiştirme ve uzun oturumlarda token yenileme işlemleri için kullanılan SDK sürümünün oturum temizleme ve kullanıcı güncelleme davranışı doğrulanmalıdır. Yalnızca sayfayı yenilemenin, token değişkenini silmenin veya tekrar Init çağırmanın önceki Messenger oturumunu temizlediğini varsaymayın.

Gizli anahtar değişikliği

Yeni anahtarı token üreten tüm backend örneklerine kontrollü biçimde dağıtın ve yeni token’larla doğrulamayı test edin. Eski anahtarla üretilen token’ların çalışmaya devam edeceğini varsaymayın. Anahtar değişimini, kullanıcıların yeni token alabileceği bir geçişle birlikte planlayın.

4.3. Mevcut doğrudan aktarımdan JWT’ye geçiş

1. Mevcut kurulumdaki kanal bilgilerini ve kullanıcı kimliği eşlemesini belirleyin.
   
2. Gizli anahtarı backend’de tanımlayın ve sayfa oluşturma akışına token üretimini ekleyin.
   
3. Kullanıcı alanlarını payload’a taşıyın; user_id eşlemesini mevcut kullanıcılarla tutarlı olacak şekilde doğrulayın.
   
4. Sayfa şablonunu, backend’de üretilen token’ı Jetlink scriptine yazıp SetUser çağıracak biçimde güncelleyin.
   
5. JWT doğrulamasını açmayı ön yüz ve sunucu dağıtımıyla birlikte planlayın. Yeni token entegrasyonu hazır olmadan açılırsa token göndermeyen kullanıcılar anonim olarak devam eder.
   
6. Geçerli token, hatalı token ve anonim kullanım senaryolarını test edin.
   
7. Web Messenger, iOS ve Android kanallarının tümünde JWT doğrulamasını etkinleştirin.
   

Kullanıcılar kanallar arasında ortaktır. Tam koruma için JWT’yi kullandığınız tüm kanallarda açın. Bu rehberdeki JavaScript örnekleri web içindir; mobil token aktarımını ilgili mobil entegrasyonla yapılandırın.

5. Messenger kuralları ve iletişim bilgisi formu

İletişim bilgisi toplama — ShowContactInfoRequest

İletişim bilgisi formunda hangi alanların gösterileceğini ve hangilerinin zorunlu olacağını ayrı ayrı belirleyebilirsiniz. IsExists ile biten özellikler alanın gösterilmesini, IsRequired ile biten özellikler zorunluluğunu belirler. Her birine gerçek bir Boolean değer, true veya false, atayın.

Bu özelliklerin tamamı Jetlink.Options altında kullanılır. Onay alanında gösterilecek bağlantı ContactInfoAgreementLink, metin ise ContactInfoAgreementText ile belirlenir.

IsVisitorContactInfoRequired = true, ziyaretçinin iletişim bilgilerini girmesini zorunlu kılmak için kullanılır. İletişim formunun doldurulması, JWT ile sunucu imzalı kullanıcı doğrulamasıyla aynı işlem değildir.

// Jetlink.Init çağrısından önce:
Jetlink.Options.ContactInfoNameIsExists = true;
Jetlink.Options.ContactInfoNameIsRequired = true;
Jetlink.Options.ContactInfoSurnameIsExists = true;
Jetlink.Options.ContactInfoSurnameIsRequired = false;
Jetlink.Options.ContactInfoEmailIsExists = true;
Jetlink.Options.ContactInfoEmailIsRequired = true;
Jetlink.Options.ContactInfoPhoneIsExists = true;
Jetlink.Options.ContactInfoPhoneIsRequired = false;
Jetlink.Options.ContactInfoGenderIsExists = false;
Jetlink.Options.ContactInfoGenderIsRequired = false;
Jetlink.Options.ContactInfoAgreementIsExists = true;
Jetlink.Options.ContactInfoAgreementIsRequired = true;
Jetlink.Options.ContactInfoAgreementLink = "https://example.com/bilgilendirme";
Jetlink.Options.ContactInfoAgreementText = "Bilgilendirme metnini okudum.";
Jetlink.Options.IsVisitorContactInfoRequired = true;

Onay metni ve bağlantı örnektir; kurumunuzun kullanacağı içerikle değiştirin. README bu konuyu ShowContactInfoRequest başlığı altında açıklar, ancak bu ad için ayrıca bir çağrı veya atama örneği vermez. Yukarıdaki yapı, belgelenmiş form alanı ayarlarını kullanır.

Sohbet açıkken açma düğmesini gizleme

Jetlink.Options.HideLauncherWhenChatWindowIsOpen = true;

Bu ayar, sohbet penceresi açıkken Messenger açma düğmesinin gizlenmesini sağlar. Jetlink.Init çağrısından önce tanımlayın.

6. Messenger fonksiyonları

Jetlink.AddMessage — Konuşma ekranına bilgilendirme mesajı ekleme

Konuşma ekranında bilgilendirme mesajı göstermek için kullanılır. İkinci parametre isteğe bağlıdır; yazıyor göstergesinin ne kadar süre görüneceğini belirler. 3000 değeri 3 saniyedir. Parametre verilmezse yazıyor göstergesi gösterilmez.

Jetlink.AddMessage("Web sitemizi ziyaret ettiğiniz için teşekkür ederiz.", 3000);
// Yazıyor göstergesi olmadan:
Jetlink.AddMessage("Size nasıl yardımcı olabiliriz?");

Jetlink.OpenChatWindow — Sohbet penceresini açma

Messenger başlatılıp ekranda gösterildikten sonra sohbet penceresini programatik olarak açmak için kullanılır.

Jetlink.OpenChatWindow();

Jetlink.CloseChatWindow — Sohbet penceresini kapatma

Sohbet penceresi açılıp ekranda gösterildikten sonra kapatmak için kullanılır.

Jetlink.CloseChatWindow();

CloseChatWindow görsel pencereyi kapatır; bunu kullanıcı oturumunu temizleyen veya logout yapan bir fonksiyon olarak kullanmayın.

7. Messenger olayları

OnChatWindowFirstOpened — İlk açılış

Kullanıcı Messenger açma düğmesine ilk kez tıkladığında tetiklenir. Örneğin ilk açılışta bir karşılama mesajı gösterebilirsiniz.

Jetlink.OnChatWindowFirstOpened = function () {
  Jetlink.AddMessage("Web sitemizi ziyaret ettiğiniz için teşekkür ederiz.", 3000);
};

OnChatWindowOpened — Her açılış

Kullanıcı Messenger açma düğmesine her tıkladığında tetiklenir. Örneğin açılış sayısını uygulamanız içinde takip edebilirsiniz.

var launcherIconClickCount = 0;
Jetlink.OnChatWindowOpened = function () {
  launcherIconClickCount++;
};

Olay işleyicilerini SDK yüklendikten sonra tanımlayın. Birleşik örnekte olaylar Init öncesinde atanır. Bu olayların programatik açma çağrılarıyla da tetikleneceğini varsaymadan ilgili akışı test edin.

8. Proaktif mesajlar

Jetlink.AddCampaignMessage, o anda web sitenizi görüntüleyen kullanıcıya iş kurallarınıza bağlı proaktif mesaj göstermek için kullanılır. Ödeme sırasında sorun yaşanması, kayıt formunda hata oluşması veya kullanıcının belirli bir düğmeye tıklaması örnek tetikleyicilerdir.

İlgili uygulama olayında, Messenger başlatıldıktan sonra çağırın. Örneklerdeki typeof Jetlink kontrolü yalnızca SDK nesnesinin varlığını kontrol eder; tek başına tüm başlatma işlemlerinin tamamlandığını garanti etmez.

Metin tabanlı proaktif mesaj

if (typeof Jetlink !== "undefined") {
  var messageObject = {
    Message: "Ödemeniz işlenirken bir sorun oluştu. Farklı bir kartla tekrar deneyebilir veya destek için bize yazabilirsiniz."
  };
  Jetlink.AddCampaignMessage(messageObject);
}

Zengin içerikli proaktif mesaj

if (typeof Jetlink !== "undefined") {
  var messageObject = {
    Message: "Üyelik işleminizde yardımcı olabiliriz.",
    MessageTitle: "Yardıma ihtiyacınız var mı?",
    PictureUrl: "https://example.com/support.png",
    ButtonText: "Destek alın"
  };
  Jetlink.AddCampaignMessage(messageObject);
}

Aynı olayın tekrar tekrar tetiklenerek kullanıcıya mükerrer mesaj göstermemesi için uygulamanızda uygun kontrolü yapın. Düğme metni, tek başına bir yönlendirme URL’si tanımlamaz; örneğe belgelenmemiş bir bağlantı alanı eklemeyin.

9. Birleşik SDK örneği

Aşağıdaki örnekte JWT’nin backend’de üretildiği ve HTML oluşturulurken SERVER_GENERATED_USER_JWT yerine yazıldığı varsayılır. Node.js/EJS için <%- JSON.stringify(userJwt) %>, C#/Razor için @Html.Raw(JsonSerializer.Serialize(Model.UserJwt)) ifadesini bir önceki bölümdeki gibi kullanın. Bu şablon ifadeleri tırnaklı yer tutucunun tamamının yerine geçer.

Örnek; dil, görünüm, Messenger kuralı, olay ve kullanıcı aktarımını birleştirir. Giriş yapılmış sayfada temel kurulum kodunun yerine kullanın.

<script type="text/javascript">
  // Bu değer sayfa oluşturulurken backend tarafından yerleştirilir.
  var userJwt = "SERVER_GENERATED_USER_JWT";

  var jetlinkScript = document.createElement("script");
  jetlinkScript.src = "https://public.jetlink.io/Sdk/Jetlink.js?j=" + Date.now() / 1000;
  jetlinkScript.onload = function () {
    Jetlink.Options.Language = "tr";
    Jetlink.Options.FontFamily = "Arial";
    Jetlink.Options.MessageTextBoxPlaceholder = "Mesajınızı yazın...";
    Jetlink.Options.ShowEmojiButton = true;
    Jetlink.Options.ShowAttachmentButton = true;
    Jetlink.Options.HideLauncherWhenChatWindowIsOpen = true;

    Jetlink.OnChatWindowFirstOpened = function () {
      Jetlink.AddMessage("Merhaba, size nasıl yardımcı olabiliriz?", 3000);
    };

    Jetlink.SetUser({ Jwt: userJwt });
    Jetlink.Init("YOUR_APP_ID", "YOUR_APP_KEY");
  };
  jetlinkScript.onerror = function () {
    console.error("Jetlink SDK yüklenemedi.");
  };
  document.head.appendChild(jetlinkScript);
</script>

10. Kurulum testi ve sorun giderme

Önce test ortamında, birbirinden farklı iki kullanıcıyla kontrol yapın. Messenger’ın görünmesi tek başına kimlik doğrulamanın başarılı olduğunu göstermez; Jetlink’te oluşan konuşmanın kullanıcı bilgilerini de kontrol edin.

SDK işlevlerinin kontrolü

• Messenger’ın hedef sayfalarda tek kez yüklendiğini doğrulayın.
  
• Dil, renk, görsel ve boyut ayarlarını masaüstü ve mobil görünümde kontrol edin.
  
• İletişim formunda alanların görünürlük ve zorunluluk ayarlarını test edin.
  
• İlk açılış ve her açılış olaylarının beklenen şekilde çalıştığını kontrol edin.
  
• Programatik açma/kapama ve bilgilendirme mesajlarını test edin.
  
• Metin ve zengin içerikli proaktif mesajları gerçek uygulama tetikleyicileriyle deneyin.
  

Hangi durumda neyi kontrol etmelisiniz?

Destek incelemesi için ilgili kanal, tarih-saat, tarayıcı sürümü, kullanılan akış ve maskelenmiş hata bilgilerini paylaşın. JWT gizli anahtarını, tam kullanıcı token’ını ve oturum çerezlerini destek kayıtlarına eklemeyin.

Sık sorulan sorular

JWT açıldığında giriş yapmamış ziyaretçiler sohbet edebilir mi?

Evet. JWT’si olmayan ziyaretçiler Messenger’ı anonim ziyaretçi olarak kullanabilir.

Token’ı tarayıcıda üretebilir miyim?

Hayır. Token imzalama işlemi gizli anahtar gerektirir; bu işlem yalnızca sunucunuzda yapılmalıdır. Tarayıcı sadece imzalanmış token’ı alır.

Mevcut uygulama access token’ımı gönderebilir miyim?

Mevcut token’ınızın Jetlink formatıyla uyumlu olduğunu varsaymayın. Bu entegrasyonda Jetlink için, gerekli alanlarla ve paneldeki gizli anahtarla HS256 imzalı bir kullanıcı token’ı üretin.

JWT içindeki bilgiler gizli midir?

JWT imzası şifreleme değildir. Token’ı elde eden biri payload içeriğini okuyabilir. Şifre, uygulama erişim token’ı veya gereksiz hassas bilgileri payload’a eklemeyin.

JWT açıkken email veya name alanını ayrıca SetUser ile gönderebilir miyim?

Bu modda kullanıcı verileri yalnızca token’dan alınır. Profil bilgilerini sunucudaki payload’a ekleyip yeni token üretin.

Geçerlilik süresi sohbeti aynı anda kapatır mı?

Belgelenmiş kural, iat değeri seçili süreden eski token’ların reddedilmesidir. Bu kuraldan açık sohbetin aynı anda sonlanacağı veya token’ın SDK tarafından otomatik yenileneceği sonucu çıkarılmamalıdır.

Yalnızca web kanalında JWT açmam yeterli mi?

Kullanıcılar kanallar arasında ortak olduğundan tam koruma için Web Messenger, iOS ve Android dahil kullandığınız tüm ilgili kanallarda JWT’yi açın.

Teknik referans: Jetlink JavaScript SDK. Mevcut SDK özellikleri, paylaşılan README dosyasından; JWT ayarları ve entegrasyonu, Kullanıcı Doğrulama (JWT) ekranı ile paylaşılan yeni ürün açıklamalarından derlenmiştir. C# serileştirme referansı: JsonSerializer.Serialize.