MPARTICLEの特異なSDK統合

フォローする
Avatar
Omri Barak
Updated

Singular SDKはmParticleのキットとして利用できます。キットを統合すると、mParticleはお客様のアプリからSingularにセッションを転送し、関連する場合はSingularのアプリインストールアトリビューションプロセスをトリガーします。

オプション機能には、アプリ内イベントの転送、収益のトラッキング、SKAdNetworkのサポート（iOSデバイス）、ディープリンクとディファードディープリンクの処理が含まれます。

ガイド エンジニアリングチーム
前提条件 この記事では、 アプリにmParticle SDKがすでに 統合されていることを前提としています。

iOS統合の手順

1

Singular SDKキーを取得する

Singularアカウントで、"Developer Tools > SDK Integration > SDK Keys "に進み、SDK KeyとSecretをコピーしてください。

Screen_Shot_2022-10-11_at_15.30.07.png
2

SingularをmParticleの出力として追加します。

  1. mParticleアカウントで、Setup > Outputsに進み、Add Event Outputをクリックします。
  2. ドロップダウンリストからSingularを選択します。
  3. Event Configuration（イベント構成）ウィンドウで、構成の名前を入力し、前のステップでコピーしたSingularキーとシークレットを入力します。
  4. Save］をクリックします。

image__2_.png
3

Singular SDKのインストール

Singular SDKをインストールします：

  1. アプリで、Link Binary With LibrariesにAdServices.frameworkを追加し、Optionalとしてマークします（iOS 14.3以上のデバイスでのみ使用可能）。

  2. アプリのPodfileにSingular MParticle Podを追加します：

    pod 'mParticle-Singular'
  3. Podfileのディレクトリで、'pod install'を実行します。
4

Singularライブラリをインポートする

Singularライブラリをインポートするには、以下のコード行を追加します：

#import "MPKitSingular.h"
5

Singular SDKの初期化

SDKの初期化コードは、アプリを開くたびに呼び出す必要があります。これはSingularのすべてのアトリビューション機能の前提条件であり、また新しいユーザーセッションをSingularに送信します（セッションはユーザーのリテンションを計算するために使用されます）。

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
      //initialize mParticle 
      MParticleOptions *options = [MParticleOptions optionsWithKey:@"<MPARTICLE_KEY>" secret:@"<MPARTICLE_SECRET>"];
      [[MParticle sharedInstance] startWithOptions:options]; 
      return YES; 
  }
6

[オプション] イベントのトラッキング

Singularはアプリ内イベントのデータを収集し、キャンペーンのパフォーマンス分析やKPIの測定に役立てることができます。

アプリケーションによっては、ユーザーのログイン、登録、チュートリアルの完了、ゲームのレベルアップなどのイベントをトラッキングしたい場合があります。

以下のサンプルコードでは、"event_name "というイベントを2つのカスタム属性とともにSingularにレポートします。Singularのレポートで、"event_name "の発生回数を見ることができます。

MPEvent *event = [[MPEvent alloc] initWithName:@"event_name"
      type:MPEventTypeTransaction];
  event.customAttributes = @{@"category":@"Destination Intro",
      @"title":@"Paris"};
  [[MParticle sharedInstance] logEvent:event];
7

[オプション] 収益の追跡

Singularはアプリを通して得た収益に関するデータを収集し、キャンペーンのパフォーマンスやROIの分析に役立てることができます。

Singularはレポート、ログエクスポート、ポストバックでデータを利用できるようにします。

収益を追跡するには、次の例のように収益イベントをSingularに報告します。この例では、商品のアプリ内購入をレポートし、商品名、SKU、数量、価格を指定しています。

// 1. Create the products
  MPProduct *product = [[MPProduct alloc] initWithName:@"product_name" sku:@"product_sku" quantity:@10     
                                                price:@100.00];
  // 2. Summarize the transaction
  MPTransactionAttributes *attributes = [[MPTransactionAttributes alloc] init];
  attributes.transactionId = @"ransaction_id";
  attributes.revenue = @400.00;
  attributes.tax = @10.00;
  
  // 3. Log the purchase event
  MPCommerceEventAction action = MPCommerceEventActionPurchase;
  MPCommerceEvent *revenueEvent = [[MPCommerceEvent alloc] initWithAction:action product:product];
  revenueEvent.transactionAttributes = attributes;
  [[MParticle sharedInstance] logEvent:revenueEvent];

注：通貨は3文字のISO 4217通貨コード（例："USD"、"EUR"、"INR"）で渡します。
8

[オプション] SKAdNetworkサポートの追加

SKAdNetworkは、エンドユーザーのプライバシーを損なうことなく、モバイルインストールのアトリビューションを決定するためのAppleの新しいフレームワークです。

SKAdNetworkを使用すると、ユーザーの個人情報を共有することなく、アプリマーケティングキャンペーンのパフォーマンスを測定できます。

SKAdNetworkの唯一のソリューションであるSKANは、最小限のエンジニアリングでSKAdNetworkを実装することができます。SKANを初期化すると、Singularに報告されるすべてのイベントがサーバー側で自動的に処理され、事前に定義されたコンバージョンモデルに基づいてコンバージョン値が更新されます。そして新しい換算値がアプリに送り返されます。このプロセスは、測定期間が終了し、アプリが最新のコンバージョン値をSKAdNetworkに送信するまで繰り返されます。

詳しくは、SingularのSKAdNetworkソリューションの紹介とSKAdNetworkの始め方をご覧ください。

以下のサンプルコードは、ATTの同意を60秒待った後にSKANを有効にします（Singular iOS SDK: Handling AppTrackingTransparency Consentを参照）。

注：このコードは、mParticleが初期化される前に実行する必要があります。

[MPKitSingular setSKANOptions:YES isManualSkanConversionManagementMode:NO 
      withWaitForTrackingAuthorizationWithTimeoutInterval:@60.0 
      withConversionValueUpdatedHandler:^(NSInteger conversionValue) {
                    NSLog(@"conversion value %ld", conversionValue);
  }];
9

[オプション] ディープリンクの処理

ディープリンクは、アプリ内の特定のコンテンツにつながるリンクです。アプリがインストールされたデバイスでユーザーがディープリンクをクリックすると、アプリが開き、特定の製品や体験が表示されます。

シンギュラートラッキングリンクは、ディープリンクだけでなく、ディファードディープリンクも含むことができます（詳しくは、 ディープリンクFAQと シンギュラートラッキングリンクFAQをご覧ください）。

注意事項

AppDelegateを使用したディープリンクの処理：

onAttributionCompleteを含むSDK初期化メソッドの呼び出しを追加します：

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
      //initialize mParticle 
      MParticleOptions *options = [MParticleOptions optionsWithKey:@"<MPARTICLE_KEY>" secret:@"<MPARTICLE_SECRET>"];
      options.proxyAppDelegate = NO; 
      [[MParticle sharedInstance] startWithOptions:options]; 
      return YES; 
  }

また、AppDelegateのcontinueUserActivityにmParticleのcontinueUserActivityメソッドの呼び出しを追加します：

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity
restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {
      [[MParticle sharedInstance] continueUserActivity:userActivity restorationHandler:restorationHandler];
      return YES;
  }

SceneDelegateを使用したディープリンクの処理：

SceneDelegateのcontinueUserActivityとwillConnectToSessionに、mParticleのcontinueUserActivityメソッドの呼び出しを追加する：

- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session 
options:(UISceneConnectionOptions *)connectionOptions {
      NSUserActivity* userActivity =
      [[[connectionOptions userActivities] allObjects] firstObject];
      [[MParticle sharedInstance] continueUserActivity:userActivity restorationHandler:nil];
  }
  
  - (void)scene:(UIScene *)scene
      continueUserActivity:(NSUserActivity *)userActivity{
      [[MParticle sharedInstance] continueUserActivity:userActivity restorationHandler:nil];
  }

Android統合のステップ

1

Singular SDKキーを取得する

Singularアカウントで、"Developer Tools > SDK Integration > SDK Keys "に進み、SDK KeyとSecretをコピーしてください。

Screen_Shot_2022-10-11_at_15.30.07.png
2

SingularをmParticleの出力として追加します。

  1. mParticleアカウントで、Setup > Outputsに進み、Add Event Outputをクリックします。
  2. ドロップダウンリストからSingularを選択します。
  3. Event Configuration（イベント構成）ウィンドウで、構成の名前を入力し、前のステップでコピーしたSingularキーとシークレットを入力します。
  4. Save］をクリックします。

image__2_.png
3

SDKのインストール

  1. 以下のようにSingularのMavenサーバーをビルドスクリプトに追加します。 これはSingularキットの要件です。

    repositories {
      maven { url "http://maven.singular.net"}
      ...
  }

  2. アプリのbuild.gradleにキットの依存関係を追加します：

    dependencies {
      compile 'com.mparticle:android-singular-kit:5+'
  }
4

SDKの初期化

SDKの初期化コードは、アプリを開くたびに呼び出す必要があります。これはSingularのすべてのアトリビューション機能の前提条件であり、また新しいユーザーセッションをSingularに送信します（セッションはユーザーのリテンションを計算するために使用されます）。セッションはSingularのレポートだけでなく、mParticleのダッシュボードでも追跡できるようになります。

//import mParticle
  import com.mparticle.MParticle;
  import com.mparticle.MParticleOptions;
  
  public class ExampleActivity extends Activity {
      @Override
      public void onCreate() {
          super.onCreate();
          MParticleOptions options = MParticleOptions.builder(this)
                  .credentials("REPLACE ME WITH KEY", "REPLACE ME WITH SECRET")
                  .build();
          MParticle.start(options);
      }
  }
5

[オプション] ユーザーIDの設定

Singular SDKは、アプリからSingularにユーザーIDを送信することができます。 これは、ユーザー名、メールアドレス、ランダムに生成された文字列、またはユーザーIDとして使用する識別子のいずれかにすることができます。

Singularはユーザーレベルのデータエクスポートと内部BIポストバック（そのようなポストバックを設定した場合）でユーザーIDを使用します。

ユーザー ID を設定すると、セッションやイベントと一緒に送信されます。ユーザー ID は、設定を解除するか、アプリをアンインストールするまで保持されます。 アプリを終了/再起動しても、ユーザー ID は解除されません。

IdentityApiRequest identityRequest = IdentityApiRequest.withEmptyUser()
          .email("foo@example.com")
          .customerId("123456")
          .build();
  MParticle.getInstance().Identity().login(identityRequest);
6

[オプション] イベントの追跡

Singularはアプリ内イベントのデータを収集し、キャンペーンのパフォーマンス分析やKPIの測定に役立てることができます。

アプリケーションによっては、ユーザーのログイン、登録、チュートリアルの完了、ゲームのレベルアップなどのイベントをトラッキングしたい場合があります。

以下のサンプルコードでは、"test_event" というイベントを JSONObject フォーマットで追加情報（customAttributes）とともに Singular にレポートします。

Map<String, String> customAttributes = new HashMap<String, String>();
            customAttributes.put("category", "event_category");
            MPEvent event = new MPEvent.Builder("test_event", MParticle.EventType.Navigation)
                   .customAttributes(customAttributes)
                   .build();
            MParticle.getInstance().logEvent(event);
7

[オプション] 収益の追跡

Singularは、mParticleからProduct.PURCHASEイベントを受信することで、アプリを通じて得た収益に関するデータを収集できます。

イベントの収益は、数量 * product_costとして計算されます。

Product product = new Product.Builder("extra life", "extra-life", 100.00)
          .quantity(4.0)
          .build();
  TransactionAttributes attributes = new TransactionAttributes("123123")
          .setRevenue(430.00)
          .setTax(30.00);
  
  CommerceEvent event = new CommerceEvent.Builder(Product.PURCHASE, product)
          .transactionAttributes(attributes)
          .currency("USD")
          .build();
  
  MParticle.getInstance().logEvent(event);

注：通貨は、3文字のISO 4217通貨コード（例：「USD」、「EUR」、「INR」）で渡します。
8

[オプション] ディープリンクの処理

ディープリンクは、アプリ内の特定のコンテンツにつながるリンクです。アプリがインストールされたデバイスでユーザーがディープリンクをクリックすると、アプリが開き、特定の製品や体験が表示されます。

シンギュラートラッキングリンクは、ディープリンクだけでなく、ディファードディープリンクも含むことができます（詳しくは、 ディープリンクFAQと シンギュラートラッキングリンクFAQをご覧ください）。

注意事項

ディープリンクを処理するには、以下の例のようにAttributionListenerを実装します。すべてのメインエントランスアクティビティでAttributionListenerを実装する必要があることに注意してください。

public class ActivityDeeplink extends AppCompatActivity implements AttributionListener {
  
      @Override
      protected void onCreate(Bundle savedInstanceState) {
          super.onCreate(savedInstanceState);
          MParticleOptions options = MParticleOptions.builder(this)
                  .credentials("REPLACE ME WITH KEY", "REPLACE ME WITH SECRET")
                  .attributionListener(this)
                  .logLevel(MParticle.LogLevel.VERBOSE)
                  .build();
          MParticle.start(options);
      }
  
      @Override
      public void onResult(@NonNull @NotNull AttributionResult attributionResult) {
          if (attributionResult.getServiceProviderId() == MParticle.ServiceProviders.SINGULAR) {
              String deeplink = attributionResult.getLink();
              JSONObject data = attributionResult.getParameters();
              String passthrough = data.optString("passthrough", null);
              // Deal with deep link
          }
      }
  
      @Override
      public void onError(@NonNull @NotNull AttributionError attributionError) {
          // Deal with error
      }
  }