klaviyo swift sdk
4.0.0
Klaviyo Swift SDK memungkinkan pengembang untuk memasukkan analitik analitik dan push notification Klaviyo ke dalam aplikasi iOS mereka. SDK membantu dalam mengidentifikasi pengguna dan melacak acara melalui API klien Klaviyo. Untuk mengurangi overhead kinerja, permintaan API antri dan dikirim dalam batch. Antrian tetap ada pada penyimpanan lokal sehingga data tidak hilang jika perangkat offline atau aplikasi diakhiri.
Setelah terintegrasi, tim pemasaran Anda akan dapat lebih memahami kebutuhan pengguna aplikasi Anda dan mengirimkan pesan tepat waktu melalui APN.
Aktifkan kemampuan pemberitahuan push dalam proyek XCODE Anda. Bagian "Mengaktifkan kemampuan pemberitahuan push" dalam panduan pengembang apel ini memberikan instruksi terperinci.
[Opsional tetapi disarankan] Jika Anda bermaksud menggunakan pemberitahuan push yang kaya, tambahkan ekstensi layanan pemberitahuan ke proyek XCODE Anda. Perpanjangan aplikasi layanan pemberitahuan dikirimkan sebagai bundel terpisah di dalam aplikasi iOS Anda. Untuk menambahkan ekstensi ini ke aplikasi Anda:
️ Target penyebaran ekstensi layanan pemberitahuan Anda default ke versi iOS terbaru. Jika ini melebihi versi iOS minimum yang didukung aplikasi Anda, pemberitahuan tekan tidak dapat menampilkan media yang terlampir pada perangkat yang lebih lama. Untuk menghindari hal ini, pastikan target penyebaran minimum ekstensi cocok dengan aplikasi Anda.️
Berdasarkan manajer ketergantungan yang Anda gunakan, ikuti instruksi di bawah ini untuk menginstal dependensi Klaviyo.
Klaviyoswift tersedia melalui Swift Package Manager. Ikuti langkah -langkah di bawah ini untuk menginstal.
https://github.com/klaviyo/klaviyo-swift-sdk di bidang teks. Ini harus memunculkan paket di layar.KlaviyoSwift ke target aplikasi Anda dan KlaviyoSwiftExtension ke target ekstensi layanan pemberitahuan (jika satu dibuat) dan klik Paket Tambah .Klaviyoswift tersedia melalui cocoapods.
YourAppTarget YourAppNotificationServiceExtenionTarget aplikasi Anda. target 'YourAppTarget' do
pod 'KlaviyoSwift'
end
target 'YourAppNotificationServiceExtenionTarget' do
pod 'KlaviyoSwiftExtension'
endpod install untuk menyelesaikan integrasi. Perpustakaan dapat terus diperbarui melalui pod update KlaviyoSwift dan pod update KlaviyoSwiftExtension . Akhirnya, di file NotificationService.swift Tambahkan kode untuk dua delegasi yang diperlukan dari file ini. Sampel ini mencakup panggilan ke Klaviyo sehingga kami dapat mengunduh dan melampirkan media ke pemberitahuan push.
SDK harus diinisialisasi dengan kunci API publik alfanumerik pendek untuk akun Klaviyo Anda, juga dikenal sebagai ID situs Anda.
// AppDelegate
import KlaviyoSwift
class AppDelegate : UIResponder , UIApplicationDelegate {
func application ( _ application : UIApplication , didFinishLaunchingWithOptions launchOptions : [ UIApplication . LaunchOptionsKey : Any ] ? ) -> Bool {
KlaviyoSDK ( ) . initialize ( with : " YOUR_KLAVIYO_PUBLIC_API_KEY " )
return true
}
}SDK harus diinisialisasi sebelum metode Klaviyo SDK lainnya dipanggil.
SDK menyediakan metode untuk mengidentifikasi pengguna Anda sebagai profil Klaviyo melalui API Profil Klien Buat. Profil dapat diidentifikasi dengan kombinasi apa pun dari yang berikut:
Pengidentifikasi di atas ini bertahan untuk penyimpanan lokal sehingga SDK dapat melacak pengguna/profil saat ini untuk Anda ketika Anda membuat permintaan acara atau ingin mengatur token push dll.
Pengidentifikasi profil dapat diatur sekaligus atau secara individual. Either way, SDK akan mengelompokkan dan batch API panggilan untuk meningkatkan kinerja.
Kode berikut menunjukkan cara mengatur pengidentifikasi profil:
// organization, title, image, location and additional properties (dictionary) can also be set using the below constructor
let profile = Profile ( email : " [email protected] " , firstName : " Blob " , lastName : " Jr. " )
KlaviyoSDK ( ) . set ( profile : profile )
// or setting individual properties
KlaviyoSDK ( ) . set ( profileAttribute : . firstName , value : " Blob " )
KlaviyoSDK ( ) . set ( profileAttribute : . lastName , value : " Jr. " ) Untuk memulai profil baru sama sekali (misalnya jika pengguna keluar) baik hubungi KlaviyoSDK().resetProfile() untuk menghapus pengidentifikasi profil yang saat ini dilacak, atau menggunakan KlaviyoSDK().set(profile: profile) obyek.
// start a profile for Blob Jr.
let profile = Profile ( email : " [email protected] " , firstName : " Blob " , lastName : " Jr. " )
KlaviyoSDK ( ) . set ( profile : profile )
// stop tracking Blob Jr.
KlaviyoSDK ( ) . resetProfile ( )
// start a profile for Robin Hood
let profile = Profile ( email : " [email protected] " , firstName : " Robin " , lastName : " Hood " )
KlaviyoSDK ( ) . set ( profile : profile )Klaviyo akan melacak pengguna yang tidak dikenal dengan ID autogenerated setiap kali token push diatur atau acara dibuat. Dengan begitu, Anda dapat mengumpulkan token push dan melacak acara sebelum mengumpulkan pengidentifikasi profil seperti email atau nomor telepon. Ketika pengidentifikasi disediakan, Klaviyo akan menggabungkan pengguna anonim dengan pengguna yang diidentifikasi.
SDK menyediakan alat untuk melacak acara yang dilakukan pengguna di aplikasi Anda melalui API acara Create Client. Di bawah ini adalah contoh cara melacak suatu acara:
// using a predefined event name
let event = Event ( name : . StartedCheckoutMetric ,
properties : [
" name " : " cool t-shirt " ,
" color " : " blue " ,
" size " : " medium " ,
] ,
value : 166 )
KlaviyoSDK ( ) . create ( event : event )
// using a custom event name
let customEvent = Event ( name : . CustomEvent ( " Checkout Completed " ) ,
properties : [
" name " : " cool t-shirt " ,
" color " : " blue " ,
" size " : " medium " ,
] ,
value : 166 )
KlaviyoSDK ( ) . create ( event : customEvent ) Metode create mengambil objek acara sebagai argumen. Acara ini dapat dibangun dengan argumen berikut:
name : Nama acara yang ingin Anda lacak, sebagai EventName Enum. Daftar metrik acara yang ditentukan Klaviyo umum dapat ditemukan di Event.EventName . Anda juga dapat membuat acara kustom dengan menggunakan CustomEvent enum case Event.EventNameproperties : Kamus properti yang khusus untuk acara tersebut. Argumen ini opsional.value : Nilai numerik ( Double ) untuk dikaitkan dengan acara ini. Misalnya, jumlah pembelian dolar. Untuk mengirim pemberitahuan push kepada pengguna Anda, Anda harus mengumpulkan token push mereka dan mendaftarkannya dengan Klaviyo. Ini dilakukan melalui KlaviyoSDK().set(pushToken:) , yang mendaftarkan token push dan status otorisasi saat ini melalui Create Client Push Token API.
registerForRemoteNotifications() untuk meminta token push dari APNs. Ini biasanya dilakukan dalam application:didFinishLaunchingWithOptions: Metode delegasi aplikasi Anda.application:didRegisterForRemoteNotificationsWithDeviceToken dalam delegasi aplikasi Anda untuk menerima token push dari APN dan mendaftarkannya ke Klaviyo.Di bawah ini adalah kode untuk melakukan kedua langkah di atas:
import KlaviyoSwift
func application ( _ application : UIApplication , didFinishLaunchingWithOptions launchOptions : [ UIApplication . LaunchOptionsKey : Any ] ? ) -> Bool {
KlaviyoSDK ( ) . initialize ( with : " YOUR_KLAVIYO_PUBLIC_API_KEY " )
UIApplication . shared . registerForRemoteNotifications ( )
return true
}
func application ( _ application : UIApplication , didRegisterForRemoteNotificationsWithDeviceToken deviceToken : Data ) {
KlaviyoSDK ( ) . set ( pushToken : deviceToken )
} Setelah token push diperoleh, langkah selanjutnya adalah meminta izin dari pengguna Anda untuk mengirim mereka pemberitahuan push. Anda dapat menambahkan kode permintaan izin di mana saja di aplikasi Anda di mana masuk akal untuk meminta pengguna untuk izin ini. Apple memberikan beberapa pedoman tentang praktik terbaik kapan dan bagaimana cara meminta izin ini. Contoh berikut menunjukkan cara meminta izin push dalam application:didFinishLaunchingWithOptions: Metode dalam file delegasi aplikasi. Namun, perlu dicatat bahwa ini mungkin bukan lokasi yang ideal karena dapat mengganggu pengalaman startup aplikasi.
Setelah mengatur token push, Klaviyo SDK akan secara otomatis melacak perubahan pada izin pemberitahuan pengguna setiap kali aplikasi dibuka atau dilanjutkan dari latar belakang.
Di bawah ini adalah contoh kode untuk meminta izin pemberitahuan push:
import UserNotifications
func application ( _ application : UIApplication , didFinishLaunchingWithOptions launchOptions : [ UIApplication . LaunchOptionsKey : Any ] ? ) -> Bool {
KlaviyoSDK ( ) . initialize ( with : " YOUR_KLAVIYO_PUBLIC_API_KEY " )
UIApplication . shared . registerForRemoteNotifications ( )
let center = UNUserNotificationCenter . current ( )
center . delegate = self as? UNUserNotificationCenterDelegate // the type casting can be removed once the delegate has been implemented
let options : UNAuthorizationOptions = [ . alert , . sound , . badge ]
// use the below options if you are interested in using provisional push notifications. Note that using this will not
// show the push notifications prompt to the user.
// let options: UNAuthorizationOptions = [.alert, .sound, .badge, .provisional]
center . requestAuthorization ( options : options ) { granted , error in
if let error = error {
// Handle the error here.
print ( " error = " , error )
}
// Irrespective of the authorization status call `registerForRemoteNotifications` here so that
// the `didRegisterForRemoteNotificationsWithDeviceToken` delegate is called. Doing this
// will make sure that Klaviyo always has the latest push authorization status.
DispatchQueue . main . async {
UIApplication . shared . registerForRemoteNotifications ( )
}
}
return true
} Ketika pengguna mengetuk pemberitahuan push, implementasikan userNotificationCenter:didReceive:withCompletionHandler dan userNotificationCenter:willPresent:withCompletionHandler di delegasi aplikasi Anda untuk menangani penerima pemberitahuan push ketika aplikasi berada di latar belakang dan latar depan masing -masing.
Di bawah ini adalah contoh cara menangani pemberitahuan push di delegasi aplikasi Anda:
// be sure to set the UNUserNotificationCenterDelegate to self in the didFinishLaunchingWithOptions method (refer the requesting push notification permission section above for more details on this)
extension AppDelegate : UNUserNotificationCenterDelegate {
// below method will be called when the user interacts with the push notification
func userNotificationCenter (
_ center : UNUserNotificationCenter ,
didReceive response : UNNotificationResponse ,
withCompletionHandler completionHandler : @escaping ( ) -> Void ) {
// If this notification is Klaviyo's notification we'll handle it
// else pass it on to the next push notification service to which it may belong
let handled = KlaviyoSDK ( ) . handle ( notificationResponse : response , withCompletionHandler : completionHandler )
if !handled {
completionHandler ( )
}
}
// below method is called when the app receives push notifications when the app is the foreground
func userNotificationCenter (
_ center : UNUserNotificationCenter ,
willPresent notification : UNNotification ,
withCompletionHandler completionHandler : @escaping ( UNNotificationPresentationOptions ) -> Void ) {
if #available ( iOS 14 . 0 , * ) {
completionHandler ( [ . list , . banner ] )
} else {
completionHandler ( [ . alert ] )
}
}
} Saat melacak pemberitahuan push yang dibuka, Anda juga dapat mengurangi jumlah lencana pada ikon aplikasi dengan menambahkan kode berikut ke userNotificationCenter:didReceive:withCompletionHandler Metode:
func userNotificationCenter (
_ center : UNUserNotificationCenter ,
didReceive response : UNNotificationResponse ,
withCompletionHandler completionHandler : @escaping ( ) -> Void ) {
// decrement the badge count on the app icon
if #available ( iOS 16 . 0 , * ) {
UNUserNotificationCenter . current ( ) . setBadgeCount ( UIApplication . shared . applicationIconBadgeNumber - 1 )
} else {
UIApplication . shared . applicationIconBadgeNumber -= 1
}
// If this notification is Klaviyo's notification we'll handle it
// else pass it on to the next push notification service to which it may belong
let handled = KlaviyoSDK ( ) . handle ( notificationResponse : response , withCompletionHandler : completionHandler )
if !handled {
completionHandler ( )
}
} Selain itu, jika Anda hanya ingin mengatur ulang jumlah lencana ke nol saat aplikasi dibuka (perhatikan bahwa ini bisa dari pengguna yang hanya membuka aplikasi terlepas dari pesan push), Anda dapat menambahkan kode berikut ke metode applicationDidBecomeActive di dalam Delegasi Aplikasi:
func applicationDidBecomeActive ( _ application : UIApplication ) {
// reset the badge count on the app icon
if #available ( iOS 16 . 0 , * ) {
UNUserNotificationCenter . current ( ) . setBadgeCount ( 0 )
} else {
UIApplication . shared . applicationIconBadgeNumber = 0
}
}Setelah pemberitahuan push pertama Anda dikirim dan dibuka, Anda harus mulai melihat metrik push yang terbuka di dalam dasbor Klaviyo Anda.
Aplikasi Anda perlu menggunakan versi 1.7.2 minimal agar langkah -langkah di bawah ini berfungsi.
Tautan mendalam memungkinkan Anda untuk menavigasi ke halaman tertentu dalam aplikasi Anda sebagai tanggapan terhadap pengguna yang membuka pemberitahuan push.
Anda perlu mengonfigurasi tautan mendalam di aplikasi Anda agar berfungsi. Proses konfigurasi untuk Klaviyo tidak berbeda dari apa yang diperlukan untuk menangani tautan mendalam secara umum, sehingga Anda dapat mengikuti dokumentasi Apple untuk tautan mendalam bersama dengan langkah -langkah yang diuraikan di sini.
Anda memiliki dua opsi untuk mengimplementasikan tautan mendalam: skema URL dan tautan universal.
Skema URL adalah cara tradisional dan lebih sederhana dari tautan mendalam dari pemberitahuan dorong ke aplikasi Anda. Namun, tautan ini hanya akan berfungsi jika aplikasi seluler Anda diinstal pada perangkat dan tidak akan dipahami oleh browser web jika, misalnya, Anda ingin menautkan dari email ke aplikasi Anda.
Agar Apple dapat merutekan tautan yang mendalam ke aplikasi Anda, Anda perlu mendaftarkan skema URL di file info aplikasi Anda. Ini dapat dilakukan dengan menggunakan editor yang diberikan Xcode dari tab Info dari pengaturan proyek Anda atau dengan mengedit info.plist secara langsung.
Bidang yang diperlukan adalah sebagai berikut:
Untuk mengedit info.plist secara langsung, cukup isi detail spesifik aplikasi Anda dan tempel ini di plist Anda.
< key >CFBundleURLTypes</ key >
< array >
< dict >
< key >CFBundleTypeRole</ key >
< string >Editor</ string >
< key >CFBundleURLName</ key >
< string >{your_unique_identifier}</ string >
< key >CFBundleURLSchemes</ key >
< array >
< string >{your_URL_scheme}</ string >
</ array >
</ dict >
</ array >Karena iOS 9 Apple telah mengamanatkan bahwa skema URL yang dapat dibuka oleh aplikasi Anda juga perlu terdaftar di Info.plist. Ini selain langkah 1 di atas. Bahkan jika aplikasi Anda tidak membuka aplikasi lain, Anda masih perlu mendaftarkan skema URL aplikasi Anda agar tautan yang dalam untuk berfungsi.
Ini perlu dilakukan di info.plist secara langsung:
< key >LSApplicationQueriesSchemes</ key >
< array >
< string >{your custom URL scheme}</ string >
</ array > Langkah 1 dan 2 Aktifkan aplikasi Anda untuk menerima tautan yang dalam, tetapi Anda juga perlu menangani tautan ini dalam aplikasi Anda. Ini dilakukan dengan mengimplementasikan application:openURL:options: Metode dalam delegasi aplikasi Anda.
Contoh:
func application (
_ app : UIApplication ,
open url : URL ,
options : [ UIApplication . OpenURLOptionsKey : Any ] = [ : ]
) -> Bool {
guard let components = NSURLComponents ( url : url , resolvingAgainstBaseURL : true )
else {
print ( " Invalid deep linking URL " )
return false
}
print ( " components: ( components . debugDescription ) " )
return true
} Jika Anda menggunakan SwiftUi, maka Anda dapat mengimplementasikan onOpenURL(perform:) Sebagai pengubah tampilan dalam tampilan yang Anda maksud untuk menangani tautan yang dalam. Ini mungkin atau mungkin bukan akar adegan Anda.
Contoh:
@ main
struct MyApplication : App {
var body : some Scene {
WindowGroup {
ContentView ( )
. onOpenURL { url in
// handle the URL that must be opened
}
}
}
} Akhirnya, kami memiliki contoh aplikasi ( Examples/KlaviyoSwiftExamples ) dalam repo SDK yang dapat Anda referensi untuk mendapatkan contoh cara menerapkan tautan mendalam di aplikasi Anda.
Setelah langkah -langkah di atas selesai, Anda dapat mengirim pemberitahuan push dari Klaviyo Push Editor di dalam situs web Klaviyo. Di sini Anda dapat membangun dan mengirim pemberitahuan push melalui Klaviyo untuk memastikan bahwa URL muncul di pawang yang Anda terapkan pada Langkah 3.
Selain itu, Anda juga dapat secara lokal memicu tautan yang dalam untuk memastikan kode Anda berfungsi menggunakan perintah di bawah ini di terminal.
xcrun simctl openurl booted {your_URL_here}
Tautan universal adalah cara yang lebih modern untuk menangani tautan yang dalam dan direkomendasikan oleh Apple. Mereka lebih aman dan memberikan pengalaman pengguna yang lebih baik. Namun, tidak seperti skema URL mereka membutuhkan sedikit lebih banyak pengaturan yang disorot dalam dokumen Apple ini.
Setelah Anda memiliki pengaturan dari Apple Docs di tempat, Anda perlu memodifikasi pelacakan terbuka push seperti yang dijelaskan di bawah ini:
extension AppDelegate : UNUserNotificationCenterDelegate {
func userNotificationCenter ( _ center : UNUserNotificationCenter , didReceive response : UNNotificationResponse , withCompletionHandler completionHandler : @escaping ( ) -> Void ) {
let handled = KlaviyoSDK ( ) . handle ( notificationResponse : response , withCompletionHandler : completionHandler ) { url in
print ( " deep link is " , url )
}
if !handled {
// not a klaviyo notification should be handled by other app code
}
}
}Perhatikan bahwa pawang tautan dalam akan dipanggil kembali di utas utama. Jika Anda ingin menangani skema URL selain tautan universal, Anda mengimplementasikannya seperti yang dijelaskan dalam Opsi 1: Skema URL.
Pemberitahuan Push Rich didukung dalam SDK Versi 2.2.0 dan lebih tinggi
Rich Push adalah kemampuan untuk menambahkan gambar untuk mendorong pesan pemberitahuan. Setelah langkah -langkah di bagian instalasi selesai, Anda harus memiliki ekstensi layanan pemberitahuan dalam pengaturan proyek Anda dengan kode dari KlaviyoSwiftExtension . Di bawah ini adalah instruksi tentang cara menguji pemberitahuan push yang kaya.
{
"aps" : {
"alert" : {
"title" : " Free apple vision pro " ,
"body" : " Free Apple vision pro when you buy a Klaviyo subscription. "
},
"mutable-content" : 1
},
"rich-media" : " https://www.apple.com/v/apple-vision-pro/a/images/overview/hero/portrait_base__bwsgtdddcl7m_large.jpg " ,
"rich-media-type" : " jpg "
}didRegisterForRemoteNotificationsWithDeviceToken di AppDelegate .Setelah Anda memiliki ketiga hal ini, Anda kemudian dapat menggunakan penguji Push Notification dan mengirim pemberitahuan push lokal untuk memastikan bahwa semuanya telah diatur dengan benar.
Dukungan kotak pasir tersedia di SDK Versi 2.2.0 dan lebih tinggi
Apple memiliki dua lingkungan dengan dukungan pemberitahuan push - produksi dan kotak pasir. Lingkungan produksi mendukung pengiriman pemberitahuan push ke pengguna nyata ketika aplikasi diterbitkan di App Store atau TestFlight. Sebaliknya, aplikasi kotak pasir yang mendukung pemberitahuan push adalah yang ditandatangani dengan sertifikat pengembangan iOS, bukan sertifikat distribusi iOS. Sandbox bertindak sebagai lingkungan pementasan, memungkinkan Anda untuk menguji aplikasi Anda di lingkungan yang mirip dengan tetapi berbeda dari produksi tanpa harus khawatir mengirim pesan ke pengguna nyata.
SDK kami mendukung penggunaan kotak pasir untuk dorong juga. SDK Klaviyo akan menentukan dan menyimpan lingkungan yang dimiliki oleh dorong Anda dan mengomunikasikannya ke backend kami, memungkinkan token Anda untuk rute dikirim ke lingkungan yang benar. Tidak ada pengaturan tambahan yang diperlukan. Selama Anda telah menggunakan aplikasi Anda ke Sandbox dengan SDK kami yang digunakan untuk mengirimkan token dorong ke backend kami, kemampuan untuk mengirim dan menerima dorongan pada aplikasi kotak pasir ini harus bekerja di luar kotak.
Dimulai dengan versi 1.7.0, SDK akan menyimpan data yang masuk dan menyiramnya kembali ke API Klaviyo pada interval. Interval didasarkan pada tautan jaringan yang saat ini digunakan oleh aplikasi. Tabel di bawah ini menunjukkan interval flush yang digunakan untuk setiap jenis koneksi:
| Jaringan | Selang |
|---|---|
| Wwan/WiFi | 10 detik |
| Seluler | 30 detik |
Penentuan koneksi didasarkan pada pemberitahuan dari layanan jangkauan kami. Ketika tidak ada jaringan yang tersedia, SDK akan cache data sampai jaringan tersedia lagi. Semua data yang dikirim oleh SDK harus tersedia segera setelah disiram oleh SDK.
SDK akan mencoba lagi permintaan API yang gagal dalam kondisi tertentu. Misalnya, jika batas waktu jaringan terjadi, permintaan akan diceritakan kembali pada interval flush berikutnya. Selain itu, jika SDK menerima kesalahan pembatas tingkat 429 dari Klaviyo API, itu akan menggunakan backoff eksponensial dengan Jitter untuk mencoba lagi permintaan berikutnya.
Lihat Panduan Kontribusi untuk mempelajari cara berkontribusi pada Klaviyo Swift SDK. Kami menyambut umpan balik Anda di bagian Isu -isu dari repositori GitHub publik kami.
Klaviyoswift tersedia di bawah lisensi MIT. Lihat file lisensi untuk info lebih lanjut.
