klaviyo swift sdk
4.0.0
Klaviyo Swift SDK позволяет разработчикам включать аналитику Klaviyo и функциональность уведомления в свои приложения для iOS. SDK помогает идентифицировать пользователей и отслеживать события через API клиента Klaviyo. Чтобы уменьшить накладные расходы, запросы API в очереди и отправляются партиями. Очередь сохраняется для локального хранилища, так что данные не теряются, если устройство не в автономном режиме или приложение прекращается.
После интеграции ваша маркетинговая команда сможет лучше понять потребности пользователей вашего приложения и отправлять им своевременные сообщения через APN.
Включите возможности push -уведомления в вашем проекте Xcode. В этом разделе «Включить возможность уведомления push» в этом руководстве по разработчику Apple содержится подробные инструкции.
[Необязательно, но рекомендуется] Если вы намереваетесь использовать богатые уведомления Push, добавьте расширение службы уведомлений в свой проект XCode. Уведомление об уведомлении приложений поступает в виде отдельного пакета в вашем приложении для iOS. Чтобы добавить это расширение в ваше приложение:
️ Цель развертывания для расширения службы уведомлений по умолчанию по умолчанию к последней версии iOS. Если это превышает минимальную версию для iOS, поддерживаемая вашим приложением, уведомления Push могут не отображать прикрепленные носители на старых устройствах. Чтобы избежать этого, убедитесь, что минимальная цель развертывания расширения соответствует целеустремленности вашего приложения.️
Основываясь на том, какой диспетчер зависимостей вы используете, следуйте инструкциям ниже, чтобы установить зависимости Клавийо.
Klaviyoswift доступен через Swift Package Manager. Следуйте приведенным ниже шагам, чтобы установить.
https://github.com/klaviyo/klaviyo-swift-sdk в текстовом поле. Это должно поднять пакет на экране.KlaviyoSwift вашему приложению Target и KlaviyoSwiftExtension с целью расширения уведомлений (если он был создан) и нажмите «Добавить пакет» .Klaviyoswift доступен через кокопод.
YourAppTarget и YourAppNotificationServiceExtenionTarget на имена вашего приложения и целей уведомления о расширении службы соответственно. target 'YourAppTarget' do
pod 'KlaviyoSwift'
end
target 'YourAppNotificationServiceExtenionTarget' do
pod 'KlaviyoSwiftExtension'
endpod install чтобы завершить интеграцию. Библиотека может быть обновлена с помощью pod update KlaviyoSwift и pod update KlaviyoSwiftExtension . Наконец, в файл NotificationService.swift добавьте код для двух необходимых делегатов из этого файла. Этот образец охватывает призывы к Клавийо, чтобы мы могли загрузить и прикрепить носитель к уведомлению Push.
SDK должен быть инициализирован с помощью короткого буквенно -цифрового общественного ключа API для вашей учетной записи Klaviyo, также известного как идентификатор вашего сайта.
// 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 должен быть инициализирован до того, как будут вызваны любые другие методы Klaviyo SDK.
SDK предоставляет методы для идентификации ваших пользователей как профилей Klaviyo через API Create Client Profile. Профиль может быть идентифицирован по любой комбинации следующего:
Эти вышеупомянутые идентификаторы сохраняются в локальном хранилище, так что SDK может отслеживать текущего пользователя/профиля для вас, когда вы выполняете запросы на события или хотите установить токен push и т. Д.
Идентификаторы профиля могут быть установлены одновременно или индивидуально. В любом случае, SDK будет группировать и партийные API вызовы для повышения производительности.
Следующий код демонстрирует, как установить идентификаторы профиля:
// 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. " ) KlaviyoSDK().set(profile: profile) запустить новый профиль (например, если пользователь выходит из входа) KlaviyoSDK().resetProfile() объект.
// 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 будет отслеживать неопознанных пользователей с автогенерированным идентификатором всякий раз, когда будет установлен токен push или создается событие. Таким образом, вы можете собирать токены и отслеживать события перед сбором идентификаторов профиля, таких как электронная почта или номер телефона. Когда будет предоставлен идентификатор, Klaviyo объединит анонимного пользователя с идентифицированным пользователем.
SDK предоставляет инструменты для отслеживания событий, которые пользователи выполняют в вашем приложении через API Create Client Event. Ниже приведен пример того, как отслеживать событие:
// 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 ) Метод create принимает объект события в качестве аргумента. Событие может быть построено со следующими аргументами:
name : имя события, которое вы хотите отслеживать, как EventName Enum. Список общих показанных метриков событий, определенных Клавио, можно найти в Event.EventName . Вы также можете создать пользовательские события, используя случай CustomEvent Enum Event.EventNameproperties : Словарь свойств, которые специфичны для события. Этот аргумент не является обязательным.value : числовое значение ( Double ) для связи с этим событием. Например, сумма покупки в долларах. Чтобы отправить push -уведомления вашим пользователям, вы должны собрать их токены и зарегистрировать их в Klaviyo. Это делается с помощью KlaviyoSDK().set(pushToken:) Метод, который регистрирует токен и текущее состояние авторизации через API Create Client Push Token.
registerForRemoteNotifications() для запроса ток -тона от APNS. Обычно это делается в application:didFinishLaunchingWithOptions: метод вашего делегата вашего приложения.application:didRegisterForRemoteNotificationsWithDeviceToken в вашем делегате для получения токна PUSH от APNS и зарегистрировать его в Klaviyo.Ниже приведен код для выполнения обоих вышеуказанных шагов:
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 )
} После получения токена толкания следующим шагом является запрос разрешения от ваших пользователей на отправку им push -уведомлений. Вы можете добавить код запроса разрешения в любом месте вашего приложения, где имеет смысл предложить пользователям это разрешение. Apple предоставляет некоторые руководящие принципы о лучших практиках, когда и как попросить этого разрешения. В следующем примере демонстрируется, как запросить разрешения на то, что в application:didFinishLaunchingWithOptions: метод в файле делегирования приложения. Тем не менее, стоит отметить, что это может быть не идеальное место, так как оно может прервать опыт стартапа приложения.
После настройки токена Push, Klaviyo SDK автоматически отслеживает изменения в разрешении уведомления пользователя всякий раз, когда приложение будет открыто или возобновлено из фона.
Ниже приведен пример кода для запроса разрешения на уведомление 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
} Когда пользователь нажимает на push -уведомление, реализуйте userNotificationCenter:didReceive:withCompletionHandler и userNotificationCenter:willPresent:withCompletionHandler в делегате вашего приложения для обработки получения Push -уведомлений, когда приложение находится в фоновом режиме и на переднем плане соответственно.
Ниже приведен пример того, как обрабатывать push -уведомления в вашем приложении делегат:
// 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 ] )
}
}
} При отслеживании открытого уведомления PUSH вы также можете уменьшить количество значков значков на значке приложения, добавив следующий код в userNotificationCenter:didReceive:withCompletionHandler :
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 ( )
}
} Кроме того, если вы просто хотите сбросить количество значков до нуля при открытии приложения (обратите внимание, что это может быть от пользователя, просто открывающего приложение независимо от сообщения push), вы можете добавить следующий код в метод applicationDidBecomeActive . Приложение делегат:
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
}
}После того, как ваши первые уведомления о том, что вы отправлены и открыты, вы должны начать видеть открытые показатели Push на вашей панели панели Klaviyo.
Ваше приложение должно использовать версию 1.7.2 как минимум для работы ниже.
Глубокие ссылки позволяют вам перейти на конкретную страницу в вашем приложении в ответ на пользователь, открывающий уведомление о push.
Вам нужно настроить глубокие ссылки в вашем приложении, чтобы они работали. Процесс конфигурации для Klaviyo ничем не отличается от того, что требуется для обработки глубокого связывания в целом, поэтому вы можете следовать документации Apple для глубокого связывания в сочетании с этапами, изложенными здесь.
У вас есть два варианта реализации глубоких ссылок: схемы URL и универсальные ссылки.
Схемы URL - это традиционный и более простой способ глубокого связывания от толчкового уведомления с вашим приложением. Тем не менее, эти ссылки будут работать только в том случае, если ваше мобильное приложение будет установлено на устройстве и не будет понято веб -браузером, если, например, вы хотите ссылаться на электронную почту в свое приложение.
Чтобы Apple направила глубокую ссылку на ваше приложение, вам необходимо зарегистрировать схему URL -адреса в файле info.plist вашего приложения. Это может быть сделано с помощью редактора, который XCode предоставляет с вкладки «Информация настройки проекта» или путем редактирования Info.plist напрямую.
Требуемые поля следующие:
Чтобы отредактировать info.plist напрямую, просто заполните конкретные детали вашего приложения и вставьте это в свой PLIST.
< 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 >Поскольку iOS 9 Apple поручила схемам URL, которые может открыть ваше приложение, также должны быть указаны в Info.plist. Это в дополнение к шагу 1 выше. Даже если ваше приложение не открывает какие -либо другие приложения, вам все равно нужно перечислить схему URL -адреса вашего приложения, чтобы глубоко связывать работу.
Это должно быть сделано в info.plist напрямую:
< key >LSApplicationQueriesSchemes</ key >
< array >
< string >{your custom URL scheme}</ string >
</ array > Шаги 1 и 2 позволяют вашему приложению получать глубокие ссылки, но вам также необходимо обрабатывать эти ссылки в вашем приложении. Это делается путем реализации application:openURL:options: Метод в вашем делегате приложения.
Пример:
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
} Если вы используете Swiftui, то вы можете реализовать onOpenURL(perform:) как модификатор представления в представлении, который вы намерены обрабатывать глубокие ссылки. Это может или не может быть корнем вашей сцены.
Пример:
@ main
struct MyApplication : App {
var body : some Scene {
WindowGroup {
ContentView ( )
. onOpenURL { url in
// handle the URL that must be opened
}
}
}
} Наконец, у нас есть пример приложения ( Examples/KlaviyoSwiftExamples ) в репо SDK, которое вы можете ссылаться на пример того, как реализовать глубокие ссылки в вашем приложении.
После завершения вышеуказанных шагов вы можете отправить push -уведомления от редактора Push Klaviyo на веб -сайте Klaviyo. Здесь вы можете построить и отправить push -уведомление через Klaviyo, чтобы убедиться, что URL -адрес отображается в обработке, который вы реализовали на шаге 3.
Кроме того, вы также можете локально запустить глубокую ссылку, чтобы убедиться, что ваш код работает с использованием приведенной ниже команды в терминале.
xcrun simctl openurl booted {your_URL_here}
Универсальные ссылки являются более современным способом обработки глубоких ссылок и рекомендуются Apple. Они более безопасны и обеспечивают лучший пользовательский опыт. Однако, в отличие от схем URL, им требуется немного больше настроек, которые выделяются в этих Apple Docs.
После того, как у вас есть настройка из Apple Docs, вам нужно будет изменить открытое отслеживание Push, как описано ниже:
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
}
}
}Обратите внимание, что обработчик глубоких ссылок будет вызовет обратно в главную ветку. Если вы хотите обрабатывать схемы URL в дополнение к универсальным ссылкам, вы их реализуете, как описано в варианте 1: схемы URL.
Rich Push -уведомления поддерживаются в SDK версии 2.2.0 и выше
Rich Push - это возможность добавлять изображения, чтобы протолкнуть сообщения уведомлений. Как только шаги в разделе установки будут завершены, вы должны иметь расширение службы уведомлений в настройке проекта с кодом из KlaviyoSwiftExtension . Ниже приведены инструкции о том, как проверить богатые уведомления Push.
{
"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 с помощью AppDelegate .После того, как у вас есть эти три вещи, вы можете использовать тестер Push Push -уведомления и отправить локальное уведомление о Push, чтобы убедиться, что все было настроено правильно.
Поддержка песочницы доступна в SDK версии 2.2.0 и выше
Apple имеет две среды с поддержкой Push -уведомлений - производство и песочница. Производственная среда поддерживает отправку push -уведомлений реальным пользователям, когда приложение опубликовано в App Store или Testflight. Напротив, приложения для песочницы, которые поддерживают Push -уведомления, являются теми, которые подписаны с сертификатами разработки iOS, вместо сертификатов распределения iOS. Песочница выступает в качестве обстановки, позволяя вам проверять ваши приложения в среде, подобной, но отличающуюся от производства, не беспокоясь о отправке сообщений реальным пользователям.
Наш SDK также поддерживает использование песочницы для толчка. SDK Klaviyo определит и хранит среду, к которой принадлежит ваш ток -ток, и сообщают об этом на нашу бэкэнд, позволяя вашим токенам отправлять отправку в правильные среды. Там нет дополнительной настройки. Пока вы развернули свою заявку на песочницу с нашим SDK, используемым для передачи токенов на нашу бэкэнд, возможность отправлять и получать толчок на этих приложениях для песочницы должна работать вне коробки.
Начиная с версии 1.7.0, SDK будет кэшировать входящие данные и пропустить их обратно в API Klaviyo в интервале. Интервал основан на сетевой ссылке, в настоящее время используемой приложением. В таблице ниже показан интервал промывки, используемый для каждого типа соединения:
| Сеть | Интервал |
|---|---|
| WWAN/WIFI | 10 секунд |
| Клеточный | 30 секунд |
Определение соединения основано на уведомлениях от нашей службы достижимости. Когда сеть не будет доступна, SDK будет кэшировать данные, пока сеть снова не станет доступной. Все данные, отправленные SDK, должны быть доступны вскоре после того, как он промывается SDK.
SDK повторно повторит запросы API, которые терпят неудачу при определенных условиях. Например, если происходит тайм -аут сети, запрос будет повторно оказан в следующем интервале промывки. Кроме того, если SDK получает ошибку 429 ограничивающей ставки от API Klaviyo, он будет использовать экспоненциальный отключение с джиттером для повторения следующего запроса.
См. Руководство по вклад, чтобы узнать, как внести свой вклад в Klaviyo Swift SDK. Мы приветствуем ваши отзывы в разделе «Проблемы нашего публичного репозитория GitHub».
Klaviyoswift доступен по лицензии MIT. Смотрите файл лицензии для получения дополнительной информации.
