メインコンテンツまでスキップ

iOS SDK 統合ガイド

このページでは、Rokt EcommerceのiOS SDKを実装して、チェックアウト時により関連性の高い顧客体験を提供する方法を説明します。SDKは、設定されたページでトリガーを発動し、ユーザーおよびトランザクションデータをRoktに渡してパーソナライズと測定を可能にすることで、こうした体験をトリガーおよび追跡します（確認ページ上でのオファーの表示など）。

担当のアカウント代表者が、iOS SDK用にアカウントを設定するお手伝いをします。SDKを初期化するために必要なキーとシークレット、およびお客様に最も関連性の高い体験を表示するために必要な追加リソースを提供します。

注記

これらの手順を完了するには開発リソースが必要です。追加の支援が必要な場合は、Roktのアカウントマネージャーにお問い合わせください。Shopifyストアでは、Rokt Ecommerceアプリを使用して数秒でRokt配置を設定できます—コーディングは不要です！

1. iOSアプリにRokt SDKを追加する​

SPMまたはCocoaPodsのいずれかを使用して、Rokt SDKをアプリケーションに含めます:

CocoaPods​

CocoaPodsを使用してSDKを統合するには、Podfileに以下を指定してください:

pod 'mParticle-Apple-SDK', '~> 8.0'
pod 'mParticle-Rokt','~> 8.0'

SPM​

Swift Package Managerを使用してSDKを統合するには:

  1. Xcodeでプロジェクトを開き、「Package Dependencies」タブに移動します。
  2. パッケージリストの下にある**+**ボタンをクリックします。
  3. 右上の検索ボックスにリポジトリURL https://github.com/mParticle/mparticle-apple-sdk を入力し、パッケージ一覧から mparticle-apple-sdk を選択し、「Dependency Rule」を「アップ・トゥ・ネクスト・メジャー・バージョン」に変更します。
  4. 右下の「Add Package」ボタンをクリックし、「パッケージ製品」として mParticle-Apple-SDK を選択します。位置情報追跡サポートを含まないSDKバージョンを使用したい場合は、mParticle-Apple-SDK-NoLocation を選択します。
  5. Rokt KitリポジトリURL https://github.com/mparticle-integrations/mparticle-apple-integration-rokt.git についてもステップ3と4を繰り返します。
    • mParticle-Apple-SDK-NoLocation パッケージ製品を選択した場合は、import mParticle_Apple_SDK_NoLocation を使用してSDKをインポートする必要があります。import mParticle_Apple_SDK の代わりに使用します。

2. Rokt SDK の初期化​

SDK を初期化するには、AppDelegate ファイルに次の初期化スニペットを挿入します:

注意
  • your-key と your-secret は、専任の Rokt チームから提供されたキーとシークレットに置き換えてください。
import mParticle_Apple_SDK

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    // SDK を初期化
    let options = MParticleOptions(key: "your-key",
    secret: "your-secret")
    // データ環境を指定してください:
    // 統合テスト中の場合は .development に設定します。
    // 生産データに対応する統合が準備できたら .production に設定します。
    // デフォルトは .autoDetect で、環境を自動的に検出しようとします
    options.environment = .development
    // 現在のユーザーを識別:
    let identifyRequest = MPIdentityApiRequest.withEmptyUser()
    // 未ハッシュのメールアドレスを使用している場合は 'email' に設定します。
    identifyRequest.email = "j.smith@example.com"
    // ユーザーがメールアドレスで識別される場合は、追加属性を設定します。
    options.identifyRequest = identifyRequest
    options.onIdentifyComplete =  {(result: MPIdentityApiResult?, error: Error?) in
    if let user = result?.user {
        user.setUserAttribute("example attribute key", value: "example attribute value")
    } else {
        //失敗処理 - 下記の「エラーハンドリング」セクションを参照
    }
}
    MParticle.sharedInstance().start(with: options)
    return true
}

2.1 初期化時にユーザーを識別する​

SDKが初期化されると、現在のユーザーを識別することができ、収集されたデータが正確にユーザーに帰属し、ユーザーの行動に基づいて最も関連性の高い広告が表示されるようにします。

SDK初期化スクリプトには、identifyRequestというオブジェクトが含まれます:

let identifyRequest = MPIdentityApiRequest.withEmptyUser()
identifyRequest.email = "j.smith@example.com"
options.identifyRequest = identifyRequest

2.2 追加のユーザー属性を設定​

初期化スクリプトには、ユーザーがメールアドレスで正常に識別された場合に、追加のユーザー属性を設定することを許可するコールバック関数が含まれています:

options.onIdentifyComplete =  {(result: MPIdentityApiResult?, error: Error?) in
    if let user = result?.user {
        user.setUserAttribute("example attribute key", value: "example attribute value")
    } else {
        //handle failure - see "Error Handling" section below
    }
}

3. データが利用可能になったときにユーザーを識別する​

SDKを初期化した後にユーザーがメールアドレスを提供するたびに（例：ログインまたは購入時）、identify メソッドを呼び出して Rokt にメールを渡す必要があります。これにより、データが現在のユーザーに正しく帰属されることが保証されます。

3.1 identifyRequest を作成する​

ユーザーを識別するには、まずユーザーのメールアドレスを含む identifyRequest オブジェクトを作成します。

ハッシュ化されていないメールアドレスを提供する場合は、以下を使用してください：

let identifyRequest = MPIdentifyApiRequest.withEmptyUser()
identifyRequest.email = "j.smith@example.com"

3.2 追加のユーザー属性を設定する​

次に、コールバック関数を作成してユーザーを識別する際に追加のユーザー属性を設定するオプションがあります。identifyRequest が成功した場合、setUserAttribute で設定したユーザー属性がユーザーに割り当てられます。

let identifyCallback = {(result: MPIdentifyApiResult?) in
    if let user = result?.user {
        user.setUserAttribute("example attribute key", value: "example attribute value")
    }
}

3.3 identify メソッドを呼び出す​

最後に、identifyRequest と identityCallback を作成した後、追加の属性を設定するために、作成した identifyRequest と identityCallback オブジェクトを渡して identify メソッドを呼び出します。

MParticle.sharedInstance().identity.identify(identifyRequest, completion: identityCallback)

例えば、Jane Smith という名前のユーザーを j.smith@example.com というメールアドレスで識別する場合（メールアドレスのハッシュ化は必要ありません）、以下のように使用します。

let identifyRequest = MPIdentifyApiRequest.withEmptyUser()
identifyRequest.email = "j.smith@example.com"

let identifyCallback = {(result: MPIdentifyApiResult?) in
    if let user = result?.user {
        user.setUserAttribute("example attribute key", value: "example attribute value")
    }
}

MParticle.sharedInstance().identity.identify(identifyRequest, completion: identityCallback)

4. ユーザー属性の追跡​

Rokt SDK を使用して、イベントとは別にユーザー属性を収集できます。ユーザー属性は、イベントを追跡する際のカスタム属性とは別扱いです。SDK は、あるセッションで収集されたユーザー属性を、同じセッション内でトリガーされたイベントと関連付けます。

ユーザー属性を収集するには、Adjust SDK を初期化した直後、すぐに以下のコードをアプリ内で実行し、イベントを記録する前に行います。

import mParticle_Apple_SDK

// 現在のユーザーを取得します。これは、SDK の初期化時にユーザーを識別した場合、または identify メソッドを呼び出した場合にのみ成功します。
let currentUser = MParticle.sharedInstance().identity.currentUser

// `currentUser` に現在のユーザーを正常に設定した後、次のようにユーザー属性を設定できます:
currentUser?.setUserAttribute("custom-attribute-name", value: "custom-attribute-value")
// 注意: すべてのユーザー属性（リスト属性やタグを含む）は、異なる名称を持たなければなりません。

// Rokt は、可能な限り次のユーザー属性を設定することをお勧めします:
currentUser?.setUserAttribute("firstname", value: "John")
currentUser?.setUserAttribute("lastname", value: "Doe")
// 電話番号は '1234567890'、または '+1 (234) 567-8901' のいずれかの形式でフォーマットできます
currentUser?.setUserAttribute("mobile", value: "3125551515")
currentUser?.setUserAttribute("age", value: "33")
currentUser?.setUserAttribute("gender", value: "M")
currentUser?.setUserAttribute("city", value: "Brooklyn")
currentUser?.setUserAttribute("state", value: "NY")
currentUser?.setUserAttribute("zip", value: "123456")
currentUser?.setUserAttribute("dob", value: "yyyymmdd")
currentUser?.setUserAttribute("title", value: "Mr")
currentUser?.setUserAttribute("language", value: "en")
currentUser?.setUserAttribute("value", value: "52.25")
currentUser?.setUserAttribute("predictedltv", value: "136.23")

// ユーザー属性を作成して、値のリストを含めることができます
currentUser?.setUserAttributeList("favorite-genres", values: ["documentary", "comedy", "romance", "drama"])

// ユーザー属性を削除するには、removeUserAttribute メソッドを呼び出し、属性名を渡します。すべてのユーザー属性は同じキー空間を共有します。
currentUser?.removeAttribute("attribute-to-remove")

5. ファネルイベントのキャプチャ​

Rokt SDKを使用すると、ユーザーのアプリ内での移動経路を説明するデータを収集するイベントトラッキングを実装できます。このデータを使用して、ユーザーの体験を最適化することができます。

SDKで記録できる主なイベントタイプは次の3つです。

  • スクリーンビューイベント: これはアプリのページがロードされたときにトリガーできるイベントです。
  • カスタムイベント: アプリに特有の情報を追跡するために作成する自由形式のイベントです。
  • コマースイベント: これは、ショッピングカートへのアイテム追加や最終購入など、ショッピング体験のさまざまな段階を説明できる、eコマースに特化したイベントです。

最初にRokt SDKと統合する際は、スクリーンビューのトラッキングの実装から始めます。カスタムイベントとコマースイベントのトラッキングについて学ぶには、付録を参照してください。

スクリーンビューのトラッキング​

最も基本的なイベントタイプの1つはスクリーンビューです。スクリーンビューを記録するには、.logScreenメソッドを呼び出し、画面の名前を文字列として渡します。 渡す名前は、'homepage' や 'product detail page' のような限定されたページセットの1つであるべきです。また、eventInfo 配列に追加のカスタム属性を含めることもできます。

MParticle.sharedInstance().logScreen(
"homepage",
eventInfo: ["custom-attribute": custom-value]
)

## 6. プレースメントを表示する

Rokt SDK の主な価値は、selectPlacements メソッドによって解放されます。これは、提供された属性に基づいて、顧客に非常に関連性の高いプレースメント（またはレイアウト）を提供します。

Rokt の統合が初期化されたら、レイアウトをレンダリングするページから selectPlacements メソッドを呼び出すことができます。これは、可能な限り早く、必要なすべての属性が利用可能になった時点で呼び出されるべきです。これにより、ユーザーにとって最良の体験を保証します。

selectPlacements を呼び出す際には、ユーザーに最も関連性の高いプレースメントを提供するために、少なくとも email、firstname、lastname、billingzipcode、confirmationref の属性を提供する必要があります。

オーバーレイプレースメント​

import mParticle_Apple_SDK
let attributes = [
    "email": "test@gmail.com",
    "firstname": "Jenny",
    "lastname": "Smith",
    "billingzipcode": "07762",
    "confirmationref": "54321"
]

MParticle.sharedInstance().rokt.selectPlacements("RoktExperience", attributes: attributes)

また、アプリがダークモードかライトモードかに主に依存するプレースメントUIをカスタマイズするためのMPRoktConfigなどのオプションパラメーターを渡すことをお勧めします。埋め込みビューやコールバックなどの追加のオプションパラメーターは、以下に示されています。

let roktConfig = MPRoktConfig()
roktConfig.colorMode = .light

MParticle.sharedInstance().rokt.selectPlacements("RoktExperience", attributes: attributes, embeddedViews: nil, callbacks: nil, config: roktConfig)
注記

識別子 RoktExperience または埋め込み識別子 RoktEmbedded1 を別の値で更新したい場合は、Roktアカウントマネージャーに連絡して、Roktプレースメントが一貫して構成されていることを確認してください。

オプション機能​

機能目的
Rokt.close()オーバーレイ配置を自動的に閉じるために使用されます。

埋め込み配置​

埋め込み配置は、上記のオーバーレイ配置と同じ推奨事項と要件を共有しますが、配置ビューをUIに埋め込むことができます。また、このセクションを使用して、Roktを通じて許可されているさまざまな高度な機能の例を提供します。MPRoktEventCallback クラスは、callbacks パラメーターを介してRoktに渡され、配置を生成および表示する際に発生するさまざまなイベントに応答することができます。

import mParticle_Apple_SDK

let attributes = [
    "email": "test@gmail.com",
    "firstname": "Jenny",
    "lastname": "Smith",
    "billingzipcode": "07762",
    "confirmationref": "54321"
]

let roktFrame = CGRect(x: 0, y: 0, width: 320, height: 50)
let roktView = MPRoktEmbeddedView(frame: roktFrame)
let embeddedViews = ["RoktEmbedded1": roktView]

let roktConfig = MPRoktConfig()
roktConfig.colorMode = .light

let callbacks = MPRoktEventCallback()
callbacks.onLoad = {
    // Rokt配置がロードされたときのオプションのコールバック
}
callbacks.onUnLoad = {
    // Rokt配置がアンロードされたときのオプションのコールバック
}
callbacks.onShouldShowLoadingIndicator = {
    // ローディングインジケーターを表示するためのオプションのコールバック
}
callbacks.onShouldHideLoadingIndicator = {
    // ローディングインジケーターを隠すためのオプションのコールバック
}
callbacks.onEmbeddedSizeChange = { (placement: String, size: CGFloat) in
    // 選択された配置と、その高さが変わるたびに配置が必要とする高さを取得するためのオプションのコールバック
}

MParticle.sharedInstance().rokt.selectPlacements("RoktExperience", attributes: attributes, embeddedViews: embeddedViews, config: roktConfig, callbacks: callbacks)
注記

サポートされている属性の完全なリストについては、Data Attributesを参照してください。

あなた専用のRoktチームがブランドとUXスタイルガイドに合わせてプレースメントレイアウトを構成します。

グローバルイベント API​

SDK は Rokt.globalEvents API を通じて SDK のステータスを提供します。

import Rokt_Widget

Rokt.globalEvents() { roktEvent in
    if let initEvent = roktEvent as? RoktEvent.InitComplete {
        print("Rokt の初期化が次のステータスで完了: \(initEvent.success)")
    }
}

イベント API​

SDK は Rokt.events API を通じて各ビューのイベントとステータスを提供します。

import mParticle_Apple_SDK

MParticle.sharedInstance().rokt.events("RoktLayout", onEvent: { roktEvent in
    if let event = roktEvent as? MPRoktEvent.MPRoktShowLoadingIndicator {

    } else if let event = roktEvent as? MPRoktEvent.MPRoktHideLoadingIndicator {
        
    } else if let event = roktEvent as? MPRoktEvent.MPRoktPlacementInteractive {
        
    } else if let event = roktEvent as? MPRoktEvent.MPRoktPlacementReady {
        
    } else if let event = roktEvent as? MPRoktEvent.MPRoktOfferEngagement {
        
    } else if let event = roktEvent as? MPRoktEvent.MPRoktOpenUrl {
        
    } else if let event = roktEvent as? MPRoktEvent.MPRoktPositiveEngagement {
        
    } else if let event = roktEvent as? MPRoktEvent.MPRoktPlacementClosed {
        
    } else if let event = roktEvent as? MPRoktEvent.MPRoktPlacementCompleted {
        
    } else if let event = roktEvent as? MPRoktEvent.MPRoktPlacementFailure {
        
    } else if let event = roktEvent as? MPRoktEvent.MPRoktFirstPositiveEngagement {
        
    } else if let event = roktEvent as? MPRoktEvent.MPRoktCartItemInstantPurchase {
        
    }
})
Event説明パラメータ
MPRoktShowLoadingIndicatorSDK が Rokt バックエンドを呼び出す前にトリガーされる
MPRoktHideLoadingIndicatorSDK が Rokt バックエンドから成功または失敗を受信したときにトリガーされる
MPRoktPlacementInteractiveプレースメントがレンダーされ、インタラクティブになったときにトリガーされるplacementId: String
MPRoktPlacementReadyプレースメントが表示する準備ができているが、まだコンテンツがレンダーされていないときにトリガーされるplacementId: String
MPRoktOfferEngagementユーザーがオファーにエンゲージしたときにトリガーされるplacementId: String
MPRoktOpenUrl設定された URL をユーザーが押してパートナーアプリに送信されるようにトリガーされるplacementId: String, url: String
MPRoktPositiveEngagementユーザーがオファーに肯定的に関与したときにトリガーされますplacementId: String
MPRoktPlacementClosedユーザーによってプレースメントが閉じられたときにトリガーされますplacementId: String
MPRoktPlacementCompletedオファーの進行が終了し、表示するオファーがもうないときにトリガーされます。
キャッシュがヒットした場合でも、前回却下されたために取得したプレースメントが表示されないときにもトリガーされます		placementId: String
MPRoktPlacementFailure何らかの障害のためにプレースメントを表示できないとき、または表示するプレースメントがないときにトリガーされますplacementId: String (optional)
MPRoktFirstPositiveEngagementユーザーがオファーに初めて肯定的に関与したときにトリガーされますplacementId: String, setFulfillmentAttributes: func (attributes: [String: String])
MPRoktCartItemInstantPurchaseプレースメントを通じて購入が行われたときにトリガーされますplacementId: String, name: String?, cartItemId: String, catalogItemId: String, currency: String, description: String, linkedProductId: String?, providerData: String, quantity: NSDecimalNumber?, totalPrice: NSDecimalNumber?, unitPrice: NSDecimalNumber?

付録​

デバッグ​

SDKを初期化する際に、次の設定オプションを設定することでデバッグログを有効にできます。

Rokt.setLoggingEnabled(enable: true)

上記の手順に従ってプレースメントと画面ビューのトラッキングを実装した後、追加のイベントトラッキングを実装したい場合があります。

アプリ構成の使用​

アプリケーションは、独自のアプリケーション環境から構成設定を送信できるようになりました。これにより、iOS SDKはシステムのデフォルトに頼るだけでなく、アプリケーションのカスタム構成を使用できるようになります。

ColorMode オブジェクト​
値説明
lightアプリケーションがライトモードである
darkアプリケーションがダークモードである
systemアプリケーションがシステムのカラーモードにデフォルトする
// アプリケーションがライトモードのみをサポートする場合。
let roktConfig = MPRoktConfig()
roktConfig.colorMode = .light

MParticle.sharedInstance().rokt.selectPlacements("RoktExperience", attributes: attributes, embeddedViews: nil, callbacks: nil, config: roktConfig)

CacheConfig オブジェクト​

パラメータ説明
cacheDurationRokt SDK がエクスペリエンスをキャッシュする時間のオプションの TimeInterval。最大許可時間は90分であり、（値が提供されないか無効な場合の）デフォルトは90分です。
cacheAttributesキャッシュキーとして使用するオプションの属性。nullの場合、Rokt.executeで送信されるすべての属性がキャッシュキーとして使用されます。
// emailとorderNumberの属性をキャッシュキーとして、1200秒間エクスペリエンスをキャッシュする。
let roktConfig = MPRoktConfig()
roktConfig.cacheDuration = TimeInterval(1200)
roktConfig.cacheAttributes = ["email": "j.smith@example.com", "orderNumber": "123"]

MParticle.sharedInstance().rokt.selectPlacements("RoktExperience", attributes: attributes, embeddedViews: nil, callbacks: nil, config: roktConfig)

SwiftUI サポートと MPRoktLayout​

アプリが主に SwiftUI で書かれている場合、iOS アプリで Rokt プレースメントを統合するためのよりモダンな宣言的アプローチとして MPRoktLayout コンポーネントを提供しています。

MPRoktLayout クラスは、selectPlacements を手動で呼び出すことなく、Rokt プレースメントを表示するための SwiftUI 互換の方法を提供し、オーバーレイと埋め込みの両方のプレースメントタイプをサポートします。

SwiftUI コンポーネントの追加​
import SwiftUI
import mParticle_Apple_SDK
import mParticle_Rokt_Swift

struct OrderConfirmationView: View {
    let attributes = [
        "email": "test@gmail.com",
        "firstname": "Jenny",
        "lastname": "Smith",
        "billingzipcode": "07762",
        "confirmationref": "54321"
    ]
    
    @State private var sdkTriggered = true
    
    var body: some View {
        VStack(alignment: .leading) {
            // 他のUIコンポーネント
            Text("Order Confirmation")
                .font(.title)
            
            // SwiftUIを使用したRoktプレースメント
            MPRoktLayout(
                sdkTriggered: $sdkTriggered,
                viewName: "RoktExperience",
                locationName: "RoktEmbedded1", // 埋め込みプレースメント用
                attributes: attributes,
                config: roktConfig, // オプション MPRoktConfig
                onEvent: { roktEvent in
                    // オプション: 異なるイベントタイプの処理、上記参照
                }
            ).roktLayout
        }
        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
    }
}
パラメータ​
パラメータ型説明
sdkTriggeredBool配置をトリガーするタイミングを制御します
viewNameStringRokt ビュー/エクスペリエンスの名前 (例: "RoktExperience")
locationNameString?埋め込み配置のオプションの場所名 (例: "RoktEmbedded1")
attributes[String: String]配置に渡す属性のディクショナリー
configMPRoktConfig?色モード、キャッシングなどのオプションの設定オブジェクト
onEvent((MPRoktEvent) -> Void)?すべての配置イベントを処理するためのオプションのコールバック

カスタムイベントをトラッキングする​

logEvent を呼び出してイベント名、イベントタイプ、およびイベントのための任意のカスタム属性を含む配列を渡すことで、カスタムイベントを定義し追跡できます。

if let event = MPEvent(name: "Video Watched", type: .navigation) {
    event.customAttributes = ["category": "Destination Intro", "title": "Paris"]
    MParticle.sharedInstance().logEvent(event)
}

サポートされているカスタムイベントタイプは次のとおりです:

  • navigation - ユーザーのナビゲーションフローやページ遷移を追跡
  • location - ユーザーの位置情報に基づいたインタラクションや動きを記録
  • search - 検索クエリや検索関連のユーザーアクションをキャプチャ
  • transaction - 金銭取引や購入関連のアクティビティを記録
  • userContent - レビュー、コメント、投稿などのユーザー生成コンテンツを追跡
  • userPreference - ユーザー設定、好み、カスタマイズの選択を記録
  • social - ソーシャルメディアのインタラクションや共有アクティビティをキャプチャ

コマースイベントをトラッキングする​

コマースイベントをトラッキングするには3つのステップがあります:

  1. 購入する商品を一つの変数内でMPProduct.initを使用して定義する
  2. トランザクションを要約するためのMPTransactionAttributesオブジェクトを作成する
  3. 商品アクションとイベントのタイプを定義し、商品定義とトランザクションの要約を含むlogEventメソッドを呼び出す
// 1. 商品を定義する
let product = MPProduct.init(name: "Double Room",
sku: "econ-1",
quantity: 4,
price: 100.00)

// 2. トランザクションを要約する
let attributes = MPTransactionAttributes.init()
attributes.transactionId = "foo-transaction-id"
attributes.revenue = 430.00
attributes.tax = 30.00

// 3. コマースイベントをログに記録する。
// AddToCartやCheckoutなど、いくつかの「アクション」の種類がサポートされています。この例はPurchaseの製品アクションを使用しています。
let action = MPCommerceEventAction.purchase;
let event = MPCommerceEvent.init(action: action, product: product)
event.transactionAttributes = attributes
MParticle.sharedInstance().logEvent(event)

製品アクションをログに記録する場合は、次の製品アクションタイプのいずれかを指定する必要があります:

  • AddToCart
  • RemoveFromCart
  • Checkout
  • CheckoutOption
  • Click
  • ViewDetail
  • Purchase
  • Refund
  • AddToWishlist
  • RemoveFromWishlist
  • Unknown
この記事は役に立ちましたか？