klaviyo swift sdk
4.0.0
Klaviyo Swift SDKを使用すると、開発者はKlaviyoの分析を組み込み、通知機能をiOSアプリケーションにプッシュすることができます。 SDKは、KlaviyoクライアントAPIを介してユーザーを特定し、イベントを追跡するのを支援します。パフォーマンスオーバーヘッドを減らすために、APIリクエストがキューに登録され、バッチで送信されます。キューはローカルストレージに持続し、デバイスがオフラインまたはアプリが終了した場合、データが失われないようにします。
統合されると、マーケティングチームはアプリユーザーのニーズをよりよく理解し、APNSを介してタイムリーなメッセージを送信できます。
Xcodeプロジェクトでプッシュ通知機能を有効にします。このApple開発者ガイドのセクション「プッシュ通知機能を有効にする」では、詳細な指示を提供します。
[オプションですが推奨]リッチプッシュ通知を使用する場合は、Xcodeプロジェクトに通知サービス拡張子を追加します。通知サービスアプリ拡張機能は、iOSアプリ内に別のバンドルとして出荷されます。この拡張機能をアプリに追加するには：
ショ和 通知サービス拡張機能の展開目標は、最新のiOSバージョンにデフォルトです。これがアプリの最小サポートされているiOSバージョンを超える場合、プッシュ通知は古いデバイスに添付のメディアを表示しない場合があります。これを回避するには、拡張機能の最小展開ターゲットがアプリのそれと一致するようにします。ショ和
使用する依存関係マネージャーに基づいて、以下の指示に従ってKlaviyoの依存関係をインストールします。
Klaviyoswiftは、Swift Package Managerから入手できます。以下の手順に従ってインストールしてください。
https://github.com/klaviyo/klaviyo-swift-sdkのURLを入力します。これにより、画面にパッケージが表示されるはずです。KlaviyoSwiftアプリのターゲットに割り当て、 KlaviyoSwiftExtension通知サービス拡張ターゲットに割り当て（作成した場合）、 [パッケージの追加]をクリックします。KlaviyoswiftはCocoapodsから入手できます。
YourAppTargetとYourAppNotificationServiceExtenionTargetをそれぞれアプリと通知サービス拡張目標の名前に置き換えてください。 target 'YourAppTarget' do
pod 'KlaviyoSwift'
end
target 'YourAppNotificationServiceExtenionTarget' do
pod 'KlaviyoSwiftExtension'
endpod install実行して統合を完了します。ライブラリは、 pod update KlaviyoSwiftおよびpod update KlaviyoSwiftExtension介して最新の状態に保つことができます。最後に、 NotificationService.swiftファイルで、このファイルから必要な2つの代表者のコードを追加します。このサンプルは、Klaviyoへの呼び出しをカバーして、プッシュ通知にメディアをダウンロードして添付できるようにします。
SDKは、サイトIDとも呼ばれるKlaviyoアカウントの短い英数字パブリックAPIキーで初期化する必要があります。
// 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は、CreateクライアントプロファイルAPIを介してユーザーをKlaviyoプロファイルとして識別する方法を提供します。プロファイルは、次の任意の組み合わせによって識別できます。
これらの上記の識別子は、イベントリクエストを行うとき、またはプッシュトークンなどを設定するときにSDKが現在のユーザー/プロファイルを追跡できるように、ローカルストレージに持続します。
プロファイル識別子は、一度または個別に設定できます。いずれにせよ、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().resetProfile()呼び出して現在追跡されているプロファイル識別子をクリアするか、 KlaviyoSDK().set(profile: profile)物体。
// 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は、プッシュトークンが設定されているか、イベントが作成されるたびに、自動生成IDで不明確なユーザーを追跡します。そうすれば、電子メールや電話番号などのプロファイル識別子を収集する前に、プッシュトークンを収集してイベントを追跡できます。識別子が提供されると、Klaviyoは匿名のユーザーを識別されたユーザーと統合します。
SDKは、Create Client Event APIを介してユーザーがアプリで実行するイベントを追跡するためのツールを提供します。以下は、イベントを追跡する方法の例です。
// 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として追跡するイベントの名前。一般的なKlaviyo定義されたイベントメトリックのリストは、 Event.EventNameにあります。 CustomEvent Enum Case of Event.EventNameを使用して、カスタムイベントを作成することもできます。properties ：イベントに固有のプロパティの辞書。この引数はオプションです。value ：このイベントに関連付ける数値（ Double ）。たとえば、購入の金額。 ユーザーにプッシュ通知を送信するには、プッシュトークンを収集し、Klaviyoに登録する必要があります。これはKlaviyoSDK().set(pushToken:)メソッドを介して行われます。これは、CreateクライアントプッシュトークンAPIを介してプッシュトークンと現在の承認状態を登録します。
registerForRemoteNotifications()を呼び出して、APNSからプッシュトークンを要求します。これは通常、 application:didFinishLaunchingWithOptions:アプリデリゲートの方法。application:didRegisterForRemoteNotificationsWithDeviceToken in YourアプリケーションデリゲートでAPNからプッシュトークンを受け取り、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 )
}プッシュトークンが取得されたら、次のステップはユーザーにプッシュ通知を送信する許可を要求することです。アプリケーションのどこにでも許可リクエストコードを追加できます。この許可については、ユーザーに促すことが理にかなっています。 Appleは、この許可をいつどのように求めるかについてのベストプラクティスに関するいくつかのガイドラインを提供します。次の例はapplication:didFinishLaunchingWithOptions: Application Delegateファイルのメソッド。ただし、アプリのスタートアップエクスペリエンスを中断できるため、これは理想的な場所ではない可能性があることは注目に値します。
プッシュトークンを設定した後、Klaviyo SDKは、アプリケーションが開きまたはバックグラウンドから再開されるたびに、ユーザーの通知許可の変更を自動的に追跡します。
以下は、プッシュ通知の許可を要求するためのサンプルコードです。
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
}ユーザーがプッシュ通知をタップする場合、 userNotificationCenter:didReceive:withCompletionHandler and userNotificationCenter:willPresent:withCompletionHandlerアプリのプッシュ通知を処理し、それぞれバックグラウンドと前景にある場合にプッシュ通知を処理します。
以下は、アプリの代表者のプッシュ通知を処理する方法の例です。
// 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 ] )
}
}
} [プッシュ通知]を追跡すると、次のコードを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 ( )
}
}さらに、アプリが開かれたときにバッジカウントをゼロにリセットするだけの場合（これは、プッシュメッセージとは無関係にアプリを開くユーザーからのものであることに注意してください）、次のコードを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
}
}最初のプッシュ通知が送信されて開かれたら、Klaviyoダッシュボード内の開いたプッシュメトリックを表示し始める必要があります。
アプリは、以下の手順が機能するために、バージョン1.7.2を最小限に使用する必要があります。
ディープリンクを使用すると、ユーザーがプッシュ通知を開くことに応じて、アプリ内の特定のページに移動できます。
アプリにディープリンクを設定して、動作する必要があります。 Klaviyoの構成プロセスは、一般的な深いリンクを処理するために必要なものと変わらないため、ここに概説されているステップと併せて深いリンクのためにAppleドキュメントに従うことができます。
深いリンクを実装するための2つのオプションがあります：URLスキームとユニバーサルリンク。
URLスキームは、プッシュ通知からアプリに深くリンクする伝統的でシンプルな方法です。ただし、これらのリンクは、モバイルアプリがデバイスにインストールされている場合にのみ機能し、たとえばメールからアプリにリンクする場合はWebブラウザーでは理解されません。
Appleがアプリケーションへの深いリンクをルーティングするには、アプリケーションのinfo.plistファイルにURLスキームを登録する必要があります。これは、XCodeがプロジェクト設定の情報タブから提供するエディタを使用して、またはinfo.plistを直接編集して実行できます。
必要なフィールドは次のとおりです。
info.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: Method in使いのメソッド。
例：
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を使用している場合は、Deep Linksを処理しようとするビューでView ModifierとしてonOpenURL(perform:)実装できます。これはあなたのシーンの根源であるかもしれません。
例：
@ main
struct MyApplication : App {
var body : some Scene {
WindowGroup {
ContentView ( )
. onOpenURL { url in
// handle the URL that must be opened
}
}
}
}最後に、SDKリポジトリにアプリ（ Examples/KlaviyoSwiftExamples ）の例があり、アプリにディープリンクを実装する方法の例を取得するために参照できます。
上記の手順が完了したら、Klaviyo Webサイト内のKlaviyo Push Editorからプッシュ通知を送信できます。ここでは、Klaviyoを介してプッシュ通知を構築して送信して、ステップ3で実装したハンドラーにURLが表示されることを確認できます。
さらに、ディープリンクをローカルでトリガーして、端末の以下のコマンドを使用してコードが機能していることを確認することもできます。
xcrun simctl openurl booted {your_URL_here}
ユニバーサルリンクは、深いリンクを処理するためのより近代的な方法であり、Appleが推奨しています。より安全で、より良いユーザーエクスペリエンスを提供します。ただし、URLスキームとは異なり、これらのAppleドキュメントで強調されているもう少しセットアップが必要です。
Apple Docsからのセットアップを設定したら、以下に説明するようにプッシュオープントラッキングを変更する必要があります。
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スキームで説明されているように実装します。
リッチプッシュ通知は、SDKバージョン2.2.0以上でサポートされています
Rich Pushは、通知メッセージをプッシュするために画像を追加する機能です。インストールセクションの手順が完了したら、 KlaviyoSwiftExtensionのコードを使用してプロジェクトのセットアップに通知サービス拡張機能を設定する必要があります。以下は、リッチプッシュ通知をテストする方法に関する指示です。
{
"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 "
}AppDelegateのdidRegisterForRemoteNotificationsWithDeviceTokenとともにコンソールに印刷できます。これらの3つのものを取得したら、プッシュ通知テスターを使用して、ローカルプッシュ通知を送信して、すべてが正しくセットアップされることを確認できます。
サンドボックスサポートはSDKバージョン2.2.0以降で利用できます
Appleには、プッシュ通知サポートの2つの環境があります - 生産とサンドボックス。制作環境は、アプリがApp StoreまたはTestFlightで公開されている場合、実際のユーザーにプッシュ通知を送信することをサポートします。対照的に、プッシュ通知をサポートするサンドボックスアプリケーションは、iOS配布証明書の代わりに、iOS開発証明書で署名されたものです。 Sandboxはステージング環境として機能し、実際のユーザーにメッセージを送信することを心配することなく、生産とは異なるが、環境でアプリケーションをテストすることができます。
当社のSDKは、プッシュのためにサンドボックスの使用もサポートしています。 KlaviyoのSDKは、プッシュトークンが属する環境を決定して保存し、それをバックエンドに伝え、トークンが正しい環境に送信できるようにします。追加のセットアップは必要ありません。 Push Tokenをバックエンドに送信するためにSDKを使用してSandboxにアプリケーションを展開している限り、これらのSandboxアプリケーションを送信および受信する機能は、すぐに機能するはずです。
バージョン1.7.0から始めて、SDKは着信データをキャッシュし、間隔でKlaviyo APIに戻します。間隔は、アプリが現在使用しているネットワークリンクに基づいています。以下の表は、各タイプの接続に使用されるフラッシュ間隔を示しています。
| ネットワーク | 間隔 |
|---|---|
| WWAN/WIFI | 10秒 |
| 携帯電話 | 30秒 |
接続の決定は、到達可能性サービスからの通知に基づいています。使用可能なネットワークがない場合、SDKはネットワークが再び利用可能になるまでデータをキャッシュします。 SDKから送信されたすべてのデータは、SDKによってフラッシュされた直後に利用できるようにする必要があります。
SDKは、特定の条件下で失敗するAPI要求を再試行します。たとえば、ネットワークタイムアウトが発生した場合、次のフラッシュ間隔でリクエストが再試行されます。さらに、SDKがKlaviyo APIからレート制限エラー429受信した場合、ジッターで指数関数的バックオフを使用して次のリクエストを再試行します。
Klaviyo Swift SDKに貢献する方法を学ぶための寄稿ガイドを参照してください。 Public Githubリポジトリの問題セクションでフィードバックを歓迎します。
Klaviyoswiftは、MITライセンスの下で入手できます。詳細については、ライセンスファイルを参照してください。
