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

iOS SDK インテグレーションガイド

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

専任のアカウント担当者が、iOS SDK のアカウント設定をサポートします。彼らは、SDK を初期化するために必要な key と secret、および顧客に最も関連性の高い体験を提供するために必要な追加リソースを提供します。

注記

これらの指示を完了するには、開発リソースが必要です。追加のサポートが必要な場合は、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」を「Up to Next Major Version」に変更します。
  4. 右下の「Add Package」ボタンをクリックし、「Package Product」として 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 の代わりに import mParticle_Apple_SDK_NoLocation を使用して 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")
    // データ環境をenvironmentで指定する:
    // 統合をテスト中の場合は.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 {
        //失敗を処理する - 下記の「エラーハンドリング」セクションを参照
    }
}

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

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

3.1 identifyRequestを作成する​

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

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

let identifyRequest = MPIdentityApiRequest.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 = MPIdentityApiRequest.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は、特定のセッションで収集されたユーザー属性を、同じセッションでトリガーされたイベントと関連付けます。

ユーザー属性を収集するには、Rokt 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)

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

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を通じて許可されるさまざまな高度な機能の例も提供します。 callbacks パラメータを通じてRoktに渡される MPRoktEventCallback クラスは、プレースメントの生成および表示時に発生するさまざまなイベントに応答することを可能にします。

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)
注記

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

専任のRoktチームが、あなたのブランドとUXスタイルガイドに合わせて配置レイアウトを設定します。

グローバルイベントAPI​

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

import Rokt_Widget

Rokt.globalEvents() { roktEvent in
    if let initEvent = roktEvent as? RoktEvent.InitComplete {
        print("Rokt init completed with status: \(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 {
        
    }
})
イベント説明パラメータ
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 (オプション)
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で送信されるすべての属性がキャッシュキーとして使用されます。
// 1200秒間エクスペリエンスをキャッシュし、email と orderNumber 属性をキャッシュキーとして使用します。
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. Define the product(s)
let product = MPProduct.init(name: "Double Room",
sku: "econ-1",
quantity: 4,
price: 100.00)

// 2. Summarize the transaction
let attributes = MPTransactionAttributes.init()
attributes.transactionId = "foo-transaction-id"
attributes.revenue = 430.00
attributes.tax = 30.00

// 3. Log the commerce event.
// Several types of "actions" are supported, such as AddToCart and Checkout. This example uses the Purchase product action.
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
この記事は役に立ちましたか？
Last updated Dec 9, 2025