7. Mobil: SDK ve push linki
Mobil tarafta iki ayrı senaryo vardır ve gereksinimleri farklıdır.
7.1 Uygulama içi anket (SDK)
Bölüm başlığı “7.1 Uygulama içi anket (SDK)”- YönMobil uygulama → SARP CX
- Kimlik
appId + 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 adım iOS entegrasyonu
Bölüm başlığı “Adım adım iOS entegrasyonu”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.
| Alan | Ne olduğu | SDK’da |
|---|---|---|
| App ID | Uygulamanı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 adresi | boot(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.TKSurveyFeedbackkütüphanesini uygulama hedefine ekleyin. - CocoaPods:
pod 'TKSurvey', '~> 1.0'. Modül adı yineTKSurveyFeedbackolduğundanimportsatı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) }}customeriçinde yalnızcaname,email,phoneNumber,externalIdvecustomAttrsiletilir; diğer anahtarlar atılır.show’un completion’ı bir kez, sonuçla çağrılır. React Native promise’i ya da Flutterresult’ı bununla güvenle kapatılabilir.- Aynı uygulamada ikinci bir anket göstermek için yeniden
bootgerekmez: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
healthCheckkullanılır (Booldö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.
Durum kodları
Bölüm başlığı “Durum kodları”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.
| Durum | Anlamı |
|---|---|
sendFeedback | Kullanıcı yanıtı gönderdi. |
closed / outside | Kapatma düğmesi ya da (kanal izin veriyorsa) form dışına dokunma/kaydırma. |
displayOnce | Kanal “bir kez göster” ayarlı ve bu cihazda daha önce gösterildi. |
preventMultipleFeedback | Bu cihaz, “Yanıt sonrası sessiz kalma” süresi içinde zaten yanıt verdi. |
displayRateLimited | Gösterim oranı/aralığı kuralı ya da sunucunun hız sınırı (429). |
surveyPassive | Sunucu kanalı reddetti (aşağıdaki uyarıya bakın). |
initSucces / initFailed | boot içindeki sağlık kontrolünün sonucu. |
opened | Form yüklendi. Yalnızca bildirimde yayınlanır. |
Arka planda: SDK’nın yaptığı istek
Bölüm başlığı “Arka planda: SDK’nın yaptığı istek”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.
7.2 Push bildirimi linki
Bölüm başlığı “7.2 Push bildirimi linki”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