İçeriğe geç

7. Mobil: SDK ve push linki

Mobil tarafta iki ayrı senaryo vardır ve gereksinimleri farklıdır.

  • YönMobil uygulama → SARP CX
  • KimlikappId + accessKey
  • Oturum45 dakika
  • Limit600 açılış / dk · kanal+IP

Anket, uygulamanın içinde bir web görünümünde (WKWebView) açılır. Uygulama ekibi HTTP isteklerini kendisi yazmaz: iOS için hazır SDK (TKSurveyFeedback) kimliği doğrular, oturumu yeniler, görüntüleme kurallarını uygular ve sonucu bir durum koduyla bildirir. Android, React Native ve Flutter bağlamaları sonraki aşamadadır.

Adım 1: Anketi yayınlayın (panel). SDK yalnızca yayındaki bir anketin aktif kanalını açabilir. Taslaktaki, kapanmış ya da kotası dolmuş bir anket uygulamada hiç görünmez.

Adım 2: Mobil uygulamayı tanımlayın (panel, bir kez). Dağıtım → Mobil sekmesinin sağ üstündeki Mobil uygulamalar düğmesi → Yeni uygulama. Uygulamaya bir ad verin; App ID (tk_app_…) ve Erişim Anahtarı (tk_ak_…) otomatik üretilir.

Mobil uygulama kaydı hesap geneli bir kayıttır: bir uygulama hesaptaki tüm anketlerin mobil kanallarını açabilir. Her anket için ayrı uygulama tanımlanmaz; uygulama (App Store’daki uygulama) başına bir kayıt yeterlidir.

Adım 3: Mobil kanalı oluşturun (panel, anket başına). Aynı sekmede Yeni kanal. Kanal tipi Mobil uygulama (SDK) olarak sabittir ve sonradan değiştirilemez. Mobil kanalda izinli adres listesi yoktur; erişim, uygulama kimliğiyle doğrulanır. Görünüm ve davranış ayarları için bkz. 10.5 Mobil.

Adım 4: Parametreleri alın (panel). Kanal satırının menüsünden Kanal parametrelerini paylaş. Açılan pencerede bir mobil uygulama seçin; aşağıdaki beş değer tek tek kopyalanabilir gelir. Altındaki Örnek boot çağrısı bu değerlerle doldurulmuş, derlenmeye hazır Swift kodudur.

AlanNe olduğuSDK’da
App IDUygulamanın kimliği (tk_app_…)boot(appId:)
Erişim AnahtarıUygulamanın anahtarı (tk_ak_…)boot(accessKey:)
Kanal kodu (code)Kanalın genel anahtarı (tk_ch_…)boot(code:), isteğe bağlı show(code:)
API adresi (apiUrl)Ortamın API köküboot(apiUrl:)
Form adresi (feedbackUrl)Anket formunun adresiboot(feedbackUrl:)

apiUrl ve feedbackUrl ortama göre değişir (dev ve prod farklıdır); kanal ya da uygulamaya göre değişmez.

Adım 5: SDK’yı projeye ekleyin (Xcode). iOS 13 veya üzeri gerekir. Paket deposu özeldir: önce Xcode → Settings → Accounts altına turkishtechnology organizasyonuna erişimi olan bir GitHub hesabı ekleyin; aksi halde paket çözümü “repository not found” hatası verir.

  • Swift Package Manager: File → Add Package Dependencies… → https://github.com/turkishtechnology/tk-survey-ios, kural Up to Next Major Version, 1.0.0’dan itibaren. TKSurveyFeedback kütüphanesini uygulama hedefine ekleyin.
  • CocoaPods: pod 'TKSurvey', '~> 1.0'. Modül adı yine TKSurveyFeedback olduğundan import satırı değişmez.

Adım 6: Uygulama açılışında boot çağırın. Bir kez çağrılması yeterlidir; değerler 4. adımdan gelir.

import TKSurveyFeedback
TKSurvey.boot(
appId: "tk_app_…",
accessKey: "tk_ak_…",
code: "tk_ch_…",
apiUrl: "https://…",
feedbackUrl: "https://…"
) { status in
// .initSucces: kanal hazır · .initFailed: kimlik, adres veya kanal sorunu
}

boot, kimlik bilgilerini saklar ve bir sağlık kontrolü yapar. Sonuç .initSucces ya da .initFailed olarak döner (initSucces yazımı önceki sağlayıcının SDK’sıyla uyum için bilinçli olarak korunmuştur).

Adım 7: Anketi göstermek istediğiniz yerde show çağırın.

TKSurvey.show(
mode: .bottomSheet, // veya .default
title: "Geri bildirim",
language: "tr",
customer: ["externalId": "…", "email": "…"]
) { status in
switch status {
case .sendFeedback:
break // kullanıcı yanıtı gönderdi
case .closed, .outside:
break // kullanıcı kapattı
default:
break // anket gösterilmedi; sebep status içinde (aşağıdaki tablo)
}
}
  • customer içinde yalnızca name, email, phoneNumber, externalId ve customAttrs iletilir; diğer anahtarlar atılır.
  • show’un completion’ı bir kez, sonuçla çağrılır. React Native promise’i ya da Flutter result’ı bununla güvenle kapatılabilir.
  • Aynı uygulamada ikinci bir anket göstermek için yeniden boot gerekmez: show(code: "tk_ch_…") yalnızca o çağrı için başka kanalı açar.
  • Anketi açmadan önce kanalın yanıt kabul edip etmediğini sormak için healthCheck kullanılır (Bool döner).

Adım 8: Sonuçları dinleyin (isteğe bağlı). Her durum ayrıca tk-survey-actions bildirimiyle yayınlanır. Formun açıldığını bildiren .opened yalnızca burada görünür, show’un completion’ına hiç gelmez.

NotificationCenter.default.addObserver(
forName: TKSurvey.actionNotification, // "tk-survey-actions"
object: nil,
queue: .main
) { note in
let status = note.userInfo?["closeStatus"] as? String
}

Adım 9: Test edin. Önce dev ortamının apiUrl/feedbackUrl değerleriyle deneyin. Ayrıntılı günlük için TKSurvey.debugMode(true) açın (varsayılan kapalı). Denemeler arasında yerel sayaçları sıfırlamak için TKSurvey.clear() kullanın; bu, “bir kez göster” gibi kuralları da sıfırlar.

Hata ya da kural nedeniyle anket gösterilmediğinde SDK ekrana hiçbir şey çizmez; sebep yalnızca durum kodunda ve bildirimde görünür.

DurumAnlamı
sendFeedbackKullanıcı yanıtı gönderdi.
closed / outsideKapatma düğmesi ya da (kanal izin veriyorsa) form dışına dokunma/kaydırma.
displayOnceKanal “bir kez göster” ayarlı ve bu cihazda daha önce gösterildi.
preventMultipleFeedbackBu cihaz, “Yanıt sonrası sessiz kalma” süresi içinde zaten yanıt verdi.
displayRateLimitedGösterim oranı/aralığı kuralı ya da sunucunun hız sınırı (429).
surveyPassiveSunucu kanalı reddetti (aşağıdaki uyarıya bakın).
initSucces / initFailedboot içindeki sağlık kontrolünün sonucu.
openedForm yüklendi. Yalnızca bildirimde yayınlanır.

Bu bölüm SDK’yı kullanan uygulama ekibi için değil, akışı izlemek ya da başka bir platform için SDK yazmak isteyenler içindir.

POST/api/v1/surveys/public/channels/{publicKey}/mobile-resolve

{
"appId": "tk_app_…",
"accessKey": "tk_ak_…",
"lang": "tr",
"platform": "ios",
"sdkVersion": "1.2.0"
}

Yanıt, web widget ile aynı zarftır:

{
"contractVersion": 1,
"channel": { "publicKey": "tk_ch_…", "theme": {…}, "behavior": {…},
"defaultLocale": "tr", "signatureRequired": false },
"surveySlug": "…",
"sessionToken": "…"
}

Kanalın hizmet verip vermediğini sormak için ayrı bir sağlık uç noktası vardır; burada kimlik gövdede değil başlıkta taşınır: x-tk-app-id ve x-tk-access-key. Anket içeriği dönmez.

API entegrasyonu gerektirmeyen yol: anonim anket linkine parametre eklenir. Format, Pisano’nun “entegrasyonsuz kişiselleştirilmiş link” formatıyla birebir aynıdır: mevcut link üretim kodu değişmez, yalnızca adres tabanı değişir.

https://s.air.tk/<slug>?responses=<base64>&sig=v1:<hex>
responses = base64( [{"question":"ucus_no","answer":"TK1986"}] )
sig = "v1:" + HMAC_SHA256(secret, <base64 metnin kendisi>) hex