klaviyo swift sdk
4.0.0
Le SDK Klaviyo Swift permet aux développeurs d'incorporer les fonctionnalités d'analyse et de notification de la notification de Klaviyo dans leurs applications iOS. Le SDK aide à identifier les utilisateurs et à suivre les événements via les API du client Klaviyo. Pour réduire les frais généraux de performances, les demandes d'API sont en file d'attente et envoyées par lots. La file d'attente est persistante pour le stockage local afin que les données ne soient pas perdues si l'appareil est hors ligne ou si l'application est terminée.
Une fois intégrée, votre équipe marketing sera en mesure de mieux comprendre les besoins des utilisateurs de votre application et de leur envoyer des messages en temps opportun via APNS.
Activez les capacités de notification push dans votre projet Xcode. La section «Activer la capacité de notification push» dans ce guide de développeur Apple fournit des instructions détaillées.
[Facultatif mais recommandé] Si vous avez l'intention d'utiliser des notifications push riches, ajoutez une extension de service de notification à votre projet Xcode. Une extension de l'application de service de notification est expédiée en tant que pack séparé dans votre application iOS. Pour ajouter cette extension à votre application:
️ L'objectif de déploiement de votre extension de service de notification par défaut à la dernière version iOS. Si cela dépasse la version iOS de votre application prise en charge, les notifications push peuvent ne pas afficher les supports joints sur les appareils plus anciens. Pour éviter cela, assurez-vous que la cible de déploiement minimum de l'extension correspond à celle de votre application.️
En fonction de la dépendance que vous utilisez, suivez les instructions ci-dessous pour installer les dépendances de Klaviyo.
Klaviyoswift est disponible via Swift Package Manager. Suivez les étapes ci-dessous pour installer.
https://github.com/klaviyo/klaviyo-swift-sdk dans le champ de texte. Cela devrait faire apparaître le package à l'écran.KlaviyoSwift à la cible de votre application et KlaviyoSwiftExtension à la cible d'extension du service de notification (si l'on a été créé) et cliquez sur Ajouter un package .Klaviyoswift est disponible via Cocoapods.
YourAppTarget et YourAppNotificationServiceExtenionTarget avec les noms de votre application et de votre service de notification des cibles d'extension respectivement. target 'YourAppTarget' do
pod 'KlaviyoSwift'
end
target 'YourAppNotificationServiceExtenionTarget' do
pod 'KlaviyoSwiftExtension'
endpod install pour terminer l'intégration. La bibliothèque peut être mise à jour via pod update KlaviyoSwift et pod update KlaviyoSwiftExtension . Enfin, dans le fichier NotificationService.swift , ajoutez le code des deux délégués requis de ce fichier. Cet exemple couvre l'appel dans Klaviyo afin que nous puissions télécharger et joindre le support à la notification push.
Le SDK doit être initialisé avec la touche API publique alphanumérique courte pour votre compte Klaviyo, également connu sous le nom d'identification de votre site.
// 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
}
}Le SDK doit être initialisé avant que toutes les autres méthodes SDK de Klaviyo ne soient appelées.
Le SDK fournit des méthodes pour identifier vos utilisateurs comme des profils Klaviyo via l'API Créer un profil client. Un profil peut être identifié par toute combinaison des éléments suivants:
Ces identifiants ci-dessus sont persistés pour le stockage local afin que le SDK puisse garder une trace de l'utilisateur / profil actuel pour vous lorsque vous faites des demandes d'événements ou souhaitez définir un jeton push, etc.
Les identifiants de profil peuvent être définis en une seule ou individuellement. Quoi qu'il en soit, le SDK se regroupera et les appels API par lots pour améliorer les performances.
Le code suivant montre comment définir les identificateurs de 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. " ) Pour démarrer un nouveau profil (par exemple, si un utilisateur se déconnecte), appelez KlaviyoSDK().resetProfile() pour effacer les identificateurs de profil actuellement suivis, ou utiliser KlaviyoSDK().set(profile: profile) pour le remplacer avec un nouveau profil objet.
// 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 suivra les utilisateurs non identifiés avec un ID autoogénéré chaque fois qu'un jeton push est défini ou un événement est créé. De cette façon, vous pouvez collecter des jetons push et suivre les événements avant de collecter des identifiants de profil tels que le courrier électronique ou le numéro de téléphone. Lorsqu'un identifiant est fourni, Klaviyo fusionnera l'utilisateur anonyme d'un utilisateur identifié.
Le SDK fournit des outils pour le suivi des événements que les utilisateurs effectuent sur votre application via l'API Create Client Event. Vous trouverez ci-dessous un exemple de la façon de suivre un événement:
// 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 ) La méthode create prend un objet d'événement comme argument. L'événement peut être construit avec les arguments suivants:
name : le nom de l'événement que vous souhaitez suivre, en tant qu'énumération EventName . Une liste de mesures d'événements définies par Klaviyo communes peut être trouvée dans Event.EventName . Vous pouvez également créer des événements personnalisés en utilisant le cas d' CustomEvent de Event.EventNameproperties : un dictionnaire des propriétés spécifiques à l'événement. Cet argument est facultatif.value : une valeur numérique ( Double ) à associer à cet événement. Par exemple, le montant en dollars d'un achat. Afin d'envoyer des notifications push à vos utilisateurs, vous devez collecter leurs jetons push et les enregistrer auprès de Klaviyo. Cela se fait via la KlaviyoSDK().set(pushToken:) Méthode, qui enregistre un token push et l'état d'autorisation actuel via l'API Create Client Push Token.
registerForRemoteNotifications() pour demander un jeton push aux APN. Cela se fait généralement dans l' application:didFinishLaunchingWithOptions: Méthode du délégué de votre application.application:didRegisterForRemoteNotificationsWithDeviceToken avec le délégué de votre application pour recevoir le jeton Push des APN et l'enregistrer auprès de Klaviyo.Vous trouverez ci-dessous le code pour faire les deux étapes ci-dessus:
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 )
} Une fois le jeton push obtenu, l'étape suivante consiste à demander l'autorisation à vos utilisateurs de les envoyer des notifications push. Vous pouvez ajouter le code de demande d'autorisation n'importe où dans votre application où il est logique d'inviter les utilisateurs pour cette autorisation. Apple fournit quelques lignes directrices sur les meilleures pratiques pour quand et comment demander cette autorisation. L'exemple suivant montre comment demander des autorisations push dans l' application:didFinishLaunchingWithOptions: Méthode dans le fichier de délégué d'application. Cependant, il convient de noter que ce n'est peut-être pas l'emplacement idéal car il pourrait interrompre l'expérience de démarrage de l'application.
Après avoir réglé un jeton push, le SDK Klaviyo suivra automatiquement les modifications de l'autorisation de notification de l'utilisateur chaque fois que l'application est ouverte ou repris à partir de l'arrière-plan.
Vous trouverez ci-dessous un exemple de code pour demander l'autorisation de notification 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
} Lorsqu'un utilisateur puise sur une notification push, implémentez userNotificationCenter:didReceive:withCompletionHandler et userNotificationCenter:willPresent:withCompletionHandler dans votre délégué d'application pour gérer respectivement les notifications push lorsque l'application est en arrière-plan et au premier plan.
Vous trouverez ci-dessous un exemple de la façon de gérer les notifications push dans le délégué de votre application:
// 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 ] )
}
}
} Lors du suivi de la notification push ouverte, vous pouvez également diminuer le nombre de badges sur l'icône de l'application en ajoutant le code suivant au 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 ( )
}
} De plus, si vous souhaitez simplement réinitialiser le nombre de badges à zéro lorsque l'application est ouverte (notez que cela pourrait provenir de l'utilisateur qui ouvrira simplement l'application indépendante du message push), vous pouvez ajouter le code suivant à la méthode applicationDidBecomeActive dans la méthode dans la Délégué de l'application:
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
}
}Une fois que vos premières notifications push sont envoyées et ouvertes, vous devez commencer à voir des mesures de poussée ouvertes dans votre tableau de bord Klaviyo.
Votre application doit utiliser la version 1.7.2 au minimum afin que les étapes ci-dessous fonctionnent.
Les liens profonds vous permettent de naviguer vers une page particulière dans votre application en réponse à l'utilisateur ouvrant une notification push.
Vous devez configurer des liens profonds dans votre application pour qu'ils fonctionnent. Le processus de configuration de Klaviyo n'est pas différent de ce qui est requis pour gérer la liaison profonde en général, vous pouvez donc suivre la documentation Apple pour la liaison profonde en conjonction avec les étapes décrites ici.
Vous avez deux options pour implémenter des liens profonds: schémas URL et liens universels.
Les schémas URL sont le moyen traditionnel et plus simple de lier profondément une notification push à votre application. Cependant, ces liens ne fonctionneront que si votre application mobile est installée sur un appareil et ne sera pas comprise par un navigateur Web si, par exemple, vous souhaitez lier un e-mail à votre application.
Pour qu'Apple achemine un lien profond vers votre application, vous devez enregistrer un schéma d'URL dans le fichier Info.plist de votre application. Cela peut être fait en utilisant l'éditeur que Xcode fournit à partir de l'onglet Info de vos paramètres de projet ou en modifiant directement l'info.plist.
Les champs requis sont les suivants:
Afin de modifier directement l'info.plist, remplissez simplement les détails spécifiques de votre application et collez-le dans votre 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 >Étant donné que iOS 9 Apple a mandaté que les schémas d'URL que votre application puissent ouvrir doivent également être répertoriés dans les info.plist. Ceci s'ajoute à l'étape 1 ci-dessus. Même si votre application n'ouvre aucune autre application, vous devez toujours répertorier le schéma URL de votre application afin que la liaison profonde fonctionne.
Cela doit être fait directement dans l'info.plist directement:
< key >LSApplicationQueriesSchemes</ key >
< array >
< string >{your custom URL scheme}</ string >
</ array > Les étapes 1 et 2 permettent à votre application de recevoir des liens profonds, mais vous devez également gérer ces liens dans votre application. Cela se fait en implémentant l' application:openURL:options: Méthode dans votre délégué d'application.
Exemple:
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
} Si vous utilisez SwiftUi, vous pouvez implémenter onOpenURL(perform:) en tant que modificateur de vue dans la vue que vous avez l'intention de gérer des liens profonds. Cela peut ou non être la racine de votre scène.
Exemple:
@ main
struct MyApplication : App {
var body : some Scene {
WindowGroup {
ContentView ( )
. onOpenURL { url in
// handle the URL that must be opened
}
}
}
} Enfin, nous avons un exemple d'application ( Examples/KlaviyoSwiftExamples ) dans le repo SDK que vous pouvez faire référence pour obtenir un exemple de la façon d'implémenter des liens profonds dans votre application.
Une fois les étapes ci-dessus terminées, vous pouvez envoyer des notifications push de l'éditeur de push Klaviyo sur le site Web de Klaviyo. Ici, vous pouvez construire et envoyer une notification push via Klaviyo pour vous assurer que l'URL apparaît dans le gestionnaire que vous avez implémenté à l'étape 3.
De plus, vous pouvez également déclencher localement un lien profond pour vous assurer que votre code fonctionne en utilisant la commande ci-dessous dans le terminal.
xcrun simctl openurl booted {your_URL_here}
Les liens universels sont un moyen plus moderne de gérer les liens profonds et sont recommandés par Apple. Ils sont plus sûrs et offrent une meilleure expérience utilisateur. Cependant, contrairement aux schémas d'URL, ils nécessitent un peu plus de configuration qui est mis en évidence dans ces documents Apple.
Une fois que vous aurez la configuration des documents Apple en place, vous devrez modifier le suivi de l'ouverture push comme décrit ci-dessous:
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
}
}
}Notez que le gestionnaire de liens profonds sera rappelé sur le fil principal. Si vous souhaitez gérer les schémas d'URL en plus des liens universels, vous les implémentez comme décrit dans l'option 1: schémas URL.
Les notifications push riches sont prises en charge dans la version 2.2.0 du SDK et plus
Rich Push est la possibilité d'ajouter des images pour pousser les messages de notification. Une fois les étapes de la section d'installation terminées, vous devez avoir une extension de service de notification dans votre configuration de projet avec le code de la KlaviyoSwiftExtension . Vous trouverez ci-dessous des instructions sur la façon de tester de riches notifications 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 la méthode deviceToken dans AppDelegate .Une fois que vous avez ces trois choses, vous pouvez ensuite utiliser le testeur de notifications push et envoyer une notification push locale pour vous assurer que tout a été configuré correctement.
La prise en charge de Sandbox est disponible dans la version 2.2.0 du SDK et plus
Apple a deux environnements avec support de notification push - production et bac à sable. L'environnement de production prend en charge l'envoi de notifications push aux utilisateurs réels lorsqu'une application est publiée dans l'App Store ou TestFlight. En revanche, les applications Sandbox qui prennent en charge les notifications push sont celles signées avec des certificats de développement iOS, au lieu des certificats de distribution iOS. Sandbox agit comme un environnement de mise en scène, vous permettant de tester vos applications dans un environnement similaire mais distinct de la production sans avoir à vous soucier d'envoyer des messages aux vrais utilisateurs.
Notre SDK prend également en charge l'utilisation de Sandbox pour Push. Le SDK de Klaviyo déterminera et stockera l'environnement auquel votre jeton de poussée appartient et communiquera cela à notre backend, permettant à vos jetons d'achever les envois dans les environnements appropriés. Aucune configuration supplémentaire n'est nécessaire. Tant que vous avez déployé votre application sur Sandbox avec notre SDK utilisé pour transmettre des jetons push sur notre backend, la possibilité d'envoyer et de recevoir des applications sur la bac à sable devrait fonctionner à l'extérieur.
En commençant par la version 1.7.0, le SDK mettra en cache les données entrantes et la retournera à l'API Klaviyo sur un intervalle. L'intervalle est basé sur le lien réseau actuellement utilisé par l'application. Le tableau ci-dessous montre l'intervalle de rinçage utilisé pour chaque type de connexion:
| Réseau | Intervalle |
|---|---|
| Wwan / wifi | 10 secondes |
| Cellulaire | 30 secondes |
La détermination de la connexion est basée sur les notifications de notre service d'accessibilité. Lorsqu'il n'y a pas de réseau disponible, le SDK mettra en cache les données jusqu'à ce que le réseau redevienne disponible. Toutes les données envoyées par le SDK doivent être disponibles peu de temps après leur vidange par le SDK.
Le SDK réessayera les demandes d'API qui échouent dans certaines conditions. Par exemple, si un délai d'expiration du réseau se produit, la demande sera rejetée sur l'intervalle de rinçage suivant. De plus, si le SDK reçoit une erreur de limitation de taux 429 de l'API KLAVIYO, il utilisera un revers exponentiel avec une gigue pour réessayer la prochaine demande.
Voir le guide contribuant pour apprendre à contribuer au SDK Klaviyo Swift. Nous accueillons vos commentaires dans la section des problèmes de notre référentiel public GitHub.
Klaviyoswift est disponible sous la licence du MIT. Voir le fichier de licence pour plus d'informations.
