フラッター用の特異なSDK統合

 

Singular SDKはFlutterのプラグインとして利用可能です。SingularをFlutterアプリに統合する方法は以下の通りです。

前提条件

  • この記事は、あなたが機能的なFlutterアプリを持っていることを前提としています。
  • SDKを初期化するには、Singular SDK KeyとSDK Secretが必要です。これらはSingularプラットフォームの "Developer Tools > SDK Integration > SDK Keys "から入手できます。

新しいビデオガイド

このビデオで統合プロセスの詳細をご覧ください。ビデオと下記のガイドの両方を使用することをお勧めします。

Singularプラグインの統合

FlutterアプリにSingularプラグインを追加するには、pubspec.yamlファイルに以下の行を追加します:

dependencies:
  singular_flutter_sdk: ^1.4.0

それからターミナルでプロジェクトに移動し、以下を実行します:

flutter packages get

Android用の追加ステップ

依存関係の追加

Androidアプリの場合、以下のようにapp/build.gradleの依存関係リストにSingularライブラリを追加する必要があります:

dependencies {  
  implementation fileTree(dir: 'libs', include: ['*.jar'])
  implementation 'com.android.support:appcompat-v7:28.0.0'
  //...
}

Singular SDKにはGoogle Play Services APIs 17.0.0+の一部であるGoogle Mobile Ads APIが必要です。すでにGoogle Play Servicesをアプリに統合していれば、この要件は満たされています。そうでない場合は、アプリのbuild.gradle に以下の依存関係を含めることで、Google Mobile Ads を個別に統合できます:

implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'

Singular SDKのtransitive dependenciesを無効にしている場合は、アプリのbuild.gradleに以下を追加してください。

implementation 'com.android.installreferrer:installreferrer:2.2'
implementation 'com.google.android.gms:play-services-appset:16.0.2'

注意: ビルド時にDuplicateClasses エラーが表示される場合は、すでに Google play-services がインストールされている可能性がありますので、依存関係をコメントアウトしてください。

パーミッションの追加

AndroidManifest.xmlファイルの<manifest>タグの下に、これらのパーミッションを追加します:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="BIND_GET_INSTALL_REFERRER_SERVICE" />
<uses-permission android:name="com.android.vending.CHECK_LICENSE" />

アプリのビルドがAndroid 12/APIレベル31以上をターゲットにしている場合は、Google Advertising IDにアクセスするためのパーミッションを追加します:

<uses-permission android:name="com.google.android.gms.permission.AD_ID" />

注意 Kids SDKを統合する場合は、このパーミッションを追加しないでください。

ご注意ください:アプリにandroid.permission.GET_TASKSパーミッションがある場合、ユーザーが実際にアプリを開く前にアプリが初期化される可能性があります。これはSingular SDKを初期化し、インストール時間の不一致を引き起こす可能性があります。この問題を防ぐには、パーミッションが不要であれば削除するか、Singular SDKの初期化コールをコード内の別の場所に移動し、ユーザーが初めてアプリを開いた後にのみ呼び出されるようにします。

iOSのための追加ステップ

Singularプラグインを使用するには、AdServicesフレームワークを追加する必要があります。

SingularSDKの初期化

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

初期化コードは、アプリを開いたときに最初にロードされるメインウィジェット(main.dartなど)に記述します。このウィジェットはステートフルである必要があり、コードはウィジェットのinitState()メソッドに追加する必要があります。

  1. まず SingularConfig オブジェクトを作成します。このオブジェクトには Singular SDK Key と Secret が含まれます。
  2. オプションで、様々なSDK機能を有効にする設定を追加できます。オプションの全リストをご覧ください。
  3. METAインストール・リファラー帰属のサポート

    Meta Install Referrer」アトリビューションを有効にするために必要なSDK設定です:

    1. Singular構成オブジェクトにFacebookアプリIDを入力してください。
      // META インストールリファラーを有効にするには
        config.facebookAppId = "ここに Facebook アプリ ID を入力してください";
    アプリのFacebookアプリIDはどこで確認できますか?

import 'package:singular_flutter_sdk/singular.dart';
import 'package:singular_flutter_sdk/singular_config.dart';
//...
class MyHomePage extends StatefulWidget { 
//... } class _MyHomePageState extends State<MyHomePage> {
//... @override  void initState() { super.initState();
//... SingularConfig config = new SingularConfig('SDK KEY', 'SDK SECRET'); // 利用可能な場合はハッシュ化されたユーザー ID を設定します
config.customUserId = "b642b4217b34b1e8d3bd915fc65c4452";

// iOS の場合 (ATT プロンプトを表示しない場合はこれを削除してください)。
config.waitForTrackingAuthorizationWithTimeoutInterval = 300;

// META インストールリファラーを有効にするには
config.facebookAppId = "ここに Facebook アプリ ID を入力してください";

// SkAdNetwork サポートを有効にするには
config.skAdNetworkEnabled = true;

/* (オプション) Singular Global Properties 機能を使用してサードパーティ ID を取得します。 それぞれの SDK は、Singular SDK の前に初期化する必要があります。 CleverTapID を渡す例。*/
// var cleverTapId = CleverTapPlugin.getCleverTapID();
// config.withGlobalProperty("CLEVERTAPID", cleverTapId, true);
Singular.start(config); }

ユーザーIDをSingularに送信する(オプション)

Singular SDKのメソッドを使用して、内部ユーザーIDをSingularに送信することができます。

注意: Singularのクロスデバイスソリューションをご利用の場合は、すべてのプラットフォームでユーザーIDを収集する必要があります。

  • ユーザーIDはどのような識別子でもかまいませんが、PII(個人を特定できる情報)を公開するべきではありません。 例えば、ユーザーのメールアドレス、ユーザー名、電話番号は使用しないでください。Singularは、お客様のファーストパーティデータにのみユニークなハッシュ値を使用することを推奨します。
  • Singularに渡すユーザーIDは、すべてのプラットフォーム(ウェブ/モバイル/PC/コンソール/オフライン)で同じ内部ユーザーIDを使用する必要があります。
  • Singularはユーザーレベルのエクスポート、ETL、内部BIポストバック(設定されている場合)にユーザーIDを含めます。ユーザーIDはファーストパーティデータであり、Singularが他者と共有することはありません。
  • ユーザーIDの値は、Singular SDKメソッドで設定されると、unsetCustomUserId メソッドで設定が解除されるまで、またはアプリがアンインストールされるまで保持されます。アプリを終了または再起動しても、ユーザーIDはアンセットされません。

ユーザーIDを設定するには、setCustomUserId メソッドを使用します。設定を解除するには(ユーザがアカウントから「ログアウト」した場合など)、unsetCustomUserId を呼び出してください。

注:複数のユーザが1つのデバイスを使用する場合、ログインとログアウトのたびにユーザIDを設定および解除するログアウトフローを実装することを推奨します。

アプリを開いたときにユーザーIDがすでに分かっている場合は、Singular SDKを初期化する前にsetCustomUserId 。こうすることで、Singularは最初のセッションからユーザーIDを持つことができます。しかし、ユーザーIDは通常、ユーザーが登録するかログインを実行するまで使用できません。その場合は、登録フローが完了した後にsetCustomUserId

Singular.setCustomUserIDメソッド
説明 ユーザーIDをSingularに送信します。
シグネチャ static void setCustomUserId(String customUserId)
使用例
Singular.setCustomUserId("custom_user_id");
Singular.unsetCustomUserIDメソッド
説明 Singularに送信されたユーザーIDの設定を解除します。
シグネチャ static void unsetCustomUserId()
使用例
Singular.unsetCustomUserId();

オプション:カスタムユーザーID デバイスマッピング

重要:この高度なエンタープライズ機能は、例外的な場合にのみ使用できます。実装する前にSingularのソリューションエンジニアにご相談ください。

Singularはサーバー間の統合により、追加のモバイルイベント追跡データを受け取ることができます。この機能を利用するには、ユーザーIDをSingularのモバイルデバイス追跡識別子にマッピングする必要があります。

注意:Singular SDKを初期化した後、またはユーザーIDを取得した後、できるだけ早くこのメソッドを呼び出してください。

Singular.setDeviceCustomUserId メソッド
説明 ログイン時と同じカスタムユーザーIDを設定し、Singularのトラッキング識別子にマッピングします。
シグネチャ static void setDeviceCustomUserId(String customUserId)
使用例
Singular.setDeviceCustomUserId("custom_user_id");

ディープリンクの実装

ディープリンクとは、ユーザーの携帯電話でアプリを開き、アプリのメインウィジェットだけでなく、特定のページやユーザーエクスペリエンスに直接ユーザーを送るリンクです。ディープリンクは通常、リターゲティングキャンペーンで使用され、すでに携帯電話にアプリを持っているが、しばらくアプリを使用していないユーザーを対象としています。SingularはSingular Linksを通してディープリンクをサポートしています。

シンギュラーリンクを有効にする

iOSとAndroidでSingular Linksを有効にするには、Singular Linksの前提条件をご覧ください。

Androidをサポートするには、プロジェクトのMainActivity.javaファイルに以下のコードを追加します:

Java Kotlin
import com.singular.flutter_sdk.SingularBridge;
import android.content.Intent;

@Override protected void onNewIntent(@NonNull Intent intent) {   super.onNewIntent(intent);   SingularBridge.onNewIntent(intent); }

iOSサポートの場合は、プロジェクトのAppDelegate.mに以下を追加します:

 

Objective-C Swift
// Top of AppDelegate.m
            
#import "SingularAppDelegate.h"

- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {    [GeneratedPluginRegistrant registerWithRegistry:self];    [SingularAppDelegate shared].launchOptions = launchOptions; return [super application:application
didFinishLaunchingWithOptions:launchOptions]; }
- (BOOL)application:(UIApplication *)application
continueUserActivity:(NSUserActivity *)userActivity
restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>>
*restorableObjects))restorationHandler {    [[SingularAppDelegate shared] continueUserActivity:userActivity
restorationHandler:restorationHandler];    return [super application:application continueUserActivity:userActivity
restorationHandler:restorationHandler ]; }
- (BOOL)application:(UIApplication *)app
openURL:(NSURL *)url
options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {     [[SingularAppDelegate shared] handleOpenUrl:url options:options];      return [super application:app openURL:url options: options]; }

Singularリンクの処理

Singularのハンドラーメカニズムを使って、アプリが開かれるきっかけとなったトラッキングリンクの詳細を読み取る。

例えば

SingularConfig config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');

config.singularLinksHandler = (SingularLinkParams params) { String deeplink = params.deeplink; String passthrough = params.passthrough; bool isDeferred = params.isDeferred; // ディープリンクを処理するコードをここに追加します }; Singular.init(config);

イベントのトラッキング(非収益)

Singularはアプリ内イベントのデータを収集し、キャンペーンのパフォーマンス分析やKPIの測定に役立てることができます。例えば、ゲームアプリでユーザーのログイン、登録、チュートリアルの完了、レベルアップなどのデータを収集したい場合があります。

Singularは様々な 標準イベントをサポートしています。これらのよく使われるイベントは、レポートや最適化のために広告ネットワークでよくサポートされています。もう一つの利点は、標準的なイベント名を使用すると、Singularが自動的に認識し、手動で定義しなくてもイベントリストに追加されることです。可能な限り標準イベントを使用することをお勧めします。

Singularに送信されるイベントのリスト(付随する属性付き)は、組織のマーケティングKPIに基づいてUA/マーケティング/ビジネスチームが作成する必要があります。ビジネスチームは、How to Track In-App Eventsのガイドに従ってください:Guide For Singular Attribution Customers.

イベントごとに推奨される標準属性を参照してください

コード内で、event または eventWithArgs メソッドを使用して Singular にイベントを送信します。

注:標準イベントの場合は、 Flutter SDK List of Standard Events and Attributesに表示されているイベントのFlutter名を使います(例:sngLogin)。

カスタムイベント(Singularの標準イベントのどれにも一致しない、あなたの組織が測定したいイベント)の場合は、任意のカスタム名(最大32文字)を使用してください。最適化のためにSingularからイベントを受け取る可能性のある広告ネットワークパートナーとの互換性のために、英語の名前を使用することをお勧めします。

Singular.event(Events.sngLogin);
Singular.eventWithArgs(eventName, {attributeName:attributeValue});
Map<String, Object> map = HashMap<String, Object>();
map ['name'] = 'John Doe';
map ['age'] = 30;
map ['isStudent'] = false;
Singular.eventWithArgs('event_Name', map);

収益のトラッキング

IAPイベントの送信

アプリの収益をSingularに追跡させるには、IAPイベントをSingularに送信します。IAPイベントを送信することで、Singularがイベントの検証データをチェックし、不正でないことを確認することもできます。

次の例をご覧ください。

注:このコードスニペットにはFlutter IAPパッケージ(https://pub.dev/packages/in_app_purchase)が必要です。

import 'package:singular_flutter_sdk/singular_iap.dart';
import 'dart:io' show Platform;
            
if (Platform.isIOS) {
  singularPurchase = new SingularIOSIAP(
    product.rawPrice.toStringAsFixed(2),
    product.currencyCode,
    purchase.productID,
    purchase.purchaseID,
    purchase.verificationData.serverVerificationData
  );
}
            
else if (Platform.isAndroid) {
  singularPurchase = new SingularAndroidIAP(
    product.rawPrice.toStringAsFixed(2),
    product.currencyCode,
    purchase.verificationData.serverVerificationData,
    purchase.verificationData.localVerificationData
  );
}
            
Singular.inAppPurchase(eventName, singularPurchase);

通貨は3文字のISO 4217通貨コード(例:"USD"、"EUR"、"INR")で渡します。

別の方法カスタム収益イベントの送信

Singularはカスタム収益イベントを名前と収益額で送信して収益を報告するオプションも提供しています。 この方法では購入レシートをSingularと共有しないため、Singularが正当なイベントであることを確認できないことにご注意ください。

例えば

Singular.customRevenue("MyCustomRevenue", "USD", 5.50);
Map<String, Object> map = HashMap<String, Object>();
map ['name'] = 'John Doe';
map ['age'] = 30;
map ['isStudent'] =false;
Singular.customRevenueWithAttributes('MyCustomRevenue','USD', 20, map);

注:通貨を3文字のISO 4217通貨コード(例:"USD"、"EUR"、"INR")で渡します。

ハイブリッドイベントトラッキング(上級者向け)

Singularでは、アプリに統合されたSingular SDKを通してすべてのイベントと収益を送信することを推奨しています。ただし、Singularは他のソースからイベントと収益を収集することもできます。

Singular SDKから送信されないイベントは、Singularのサーバー間イベントドキュメンテーション要件に準拠し、イベントの属性を正しく設定するために一致するデバイス識別子を提供する必要があります。

重要です

Server-to-Server イベントリクエストで使用されるデバイス識別子がSingularで一致しない場合、不一致が発生します。以下の可能性に注意してください:

  • イベントリクエストがSingular SDKがアプリセッションからデバイス識別子を記録する「前」に受信された場合、そのイベントリクエストは未知のデバイスの「最初のセッション」とみなされ、Singularはそのデバイスをオーガニックアトリビューションとしてアトリビュートします。
  • もしSingular SDKがデバイス識別子を記録していたとしても、Singular SDKの識別子がServer-to-Server Eventリクエストで指定されたデバイス識別子と異なる場合、イベントの帰属は正しくありません。

ハイブリッドイベント追跡ガイド

内部サーバーからのイベント送信

Singularはお客様のサーバーから収益に関するデータを収集し、キャンペーンのパフォーマンスやROIの分析に役立てることができます。

要件

  • アプリ内登録またはログインイベントから、デバイス識別子を取得して渡し、このデータをユーザーIDと共にサーバーに保存します。デバイス識別子はユーザーによって変更される可能性があるため、ユーザーがアプリセッションを生成する際には必ず識別子を更新してください。これにより、サーバー側イベントが正しいデバイスに帰属することが保証されます。
  • サーバー側イベントはプラットフォーム固有であるため、デバイスプラットフォームに一致するデバイス識別子(iOSデバイスのIDFAまたはIDFVなど)のみを使用して送信する必要があります。
  • Singular 内部 BI ポストバック メカニズムを使用して、内部エンドポイントにリアルタイムでイベントをプッシュすると、サーバー側でデータセットを更新できます。内部BI ポストバック FAQ を参照してください。
  • 詳細については、『サーバー間統合』ガイドの「収益の追跡」セクションを参照してください。
収益プロバイダからのイベントの送信
RevenueCatや adaptyのようなサードパーティプロバイダーは、Singularに購入収益や購読収益を提供することができます。

これらのパートナーを有効にする方法の詳細については、以下のリンクを参照してください。

セグメントからのイベント送信

SingularSDKと並行してSegmentからSingularにイベントを送信するには、Segmentに"Cloud-Mode "Destinationを追加する必要があります。こちらのガイドに従ってください。

広告収益アトリビューションサポートの追加

Singular SDKで広告収益 アトリビューションを設定できます。

Flutter SDKを使用して広告収益アトリビューションサポートを追加するには:

  1. 適切なコードスニペットを追加して、広告収益データに使用しているメディエーションプラットフォームから広告収益情報を取得 します。

    Android SDKドキュメントのコードスニペットをご覧ください。

注:通貨は3文字のISO 4217通貨コード(例:"USD"、"EUR"、"INR")で渡します。

広告収入イベントをSingularに報告するには、以下のコードを使用します。
  1. SingularAdDataオブジェクトを関連データで初期化する。
  2. データをSingularに報告する
Dart
SingularAdData adData = SingularAdData(
"あなたの広告プラットフォーム",
"通貨コード",
0.05)
Singular.adRevenue(adData)

SKAdNetworkサポートの追加

アプリのSKAdNetworkトラッキングを有効にするには、Singularを初期化する前にskAdNetworkEnabled コンフィギュレーションオプションを有効にしてください。

マネージドモード(推奨)

マネージドモードでは、Singularプラットフォームで設定できるお好みのコンバージョンモデルに基づいて、Singularが自動的にSKAdNetworkのコンバージョン値を管理します。

詳しくは、Singularのコンバージョンバリュー管理についてと SKAdNetworkモデル設定FAQをご覧ください。 SingularでSKAdNetworkを使用するためのステップバイステップガイドは、SKAdNetworkの始め方をご覧ください。

注:上記の初期化コードでは、SKAN Managedモードがすでに有効になっています。これらの設定項目が設定されていることを確認してください。

マネージドモードでSKAdNetworkを有効にするには、以下のコードを使用してください:

SingularConfig config = new SingularConfig('<SDK KEY>', '<SDK SECRET>');
config.skAdNetworkEnabled = true;
config.waitForTrackingAuthorizationWithTimeoutInterval = 300; Singular.init(config);

マニュアルモード

SKAdNetworkの変換値を管理するための独自の戦略やツールをすでにお持ちの場合は、SKAdNetworkをマニュアルモードで有効にすることができます。

SingularConfig config = new SingularConfig('SDK KEY', 'SDK SECRET');
config.skAdNetworkEnabled = true;
config.manualSkanConversionManagement = true;
config.waitForTrackingAuthorizationWithTimeoutInterval = 300; Singular.init(config);

そして、コンバージョン値を更新するには、以下のコードを使用します:

ingular.skanUpdateConversionValue(conversionValue)

コンバージョン値の変更を追跡するには、以下のコールバック関数を使用します:

config.conversionValueUpdatedCallback = (int conversionValue) {
  print('Received conversionValueUpdatedCallback: ' + conversionValue.toString());
};

現在の変換値を取得するには、以下のコードを使用します:

Singular.skanGetConversionValue().then((conversionValue) {
  print('conversion value: ' + conversionValue.toString());
});

その他のオプション

アンインストールの追跡

Singularにアプリのアンインストールを追跡させるには、次の例のようにSingularにAPNS/FCMトークンを与えます:

// iOS
Singular.registerDeviceTokenForUninstall(apnsToken);
            
// Android
Singular.registerDeviceTokenForUninstall(fcmToken);

データプライバシー法の遵守

Singularは、GDPRやCCPA(カリフォルニア州消費者プライバシー法)のような消費者プライバシー法を遵守する可能性のあるパートナーと協力できるように、プライバシー保護機能を提供します。 これらのパートナーは、エンドユーザーが個人情報の共有に同意した場合に通知されることを望んでいます。

ユーザーに情報共有の同意を求める方法を実装している場合は、limitDataSharingメソッドを使用してユーザーの選択をSingularに通知します:

Singular.limitDataSharing(false)を使用して、ユーザが情報の共有に同意した(オプトインした)ことを示します。

ユーザが同意しなかった場合はSingular.limitDataSharing(true)を使用します。

Singularは"ユーザープライバシーのポストバック"でLimitDataSharingを使用し、関連する規制を遵守するために必要なパートナーにこの情報を渡します。詳しくは「ユーザーのプライバシーとデータ共有の制限」をご覧ください。

注: このメソッドの使用は任意ですが、ユーザーがオプトインしたことが特に通知された場合に限り、パートナーがSingularと共有する属性情報がある場合があります。

Singular.limitDataSharingメソッド
シグネチャ Singular.limitDataSharing(booleanshouldLimitDataSharing)
説明 個人データの共有に対するユーザーの同意(オプトイン)をSingularに通知します。
使用例
// ユーザーがデータ共有に同意した
Singular.limitDataSharing(false);

GDPR準拠のための追加メソッド

Singular SDKは、GDPRポリシーに準拠し、トラッキングに対するユーザーの同意または非同意についてSingularに知らせるためのメソッドをいくつか提供しています。

Singular.trackingOptInメソッド
説明 トラッキングに対するユーザーの同意(オプトイン)をSingularに通知します。
使用例
Singular.trackingOptIn();
Singular.stopAllTracking メソッド
説明

このアプリにおけるこのユーザーのトラッキングをすべて停止します。

注意:このメソッドを呼び出すと、アプリが再起動した後でもSDKが効果的に無効になります(状態は持続します)!トラッキングを再び有効にする唯一の方法は、resumeAllTracking()を呼び出すことです。
使用例
Singular.stopAllTracking();
Singular.resumeAllTrackingメソッド
説明 このアプリのこのユーザーのトラッキングを再開します。
使用例
Singular.resumeAllTracking();
Singular.isAllTrackingStoppedメソッド
説明 このアプリのこのユーザーのトラッキング状況を確認します。StopAllTracking()を使用してトラッキングが停止され、再開されていない場合はtrueを返します。
使用例
Singular.isAllTrackingStopped();