klaviyo swift sdk
4.0.0
O Klaviyo Swift SDK permite que os desenvolvedores incorporem a análise da Klaviyo e empurre a funcionalidade de notificação em seus aplicativos iOS. O SDK auxilia a identificar usuários e rastrear eventos via APIs do Klaviyo Client. Para reduzir a sobrecarga de desempenho, as solicitações da API são filmadas e enviadas em lotes. A fila é persistida no armazenamento local para que os dados não sejam perdidos se o dispositivo estiver offline ou o aplicativo for encerrado.
Uma vez integrado, sua equipe de marketing poderá entender melhor as necessidades dos usuários do aplicativo e enviar mensagens oportunas via APNs.
Ativar recursos de notificação de push em seu projeto Xcode. A seção "Ative a capacidade de notificação de push" neste guia do desenvolvedor da Apple fornece instruções detalhadas.
[Opcional, mas recomendado] Se você pretende usar notificações ricas em push, adicione uma extensão do serviço de notificação ao seu projeto Xcode. Um aplicativo de serviço de notificação é fornecido como um pacote separado dentro do seu aplicativo iOS. Para adicionar esta extensão ao seu aplicativo:
️ A meta de implantação da sua extensão de serviço de notificação é padronizada para a versão mais recente do iOS. Se isso exceder a versão iOS mínima do seu aplicativo, as notificações push podem não exibir mídia anexada em dispositivos mais antigos. Para evitar isso, verifique se a meta de implantação mínima da extensão corresponde à do seu aplicativo.️
Com base em qual gerenciador de dependência você usa, siga as instruções abaixo para instalar as dependências do Klaviyo.
Klaviyoswift está disponível via Swift Package Manager. Siga as etapas abaixo para instalar.
https://github.com/klaviyo/klaviyo-swift-sdk no campo de texto. Isso deve abrir o pacote na tela.KlaviyoSwift ao seu Target de App e KlaviyoSwiftExtension ao destino de extensão do serviço de notificação (se um foi criado) e clique em Adicionar pacote .Klaviyoswift está disponível através de Cocoapods.
YourAppTarget e YourAppNotificationServiceExtenionTarget pelos nomes de seu aplicativo e metas de extensão de serviço de notificação, respectivamente. target 'YourAppTarget' do
pod 'KlaviyoSwift'
end
target 'YourAppNotificationServiceExtenionTarget' do
pod 'KlaviyoSwiftExtension'
endpod install para concluir a integração. A biblioteca pode ser mantida atualizada por meio da pod update KlaviyoSwift e pod update KlaviyoSwiftExtension . Finalmente, no arquivo NotificationService.swift Adicione o código para os dois delegados necessários deste arquivo. Esta amostra cobre a chamada de Klaviyo para que possamos fazer o download e anexar a mídia à notificação de push.
O SDK deve ser inicializado com a curta chave da API pública alfanumérica para sua conta Klaviyo, também conhecida como ID do seu 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
}
}O SDK deve ser inicializado antes que outros métodos Klaviyo SDK sejam chamados.
O SDK fornece métodos para identificar seus usuários como perfis Klaviyo por meio da API Create Client Profile. Um perfil pode ser identificado por qualquer combinação do seguinte:
Esses identificadores acima são persistidos para o armazenamento local, para que o SDK possa acompanhar o usuário/perfil atual para você quando você faz solicitações de eventos ou deseja definir um token push etc.
Os identificadores de perfil podem ser definidos de uma só vez ou individualmente. De qualquer forma, o SDK agrupará e lotam as chamadas da API para melhorar o desempenho.
O código a seguir demonstra como definir identificadores de perfil:
// 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. " ) Para iniciar um novo perfil (por exemplo, se um usuário efetuar o login), ligue para KlaviyoSDK().resetProfile() para limpar os identificadores de perfil atualmente rastreados ou use KlaviyoSDK().set(profile: profile) para sobrescrever com um novo perfil objeto.
// 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 rastreará usuários não identificados com um ID autogenerado sempre que um token push estiver definido ou um evento for criado. Dessa forma, você pode coletar tokens push e rastrear eventos antes de coletar identificadores de perfil, como email ou número de telefone. Quando um identificador é fornecido, Klaviyo mescla o usuário anônimo com um usuário identificado.
O SDK fornece ferramentas para rastrear eventos que os usuários executam no seu aplicativo através da API Create Client Event. Abaixo está um exemplo de como rastrear um evento:
// 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 ) O método create toma um objeto de evento como argumento. O evento pode ser construído com os seguintes argumentos:
name : O nome do evento que você deseja rastrear, como um nome EventName . Uma lista de métricas de eventos comuns de Klaviyo definidas pode ser encontrada no Event.EventName . Você também pode criar eventos personalizados usando o caso CustomEvent Enum de Event.EventNameproperties : um dicionário de propriedades específicas para o evento. Este argumento é opcional.value : Um valor numérico ( Double ) para se associar a este evento. Por exemplo, a quantia em dólar de uma compra. Para enviar notificações push para seus usuários, você deve coletar seus tokens de push e registrá -los com Klaviyo. Isso é feito através do KlaviyoSDK().set(pushToken:) , que registra um token push e o estado de autorização atual através da API Create Client Push Token.
registerForRemoteNotifications() para solicitar um token de push do APNS. Isso normalmente é feito no application:didFinishLaunchingWithOptions: Método do seu delegado de aplicativo.application:didRegisterForRemoteNotificationsWithDeviceToken no seu delegado de aplicativo para receber o token de pressão do APNS e registrá -lo no Klaviyo.Abaixo está o código para fazer as duas etapas acima:
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 )
} Depois que o token push for obtido, a próxima etapa é solicitar permissão de seus usuários para enviar notificações push. Você pode adicionar o código de solicitação de permissão em qualquer lugar do seu aplicativo, onde faz sentido solicitar aos usuários essa permissão. A Apple fornece algumas diretrizes sobre as melhores práticas para quando e como solicitar essa permissão. O exemplo a seguir demonstra como solicitar permissões de push dentro do application:didFinishLaunchingWithOptions: Método no arquivo delegado do aplicativo. No entanto, vale a pena notar que esse pode não ser o local ideal, pois pode interromper a experiência de inicialização do aplicativo.
Depois de definir um token de push, o Klaviyo SDK rastreará automaticamente as alterações na permissão de notificação do usuário sempre que o aplicativo for aberto ou retomado do plano de fundo.
Abaixo está o código de exemplo para solicitar permissão de notificação de 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
} Quando um usuário tocar em uma notificação de push, implemente userNotificationCenter:didReceive:withCompletionHandler e userNotificationCenter:willPresent:withCompletionHandler em seu delegado de aplicativo para lidar com as notificações push de recebimento quando o aplicativo estiver em segundo plano e em primeiro plano, respectivamente.
Abaixo está um exemplo de como lidar com as notificações push em seu delegado de aplicativo:
// 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 ] )
}
}
} Quando o rastreamento abriu a notificação de push, você também pode diminuir a contagem de crachás no ícone do aplicativo adicionando o código a seguir ao userNotificationCenter:didReceive:withCompletionHandler Método:
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 ( )
}
} Além disso, se você deseja apenas redefinir a contagem de crachás para zero quando o aplicativo for aberto (observe que isso pode ser do usuário apenas abrir o aplicativo independente da mensagem push), você pode adicionar o seguinte código ao método applicationDidBecomeActive no Delegado de aplicativos:
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
}
}Depois que suas primeiras notificações push forem enviadas e abertas, você deve começar a ver métricas de push aberto no seu painel Klaviyo.
Seu aplicativo precisa usar a versão 1.7.2 no mínimo para que as etapas abaixo funcionem.
Os links profundos permitem que você navegue para uma página específica em seu aplicativo em resposta ao usuário que abre uma notificação de push.
Você precisa configurar links profundos em seu aplicativo para que eles funcionem. O processo de configuração para Klaviyo não é diferente do que é necessário para lidar com a ligação profunda em geral, para que você possa seguir a documentação da Apple para uma ligação profunda em conjunto com as etapas descritas aqui.
Você tem duas opções para implementar links profundos: esquemas de URL e links universais.
Os esquemas de URL são a maneira tradicional e mais simples de vincular profunda de uma notificação de push ao seu aplicativo. No entanto, esses links só funcionarão se o seu aplicativo móvel estiver instalado em um dispositivo e não for entendido por um navegador da Web se, por exemplo, você quiser vincular um email ao seu aplicativo.
Para que a Apple rotear um link profundo para o seu aplicativo, você precisa registrar um esquema de URL no arquivo info.plist do seu aplicativo. Isso pode ser feito usando o editor que o Xcode fornece na guia Informações das configurações do seu projeto ou editando o info.plist diretamente.
Os campos necessários são os seguintes:
Para editar diretamente o info.plista, basta preencher os detalhes específicos do seu aplicativo e colar isso no seu 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 >Como o iOS 9 Apple exigiu que os esquemas de URL que seu aplicativo possa abrir também precisa ser listado na info.plist. Isso é um acréscimo à etapa 1 acima. Mesmo que seu aplicativo não esteja abrindo nenhum outro aplicativo, você ainda precisa listar o esquema de URL do seu aplicativo para que a ligação profunda funcione.
Isso precisa ser feito diretamente na info.plista:
< key >LSApplicationQueriesSchemes</ key >
< array >
< string >{your custom URL scheme}</ string >
</ array > As etapas 1 e 2 permitem que seu aplicativo receba links profundos, mas você também precisa lidar com esses links em seu aplicativo. Isso é feito implementando o application:openURL:options: Método no seu delegado de aplicativo.
Exemplo:
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
} Se você estiver usando SwiftUi, poderá implementar onOpenURL(perform:) Como um modificador de exibição na visualização que pretende lidar com links profundos. Isso pode ou não ser a raiz da sua cena.
Exemplo:
@ main
struct MyApplication : App {
var body : some Scene {
WindowGroup {
ContentView ( )
. onOpenURL { url in
// handle the URL that must be opened
}
}
}
} Por fim, temos um exemplo de aplicativo ( Examples/KlaviyoSwiftExamples ) no repositório SDK que você pode fazer referência para obter um exemplo de como implementar links profundos em seu aplicativo.
Depois que as etapas acima forem concluídas, você poderá enviar notificações push do editor Klaviyo Push no site da Klaviyo. Aqui você pode construir e enviar uma notificação de push através do Klaviyo para garantir que o URL apareça no manipulador que você implementou na Etapa 3.
Além disso, você também pode acionar localmente um link profundo para garantir que seu código esteja funcionando usando o comando abaixo no terminal.
xcrun simctl openurl booted {your_URL_here}
Os links universais são uma maneira mais moderna de lidar com links profundos e são recomendados pela Apple. Eles são mais seguros e oferecem uma melhor experiência do usuário. No entanto, diferentemente dos esquemas de URL, eles exigem um pouco mais de configuração destacados nesses documentos da Apple.
Depois de ter a configuração dos documentos da Apple, você precisará modificar o rastreamento aberto, conforme descrito abaixo:
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
}
}
}Observe que o manipulador de link profundo será chamado de volta no thread principal. Se você deseja lidar com esquemas de URL, além dos links universais, você os implementa, conforme descrito nos esquemas da Opção 1: URL.
Notificações push ricas são suportadas na versão SDK 2.2.0 e superior
Rich Push é a capacidade de adicionar imagens para empurrar mensagens de notificação. Depois que as etapas da seção de instalação estiverem concluídas, você deve ter uma extensão de serviço de notificação em sua configuração do projeto com o código da KlaviyoSwiftExtension . Abaixo estão as instruções sobre como testar notificações ricas em 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 com o método DechDeviceToken no AppDelegate .Depois de ter essas três coisas, você pode usar o testador de notificações push e enviar uma notificação de push local para garantir que tudo estivesse configurado corretamente.
O suporte de sandbox está disponível no SDK versão 2.2.0 e superior
A Apple possui dois ambientes com suporte de notificação push - produção e caixa de areia. O ambiente de produção suporta o envio de notificações push para usuários reais quando um aplicativo é publicado na App Store ou Testflight. Por outro lado, os aplicativos de caixa de areia que suportam notificações push são aqueles assinados com os certificados de desenvolvimento do iOS, em vez de certificados de distribuição do iOS. O Sandbox atua como um ambiente de encenação, permitindo que você teste seus aplicativos em um ambiente semelhante, mas distinto da produção, sem precisar se preocupar em enviar mensagens para usuários reais.
Nosso SDK suporta o uso da caixa de areia para push também. O SDK de Klaviyo determinará e armazenará o ambiente ao qual seu token de pressão pertence e comunicará isso ao nosso back -end, permitindo que seus tokens para rotear envios para os ambientes corretos. Não há configuração adicional necessária. Desde que você tenha implantado seu aplicativo na Sandbox com nosso SDK empregado para transmitir tokens push para o nosso back-end, a capacidade de enviar e receber push nesses aplicativos de sandbox deve funcionar fora do caixa.
Começando com a versão 1.7.0, o SDK cache os dados recebidos e os liberará de volta à API Klaviyo em um intervalo. O intervalo é baseado no link de rede atualmente em uso pelo aplicativo. A tabela abaixo mostra o intervalo de descarga usado para cada tipo de conexão:
| Rede | Intervalo |
|---|---|
| WWAN/WIFI | 10 segundos |
| Celular | 30 segundos |
A determinação da conexão é baseada em notificações do nosso serviço de acessibilidade. Quando não houver rede disponível, o SDK cache os dados até que a rede fique disponível novamente. Todos os dados enviados pelo SDK devem estar disponíveis logo após serem descartados pelo SDK.
O SDK tentará repetir solicitações que falhem sob certas condições. Por exemplo, se ocorrer um tempo limite de rede, a solicitação será julgada no próximo intervalo de descarga. Além disso, se o SDK receber um erro de limitação de taxa 429 da API Klaviyo, ele usará o retorno exponencial com o jitter para tentar novamente a próxima solicitação.
Veja o guia contribuinte para aprender a contribuir para o Klaviyo Swift SDK. Congratulamo -nos com seus comentários na seção de problemas do nosso repositório público do GitHub.
Klaviyoswift está disponível sob a licença do MIT. Consulte o arquivo de licença para obter mais informações.
