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

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

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

専任のアカウント担当者が、Flutter アプリでターゲットにしているプラットフォーム用にアカウントを設定するお手伝いをします。彼らは、SDK を初期化するために必要な key (iOS/Android/Web) と secret (iOS/Android) の両方、および顧客に最も関連性の高い体験を提供するために必要な追加リソースを提供します。

注記

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

1. Flutter セットアップ​

Flutter アプリケーションに Flutter SDK を依存関係として追加します:

flutter pub add mparticle_flutter_sdk

Rokt Flutter SDK 依存関係をアプリケーションに追加した後、次の（または類似の）行がパッケージの pubspec.yaml ファイルに追加されます:

dependencies:
    mparticle_flutter_sdk: ^1.1.0

Dart コードにパッケージをインポートし、mParticle のインスタンスを取得します:

import 'package:mparticle_flutter_sdk/mparticle_flutter_sdk.dart';

MparticleFlutterSdk? mpInstance = await MparticleFlutterSdk.getInstance();

Dart プラグインをインストールした後、以下の手順に従って Rokt SDK をモバイルアプリまたはウェブサイトに統合し続けます。アプリまたはサイトを起動する際にログにエラーが表示されないように、アカウントマネージャーから提供された key と secret を必要な場所に必ず含めてください。

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

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

CocoaPods​

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

ios/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_NoLocation を使用してSDKをインポートする必要があります。

1.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
    MParticle.sharedInstance().start(with: options)
    return true
}

追加セットアップ​

詳細なヘルプについては、完全なiOS SDK 統合ガイドを参照してください。

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

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

ユーザー属性を収集するには、Rokt SDKを初期化した直後に、イベントをログに記録する前に次のコードを実行する必要があります。

import 'package:mparticle_flutter_sdk/mparticle_flutter_sdk.dart';

// 現在のユーザーを取得します。これは、SDKの初期化時またはidentifyメソッドを呼び出すことでユーザーを識別した場合にのみ成功します。
var currentUser = await mpInstance?.getCurrentUser();

// 現在のユーザーを`currentUser`に設定した後、次のようにユーザー属性を設定できます:
currentUser?.setUserAttribute('custom-attribute-name', 'custom-attribute-value');
// 注意: すべてのユーザー属性（リスト属性やタグを含む）は、異なる名前を持つ必要があります。

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

// 複数の値を含むユーザー属性を作成することができます
var attributeList = <String>[];
attributeList.add('documentary');
attributeList.add('comedy');
attributeList.add('romance');
attributeList.add('drama');
currentUser?.setUserAttributeArray(key: 'favorite-genres', value: attributeList);

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

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

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

SDKで記録できる主なイベントタイプは3つあります：

  • スクリーンビューイベント (Screen View Events): これらは、アプリの画面が読み込まれたときにトリガーできるイベントです。
  • カスタムイベント (Custom Events): これらは、アプリ固有の情報を追跡するために作成する自由形式のイベントです。
  • コマースイベント (Commerce Events): これらは、ショッピング体験のさまざまな段階を説明できるeコマース特有のイベントで、カートへのアイテム追加や最終購入を含みます。

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

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

トラッキングできる最も基本的なイベントタイプの1つがスクリーンビューです。スクリーンビューをログに記録するには、画面が読み込まれるとすぐにmpInstance?.logScreenEvent()メソッドを呼び出し、画面の名前を文字列として渡し、必要に応じて説明的な属性を含むハッシュマップを渡します。

渡す名前は、'homepage'や'product detail page'のような限られたセットの画面の1つであるべきです。

import 'package:mparticle_flutter_sdk/events/screen_event.dart';

var screenInfo = {
    'rating': '5',
    'property_type': 'hotel'
};

ScreenEvent screenEvent = ScreenEvent(eventName: 'Details')
  ..customAttributes = screenInfo;
mpInstance?.logScreenEvent(screenEvent);

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

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

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

selectPlacements を呼び出す際には、少なくとも email、firstname、lastname、billingzipcode、および confirmationref 属性を提供する必要があります。

final attributes = {
    "email": "j.smith@example.com",
    "firstname": "Jenny",
    "lastname": "Smith",
    "mobile": "(555)867-5309",
    "postcode": "90210",
    "country": "US"
};

// プレースメントにカスタムフォントを使用したい場合、fontTypefaces マップを作成します
final fontTypefaces = {"Arial-Bold": "fonts/Arial-Bold.ttf"};

// また、アプリがダークモードまたはライトモードにあるかどうかを主にカスタマイズするための `RoktConfig` などのオプションのパラメータを渡すこともできます。埋め込みビューやイベントなどの追加のオプションパラメータは下に示されています。
final roktConfig = RoktConfig(
    colorMode: ColorMode.light
);

mpInstance?.rokt.selectPlacements(
    identifier: "RoktExperience",
    attributes: attributes,
    fontFilePathMap: fontTypefaces,
    roktConfig: roktConfig
);

オプション機能​

埋め込みプレースメント​

埋め込みプレースメントは、上記のオーバーレイプレースメントと同じ推奨事項と要件を共有しますが、プレースメントビューをUIに埋め込むことができます。

RoktLayoutには、ウィジェットが作成されたときに通知するコールバックがあります。

import 'package:mparticle_flutter_sdk/mparticle_flutter_sdk.dart';

const RoktLayout(
    placeholderName: "RoktEmbedded1",
    onLayoutCreated: () {
        // レイアウトが作成されました
    }
);

イベント​

SDKは、各ページのイベントをMPRoktEvents EventChannelを通じてストリームとして提供します。

final EventChannel roktEventChannel = EventChannel('MPRoktEvents');
roktEventChannel.receiveBroadcastStream().listen((dynamic event) {
    debugPrint("rokt_event: _receiveRoktEvent $event ");
});
イベント説明パラメータ
ShowLoadingIndicatorSDKがRoktバックエンドを呼び出す前にトリガーされます
HideLoadingIndicatorSDKがRoktバックエンドから成功または失敗を受信したときにトリガーされます
OfferEngagementユーザーがオファーに関与したときにトリガーされますplacementId: String
PositiveEngagementユーザーがオファーに対して積極的に関与したときにトリガーされますplacementId: String
FirstPositiveEngagementユーザーが初めてオファーに対して積極的に関与したときにトリガーされますplacementId: String, fulfillmentAttributes: FulfillmentAttributes
PlacementInteractiveプレースメントがレンダリングされ、対話可能になったときにトリガーされますplacementId: String
PlacementReadyプレースメントが表示準備ができたが、まだコンテンツがレンダリングされていないときにトリガーされますplacementId: String
PlacementClosedユーザーによってプレースメントが閉じられたときにトリガーされますplacementId: String
PlacementCompletedオファーの進行が終了し、表示するオファーがなくなったときにトリガーされます。
また、キャッシュがヒットしたが、取得されたプレースメントが以前に却下されたため表示されない場合にもトリガーされます		placementId: String
PlacementFailure何らかの失敗によりプレースメントを表示できない場合、または表示するプレースメントがない場合にトリガーされますplacementId: String (オプション)
OpenUrlユーザーがパートナーアプリに送信するように設定されたURLを押したときにトリガーされますplacementId: String, url: String

付録​

アプリケーション設定の使用​

アプリケーションは、独自のアプリケーション環境から設定を渡すことができるようになりました。これにより、Rokt SDK はシステムのデフォルトに依存せず、アプリケーションのカスタム設定を使用することができます。

ColorMode オブジェクト​
値説明
lightアプリケーションはライトモードです
darkアプリケーションはダークモードです
systemアプリケーションはシステムのカラーモードをデフォルトとします
CacheConfig オブジェクト​
注記

CacheConfig はモバイル統合にのみ関連し、ウェブでは無視できます。

パラメータ説明
cacheDurationRokt SDK がエクスペリエンスをキャッシュする秒単位のオプションの期間です。許可される最大値は90分で、デフォルト（値が提供されていないか無効な場合）は90分です。
cacheAttributesキャッシュキーとして使用するオプションの属性です。null の場合、selectPlacements で送信されたすべての属性がキャッシュキーとして使用されます。
final roktConfig = RoktConfig(
    cacheConfig: CacheConfig(
        cacheDurationInSeconds: 100,
        cacheAttributes: attributes
    )
);

mpInstance?.rokt.selectPlacements(
    identifier: "RoktExperience",
    attributes: attributes,
    roktConfig: roktConfig
);

カスタムイベントのトラッキング​

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

MPEvent.Builder オブジェクトを使用して、イベント名、イベントタイプ、およびカスタム属性のマップを渡すことで、カスタムイベントを定義してトラッキングできます。

Kotlin および Java でサポートされているカスタムイベントタイプは以下の通りです：

  • Navigation - アプリ内のユーザーのナビゲーションフローとページ遷移をトラッキング
  • Location - ユーザーの位置に基づくインタラクションと移動を記録
  • Search - 検索クエリと検索関連のユーザーアクションをキャプチャ
  • Transaction - 金銭取引と購入関連の活動をログ
  • UserContent - レビュー、コメント、投稿などのユーザー生成コンテンツをトラッキング
  • UserPreference - ユーザー設定、好み、カスタマイズの選択を記録
  • Social - ソーシャルメディアのインタラクションと共有活動をキャプチャ
import 'package:mparticle_flutter_sdk/events/event_type.dart';
import 'package:mparticle_flutter_sdk/events/mp_event.dart';

final customAttributes = {
  'category': 'Destination Intro',
  'title': 'Paris',
};

MPEvent event = MPEvent(
    eventName: 'Video Watched',
    eventType: EventType.Navigation)
    ..customAttributes = customAttributes
mpInstance?.logEvent(event);

コマースイベントのトラッキング​

コマースイベントをトラッキングするには、以下の3つのステップが必要です：

  1. 購入される製品または製品群を定義する
  2. 取引の概要を含むオブジェクトを作成する
  3. 製品の定義と取引の概要を含めてイベントをログに記録する
import 'package:mparticle_flutter_sdk/events/commerce_event.dart';
import 'package:mparticle_flutter_sdk/events/product.dart';
import 'package:mparticle_flutter_sdk/events/product_action_type.dart';
import 'package:mparticle_flutter_sdk/events/transaction_attributes.dart';

// 1. 製品を作成する

// 製品のためのカスタム属性のマップを文字列のキー/バリューペアとしてオプションで作成する
final customAttributes = {
  'ocean-view': 'true',
  'balcony': 'false',
};

Product product = Product(
    name: 'Double Room - Econ Rate',
    sku: 'econ-1',
    price: 100.00,
    product.quantity = 4;
);

// 上記で作成したカスタム属性のマップを含める
product.attributes = customAttributes;

// 2. 取引を要約する
final TransactionAttributes attributes =
    TransactionAttributes(
        transactionID: '12345',
        revenue: 430.00,
        tax: 30.00
    );

// 3. 購入イベントをログに記録する
CommerceEvent event = CommerceEvent.withProduct(
    productActionType: ProductActionType.Purchase,
    product: product
);
event.transactionAttributes = attributes;

// 購入イベントのためのオプションのカスタム属性はキー/バリュー文字列ペアのマップとして追加できます
event.customAttributes = {"sale": "true", "phone-booking": "true"};

// また、マップを作成してからcustomAttributesビルダーメソッドに渡すこともできます。例えば：
//    val customTransactionAttributes = mutableMapOf<String, String>()
//    customTransactionAttributes["sale"] = "true"
//    customTransactionAttributes["phone-booking"] = "true"
//    .customAttributes(customTransactionAttributes)
mpInstance?.logCommerceEvent(event);
この記事は役に立ちましたか？
Last updated Oct 29, 2025