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.5.1

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

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'

さらに、アプリをSamsung Galaxy Storeを通じて配布する場合は、Samsung Galaxy Storeのインストール・リファラーをサポートするために以下を追加してください：

implementation 'store.galaxy.samsung.installreferrer:samsung_galaxystore_install_referrer:4.0.0'

パーミッションの追加

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" />

さらに、アプリがSamsung Galaxy Storeを通じて配布され、Android 11以上をターゲットにしている場合は、Samsung Galaxy Storeのインストール・リファラーをサポートするために以下を追加します：

<queries>
   <package android:name="com.sec.android.app.samsungapps" />
</queries>

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

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

iOSのための追加ステップ

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

Singular SDKの初期化

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

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

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

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

   1. Singular Configuration ObjectにFacebookアプリIDを入力してください。
      

      // To enable META Install Referrer
      
                config.facebookAppId = "INSERT YOUR FACEBOOK APP ID HERE";

   アプリの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');
      // Set hashed User ID if available

      config.customUserId = "b642b4217b34b1e8d3bd915fc65c4452";
      
      // For iOS (Remove this if you are not displaying an ATT prompt)!

      config.waitForTrackingAuthorizationWithTimeoutInterval = 300;
      
      // To enable SkAdNetwork Support

      config.skAdNetworkEnabled = true;
      
      // To enable META Install Referrer

      config.facebookAppId = "INSERT YOUR FACEBOOK APP ID HERE";
      
      // (optional) Using Singular Global Properties feature to capture 

      // third party identifiers. The respective SDK(s) must be initialized

      // before the Singular SDK. Example of passing the CleverTapID.

      // var cleverTapId = CleverTapPlugin.getCleverTapID();

      // config.withGlobalProperty("CLEVERTAPID", cleverTapId, true);

              
      Singular.start(config);
  }

ATT同意の処理（初期化遅延の設定）

ATT（App Tracking Transparency）プロンプトの表示

iOS 14.5から、アプリは、デバイスのIDFAを含む追跡目的に役立ついくつかのユーザーデータにアクセスして共有する前に、（App Tracking Transparencyフレームワークを使用して）ユーザーの同意を求める必要があります。

Singularは、デバイスを識別し、インストールアトリビューションを実行するために、IDFAを取得することで大きなメリットを得ています（ただし、IDFAを取得せずにアトリビューションを実行する方法もあります）。IDFAを取得するために、ユーザーの同意を求めることを強く推奨します。

初期化を遅らせてATTの応答を待つ

デフォルトでは、Singular SDKは初期化時にユーザーセッションを送信します。セッションが新しいデバイスから送信されると、Singularのアトリビューションプロセスが即座にトリガーされます。したがって、Singular SDKが最初のセッションを送信する前に、同意を求め、IDFAを取得することが 不可欠です。

ユーザーセッションの開始を遅らせるには、Singular SDKを初期化し、ConfigオブジェクトにwatefForTrackingAuthorizationWithTimeoutIntervalオプションを指定します。このオプションは上記のコードサンプルにすでに含まれています。

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

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

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

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

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

Singular.setCustomUserId("custom_user_id");

Singular.unsetCustomUserId();

Singular.setDeviceCustomUserId("custom_user_id");

ディープリンクの実装

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

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

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

Androidサポートの場合は、プロジェクトのMainActivity.javaファイルに以下のコードを追加してください：

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

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

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

override fun onNewIntent(intent: Intent) {
  super.onNewIntent(intent)
  SingularBridge.onNewIntent(intent);
}

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

// 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];
}

import singular_flutter_sdk
  
override func application(_ application: UIApplication, 
  didFinishLaunchingWithOptions
  launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    GeneratedPluginRegistrant.register(with: self) if 
      let singularAppDelegate = SingularAppDelegate.shared() {
        singularAppDelegate.launchOptions = launchOptions
      }
  return super.application(application, didFinishLaunchingWithOptions:launchOptions)
}

override func application(_ application: UIApplication, 
  continue userActivity:NSUserActivity, 
  restorationHandler: @escaping ([UIUserActivityRestoring]?)-> Void) -> Bool {
    if let singularAppDelegate = SingularAppDelegate.shared() {
      singularAppDelegate.continueUserActivity(userActivity, restorationHandler:nil)
    }
  return super.application(application, continue:userActivity, 
    restorationHandler: restorationHandler);
}

override func application(_ app: UIApplication, 
  open url: URL, options:[UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    if let singularAppDelegate = SingularAppDelegate.shared() {
      singularAppDelegate.handleOpen(url, options: options)
    }
  return super.application(app, open: 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;
  // Add your code here to handle the deep link

};
          
Singular.init(config);

トラッキングイベント（非収益）

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

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

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

追跡するイベントごとに、さまざまな属性を渡すことができます。イベントごとの推奨標準属性を参照してください。

コード内で、eventまたはeventWithArgsメソッドを使用して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;
            
// Parse the revenue amount and currency first
double revenue = double.tryParse(product.rawPrice.toStringAsFixed(2)) ?? 0.0;
String? currencyCode = product.currencyCode;

// Only process if both revenue is greater than 0 and currencyCode exists
if (revenue > 0 && currencyCode != null && currencyCode.isNotEmpty) {
  if (Platform.isIOS) {
    singularPurchase = new SingularIOSIAP(
      revenue,
      currencyCode,
      purchase.productID,
      purchase.purchaseID,
      purchase.verificationData.serverVerificationData
    );
  }
              
  else if (Platform.isAndroid) {
    singularPurchase = new SingularAndroidIAP(
      revenue,
      currencyCode,
      purchase.verificationData.serverVerificationData,
      purchase.verificationData.localVerificationData
    );
  }
              
  Singular.inAppPurchase(eventName, singularPurchase);
}

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

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);

ハイブリッドイベント追跡（上級者向け）

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

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

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

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

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を使用し、関連する規制を遵守するために必要なパートナーにこの情報を渡します。詳しくは「ユーザーのプライバシーとデータ共有の制限」をご覧ください。

// User has opted into sharing data

Singular.limitDataSharing(false);

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

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

Singular.trackingOptIn();

Singular.stopAllTracking();

Singular.resumeAllTracking();

Singular.isAllTrackingStopped();