Unity SDK統合ガイド

 

新しいビデオガイド

このビデオでは、統合とテストのプロセスについて詳しく説明しています。 ビデオと以下のガイドの両方を使用することをお勧めします。

始める前にSDKの前提条件

Singular SDKの統合の 手順に従ってください:計画と前提条件

これらのステップはSingular SDKを統合するための前提条件です。

1.SDKのインストール

1.1.SDKパッケージのダウンロードとインポート

Unityカスタムパッケージのインポート

バージョン4.3.2以前からアップグレードする場合は?

Assets > Plugins > iOS に移動し、新しい unitypackage をインポートする前に以下のファイルを削除してください!

  • Attributes.h
  • Events.h
  • libSingular.a
  • Singular.h
  • SingularAdData.h
  • SingularConfig.h
  • SingularLinkParams.h
  1. 新しいSingular SDK unitypackage v4.4.2 ファイルをダウンロードしてください。
  2. Unityメニューからに移動します:

    • Assets > Import Package > Custom package
    • ダウンロードしたunitypackageを選択します。
    • インポートを選択します。

1.2.Android用の設定

ヒント: Unityを使用しているときにAndroidManifestを更新する方法
  1. Unity v2018.3以降では、プレイヤーウィンドウのCustom Main Manifestプロパティを有効にするだけで、独自のAndroidManifest ファイルを追加できます(File > Build Settings > Player Settings > Publishing settings でアクセスできます)。これにより、デフォルトのAndroidManifest.xmlファイルが生成され、編集することができます。

    ファイルはAssets/Plugins/Android/AndroidManifest.xmlにあります。

    ソース: https://docs.unity3d.com/2023.2/Documentation/Manual/android-manifest.html

  2. UnityのカスタムMain Manifestファイルを使用する代わりに、Unityからアプリをエクスポートした後、Android StudioからAndroidManifest.xml

ヒント:Unityを使用している ときにGradleの設定を更新する方法
  1. Unity v2018.3以降では、PlayerウィンドウのCustom Gradle Templateプロパティを有効にして独自に追加することができます(custom Gradle build file からは、File > Build Settings > Player Settings > Publishing settings でアクセスできます)。これにより、デフォルトのmainTemplate.gradleファイルが生成され、編集することができます。

    ファイルはAssets/Plugins/Android/mainTemplate.gradleにあります。

    ソース:https://docs.unity3d.com/2023.2/Documentation/Manual/android-gradle-overview.html

  2. UnityのカスタムGradleビルドファイルを使用する代わりに、Unityからアプリをエクスポートした後、Android Studioからアプリbuild.gradle

ヒント: Android 12デバイスをサポートする予定はありますか?

ファイルを play-services-ads-identifier-18.0.1.aar ファイルをAssets/Plugins/Android/ フォルダに追加して、Unity が Google Advertising Identifier をキャプチャするために必要な依存関係を含めるようにします。すでにこの依存関係がある場合は、このステップをスキップできます。

AndroidManifest パーミッションを更新する

AndroidManifest.xml ファイルで、以下のパーミッションを追加します:


<!--  インターネット接続を使用するには、この許可が必要です。  -->
<uses-permission android:name="android.permission.INTERNET" />

<!--  このパーミッションは、アクティブなインターネット接続をチェックするために必要です。  -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!--  このパーミッションは、Google Playのリファラーデータを取得するために必要です。  -->
<uses-permission android:name="BIND_GET_INSTALL_REFERRER_SERVICE" />

<!--  このパーミッションは、Google Install Fraudを検証するために必要です。  -->
<uses-permission android:name="com.android.vending.CHECK_LICENSE" />
	
Singular SDK の Transitive dependencies を無効にしましたか?
  1. Singular SDKのtransitive dependenciesを無効にした場合は、アプリのbuild.gradleに以下を追加してください。

    implementation 'com.android.installreferrer:installreferrer:2.2'
    implementation 'com.google.android.gms:play-services-appset:16.0.0'
  2. 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+'

    詳細については、 GoogleのGoogle Play Servicesのセットアップガイドを参照してください。

ProguardまたはEclipseを使用していますか?

Proguardを 使用している場合は、proguard-unity.txtファイルに以下のコードを追加してください:

-keep class com.singular.sdk.** { *; }
-keep public class com.android.installreferrer.** { *; }
-keep public class com.singular.unitybridge.** { *; }

Eclipseでビルド する場合は、以下のいずれかの方法でAARをEclipseプロジェクトに統合してください:

  1. singular_sdk-12.x.x.aarを解凍します。
  2. classes.jarを singular_sdk-12.x.x.jarにリネームします(これがメインのSDK jarです)。
  3. 上記のjarとlibs/installreferrer-release.jar(Google Referrer APIライブラリ)をEclipseプロジェクトに任意の方法で統合します。
  4. AARに含まれるAndroidManifest.xmlからBIND_GET_INSTALL_REFERRER_SERVICEパーミッションをAndroidManifest.xmlにコピーします。

1.3.iOSの設定

Unityからビルドした後、以下のライブラリ/フレームワークをUnity XCodeプロジェクトにリンクします。UnityFrameworkTargetに移動し、Build Phases > Link Binary with Librariesを選択します。以下を追加します:

  • WebKit.framework
  • libsqlite3.0.tbd
  • libz.tbd
  • AdServices.framework (必ず追加する 必要がありますが、iOS 14.3以上のデバイスでのみ利用可能なため、Optionalとして マークしてください)。また、Apple Search Adsで実行する場合は必須です!

重要: Apple Search Ad Campaignsを利用する予定があり、アトリビューションをトラッキングしたい場合は、App BuildでAdServices.framework

2.SDKインテグレーション

2.1.SingularSDKObjectの設定

Unityプラットフォームの階層ペインで、"Empty GameObject "を追加します:

  1. メインシーンに"Empty GameObject"を追加し、名前をSingularSDKObject とします。

  2. SingularSDKObjectスクリプトコンポーネントを追加し、SingularSDK スクリプトを選択します。

  3. SingularSDKObject の Inspection ペインでSingular SDK KeySDK Secretをそれぞれのフィールドに貼り付けます。SDKキーとシークレットを取得するには、Singularアカウントにログインし、"Developer Tools > SDK Integration > SDK Keys") にアクセスしてください。

    Singular SDK KeyとSecretが正しく適用されていない場合、データはSingularに送信されません。
    Singular SDKコンソールを使用して実装をテストし、正しい動作を確認してください。

注: SingularSDKObject のデフォルトの検査ペイン設定

検査ペインでは以下のオプションが有効になっています:

  • Initialize On Awake (チェック済み)

    この設定により、UnityはアプリのAwakeステータスに基づいてSingular SDKの初期化を制御できるようになります。

    アプリ要件のプライバシーコンプライアンスに従い、必要に応じてこのオプションを更新してください。このオプションのチェックを外すと、AwakeステータスでのSingular SDKの初期化が無効になり、手動での初期化が必要になります。

  • SKAN Enabled (チェック済み)

    Unity SDKバージョン4.0.17から、 SKAdNetworkはデフォルトで有効になって います。マネージドモード(Singularダッシュボードで選択した変換モデルを使用してSKAN変換値をSingularが更新するモード)では有効です。

    最新バージョンのSDKを使用している限り、SKAdNetworkを使用するために他の何かを設定したり、コードを追加したりする必要はありません。

  • Wait For Tracking Authorization 0(オフ)に設定

    アプリがApp Tracking Transparency(ATT)プロンプトを表示している場合、このタイムアウトを300秒に設定することをお勧めします。タイムアウトを追加すると、Singular SDKのセッションが遅延し、Singularのサーバーにイベントを記録する前に、ユーザーがAppTrackingTransparency Consentを承認/拒否できるようになります。ユーザーがATTプロンプトに応答すると、Singular SDKは遅延なく続行します。ATTを表示しない場合は、このオプションのデフォルト値は0(待機なし)のままにしてください。

  • Enable Logging (チェックした)

    Singular SDKからの詳細ログを有効にします。ログレベル」オプションと一緒に使用する必要があります。

  • Log Level 3 に設定

    Singular SDKがLogCat出力に警告ログを表示できるようにします。

  • Ddl Timeout Sec 0に設定

    デフォルトでは、"0 "の設定は60秒のタイムアウトを使用します。 これはSingularサーバーに、最後のタッチアトリビュートに結びついたディープリンクの値を検索する時間を指定します。遅延されたディープリンクが見つかった場合、SDK Sessonのレスポンスでアプリに返され、処理されます。 60秒以内に遅延されたディープリンクが見つからなかった場合、サーバーは検索を停止します。

  • Session Timeout Sec 0に設定

    アプリがバックグラウンドになり、フォアグラウンドに戻ったときにSingular SDKが新しいセッションを登録するまでのタイムアウトを秒単位で指定します。デフォルトでは、"0 "の設定は60秒のタイムアウトを使用します。必要であれば、より大きなウィンドウのためにこの設定を調整することができます。

  • Shortlink Resolve Timeout 0に設定

    デフォルトでは、"0 "の設定は10秒間のタイムアウトを使用します。 このタイムアウトはユーザーエクスペリエンスを保護し、指定されたショートリンクが指定された時間内に解決されない場合、Singular SDKによってディープリンクハンドラーがトリガーされることはありません。

その他の検査ペインオプション

Facebookを有効にする (METAインストールリファラー)

METAInstall ReferrerAttributionメソッドをサポートするには、SingularSDKObjectのInspection PaneにFacebook App IDを追加します。

  1. メインシーンで SingularSDKObject をクリックします。
  2. Inspection Paneを開き、"Facebook App ID "フィールドを見つけます。
  3. Facebook App IDを追加します。

2.2.SKAdNetworkの使用

Unity SDKバージョン4.0.17から、 SKAdNetworkはデフォルトで有効になって います。SKAdNetworkはマネージドモード(Singularダッシュボードで選択したコンバージョンモデルを使用してSKANコンバージョン値を更新するモード)で有効です。

最新バージョンのSDKを使用している限り、SKAdNetworkを使用するために他に何かを設定したり、コードを追加したりする必要はありません。

追加情報

旧バージョンのSDKでSKAdNetworkを有効にする

古いバージョンのSDKを使用している場合、以下のいずれかの方法でSKAdNetworkを有効にする必要があります:

  • SingularSDKObject にアクセスし、SKANEnabledTrue に設定します。
  • アプリのコードでSingularSDK.SkanRegisterAppForAdNetworkAttribution()を呼び出します。
手動モードで SKAdNetwork を使用する(上級者向け)

独自のロジックを使用して SKAN の変換値を手動で管理する場合は、次のようにする必要があります:

  • SingularSDKObjectmanualSKANConversionManagementを Trueに設定します。
  • コード内で以下のメソッドを使用して、変換値を設定および取得します。
SingularSDK.SkanUpdateConversionValue メソッド
説明

SKAdNetworkの変換値を更新します。

注意: このメソッドは、SKAdNetwork 変換値を手動で更新することを選択した場合に使用します。このメソッドは、manualSKANConversionManagementTrue に設定されている場合にのみ動作します。

署名 public void SkanUpdateConversionValue(int value)
使用例
// サイン会開催
Singular.Event("SignUp");

// 変換値を7に更新
SingularSDK.SkanUpdateConversionValue(7);
SingularSDK.SkanGetConversionValue メソッド
説明 Singular SDKによって追跡されている現在の変換値を取得します。
シグネチャ public int? SkanGetConversionValue()
使用例
int? value = SingularSDK.SkanGetConversionValue();
SingularSDK.SetConversionValueUpdatedHandler メソッド
説明 変換値が更新されたときに通知を受け取るハンドラを設定します。
シグネチャ public void SetConversionValueUpdatedHandler(SingularConversionValueUpdatedHandler handler)
使用例
public class Main : MonoBehaviour, SingularConversionValueUpdatedHandler {
  void Awake() {
    SingularSDK.SetConversionValueUpdatedHandler(this);
  }

  void OnConversionValueUpdated(int value) {
    // 変換値を使用する
  }
}

2.3.iOSのApp Tracking Transparency(ATT)同意の処理

App Tracking Transparency(ATT)プロンプトを表示していますか?

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

Singularは、デバイスを特定し、インストールアトリビューションを実行するために、IDFAを取得することで非常にメリットがあります(ただし、IDFAなしでアトリビューションを実行する方法もあります)。IDFAを取得するために、ユーザーの同意を求めることを強くお勧めします。

ユーザーがATTプロンプトに応答するまで、Singular SDKの初期化を遅らせることをお勧めします。

デフォルトでは、Singular SDKは初期化時にユーザーセッションを送信します。新しいデバイスからセッションが送信されると、Singularのアトリビューションプロセス(その時点でSingularが利用可能なデータのみに基づいて実行される)が即座にトリガーされます。したがって、Singular SDKが最初のセッションを送信する 前に同意を求め、IDFAを取得することが重要です。

ヒント: アプリがApp Tracking Transparency(ATT)プロンプトを表示している場合は、タイムアウトを300秒に設定することを推奨します。ATTを表示していない場合、 このオプションのデフォルト値は0(待機なし)のままにしてください。

waitForTrackingAuthorizationWithTimeoutInterval を設定するには、SingularSDKObject Inspection ペインの設定オプションを調整する。これは、Singular SDKがSingularのサーバーにイベントを記録する前に、ユーザーがAppTrackingTransparency Consentを承認/拒否するのを待つ最大時間(秒)を設定します。

2.4.ディープリンクの処理

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

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

以下の手順で方法を説明します:

  1. アプリを開くきっかけとなったトラッキングリンクにアクセスする、
  2. ディープリンク先を読み取る
  3. 適切なコンテンツを表示する。

注意事項

ディープリンクの設定 前提条件

  1. iOSとAndroidの前提条件: Singular Links Prerequisitesの説明に従ってください。

  2. Unity用の追加セットアップ:アプリのAndroidManifest.xml ファイルで、アクティビティ名のプロパティをデフォルトのUnityPlayerActivity:

    <activity android:name="com.unity3d.player.UnityPlayerActivity"

    に変更します:

    <activity android:name="com.singular.unitybridge.SingularUnityActivity"

    に変更します

    注: カスタム・アクティビティを実装している場合は、アクティビティのonNewIntentでこのメソッドを呼び出します:

    @Override
    protected void onNewIntent(Intent intent) {
        setIntent(intent);
    
        // カスタム・アクティビティからonNewIntentでこのメソッドを呼び出します。
        SingularUnityBridge.onNewIntent(intent);
    }

ディープリンクハンドラの追加

Singular SDKは、アプリを開くきっかけとなったトラッキングリンクの詳細を読み取るハンドラメカニズムを提供します。

ハンドラを使用するには

  1. SingularLinkHandler インターフェースを実装します。
  2. クラス内の任意の場所でSetSingularLinkHandler メソッドを呼び出し、クラスをディープリンクのハンドラとして登録します。
  3. SetSingularLinkHandler を呼び出すと、Singular SDK はトラッキングリンクを取得し、OnSingularLinkResolved メソッドを呼び出し、トラッキングリンクの詳細を渡します。リンクの詳細を読み込んで処理するには、このメソッドをオーバーライドします。

次のサンプルコードは3つのステップを示しています:

public class Main : SingularLinkHandler {
    // ...
    void Awake () {
      // クラスをSingular Linkハンドラとして登録します。
      // このメソッドは、アプリの実行中のどの時点でも呼び出すことができます。トラッキングリンクの詳細を取得し、OnSingularLnkResolvedを呼び出します。
      SingularSDK.SetSingularLinkHandler(this);
    }
    
    public void OnSingularLinkResolved(SingularLinkParams linkParams) {
      // リンクの管理]ページで設定されたディープリンク先
      string deeplink = linkParams.Deeplink;
      
      // リンクにパススルー・パラメータが追加されている場合。
      string passthrough = linkParams.Passthrough;
      
      // 遅延ディープリンクとして設定されたリンクかどうか。
      bool isLinkDeferred = linkParams.IsDeferred;
      
      // ディープリンクを処理するコードをここに追加する
    }
    
    // ...

メソッドの参照

SetSingularLinkHandler
SetSingularLinkHandler メソッド
説明 アプリを開くきっかけとなったトラッキングリンクの詳細を取得するハンドラを登録します。
シグネチャ
public void SetSingularLinkHandler(SingularLinkHandler 
handler)
使用例
public class Main : MonoBehaviour, SingularLinkHandler {
    void Awake () {
        SingularSDK.SetSingularLinkHandler(this)
    }
}
OnSingularLinkResolved
OnSingularLinkResolved Method
説明 SetSingularLinkHandler. のコールバックメソッド トラッキングリンクの詳細を読み込んで処理します。
シグネチャ
public void OnSingularLinkResolved(SingularLinkParams
linkParams)

注意: SingularLinkParams オブジェクトには以下の値が含まれます:

  • Deeplink - Singular プラットフォームの Manage Links ページで設定されたディープリンク先。
  • Passthrough - リンクに追加されたパススルーパラメータ(もしあれば)。
  • IsDeferred - リンクが遅延ディープリンクとして設定されているかどうか。
使用例
public void OnSingularLinkResolved(SingularLinkParams
linkParams){ // トラッキング・リンクの詳細を読み、記録する Debug.Log("deeplink: " + linkParams.Deeplink); Debug.Log("passthrough: " + linkParams.Passthrough); Debug.Log("is_deferred: " + linkParams.IsDeferred); }

レガシーリンクでのディープリンクの処理

Singularの古いお客様であれば、新しいSingular Linksではなく、レガシーリンク(Singularの古いトラッキングリンクの仕組み)を使用している可能性があります。 レガシーリンクはCreate LinkView Links ページで管理され、ディープリンクとディファードディープリンクの機能も提供します。

あなたの組織でレガシーリンクを使う場合は、上記の SingularLinksHandler の代わりにSingularDeferredDeepLinkHandler というディープリンク用のハンドラを実装する必要があります。実装は非常に似ています。

2.5.SDKの初期化

注意:Singular SDKを実装する際には、GDPR、CCPA、COPPAなど、ビジネスを展開している地域で制定されている様々なプライバシー法を遵守することを忘れないでください。詳しくはSDKのオプトインとオプトアウトをご覧ください。

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

デフォルトでは、SingularSDK.csはシーンが作成されると、Awakeメソッドを通して自動的にSDKを初期化します。

手動での初期化

アプリの実行の後の時点でSDKを手動で初期化したい場合は、次のようにしてください:

  1. SingularSDK オブジェクトの検査ペインでInitialize on Awake オプションを無効にします。
  2. SingularSDK.InitializeSingularSDK 静的メソッドを使用してSDKを初期化します:
SingularSDK.InitializeSingularSDKメソッド
説明 SingularSDKがAwake時に初期化されていない場合、初期化します。
シグネチャ
public void InitializeSingularSDK()
使用例
// SDKキーとSDKシークレットは
// SingularSDKに関連するゲームオブジェクト SingularSDK.InitializeSingularSDK();

スレッドセーフに関する注意: Singular Unity SDKは、他のUnityメソッドを呼び出すのと同じように、常に同じスレッドから呼び出す必要があります。

2.6.セッションタイムアウトの設定(オプション)

デフォルトでは、アプリがバックグラウンドで60秒以上実行されてからフォアグラウンドに戻ると、Singular SDKは新しいセッションを登録します。デフォルトのタイムアウト値は、SingularSDKObjectのSession Timeout Sec プロパティを変更することで変更できます。

2.7.ユーザー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 を呼び出します。

SingularSDK.SetCustomUserId メソッド
説明 ユーザーIDをSingularに送信します。
シグネチャ public void SetCustomUserId(string customUserId)
使用例
SingularSDK.SetCustomUserId("custom_user_id");
SingularSDK.UnsetCustomUserId メソッド
説明 Singular に送信されたユーザー ID の設定を解除します。
シグネチャ public void UnsetCustomUserId()
使用例
SingularSDK.UnsetCustomUserId();

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

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

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

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

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

3.イベントと収益のトラッキング

3.1. イベントのトラッキング(非収入)

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

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

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

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

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

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

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

SingularSDK.Event メソッド
説明 トラッキングのためにユーザーイベントをSingularに送信する。
署名
public static void Event(string name)
public static void Event(string name, params object[] args)
public static void Event(Dictionary<string, object> args,
string name)

注: ディクショナリを渡す場合、ディクショナリ値はこれらの型のいずれかでなければならない: string, int, long, float, double, null, ArrayList, Dictionary<String,object>

使用例

// 標準イベントを送信 ログイン
SingularSDK.Event(sngLogin);
  
// 2つのキーと値のペアを渡すカスタム・イベントの例
SingularSDK.Event("Myevent", "Key1", "Value1", "Key2", 1234);
// 辞書を渡すJSONEventの例 SingularSDK.Event(new Dictionary<string, object>() { {"Key1", "Value1"}, {"Key2", new Dictionary<string, object>() { {"SubKey1", "SubValue1"}, {"SubKey2", "SubValue2"} } }}, "JSONEvent");

3.2.収益のトラッキング

Singularは、キャンペーンのパフォーマンスやROIの分析に役立てるため、アプリを通じて得た収益に関するデータを収集することができます。Singularはレポート、ログエクスポート、ポストバックでデータを利用できるようにします。

注意事項 異なる通貨で報告された収益は、Singularアカウントで設定された組織の優先通貨に自動変換されます。

UnityのビルトインIAP(アプリ内課金)オブジェクトを使って収益イベントをトラッキングできます。こうすることで、Singularは購入に関するすべての情報を取得し、より豊富なレポートを作成できます。Singularは購入レシートも取得し、これをバックエンドで使用して購入を検証し、アトリビューション詐欺を除外します。

SingularSDK.InAppPurchase メソッド
説明 IAP商品をSingularに送信し、購入イベントを追跡します。
署名
public static void InAppPurchase(Product product,
Dictionary<string, object> attributes, bool isRestored = false)
public static void InAppPurchase(string eventName,
Product product, Dictionary<string, object> attributes,
bool isRestored = false)
public static void InAppPurchase(IEnumerable<Product> products, Dictionary<string, object> attributes, bool isRestored = false)
public static void InAppPurchase(string eventName,
IEnumerable<Product> products, Dictionary<string, object>
attributes, bool isRestored = false)

注s:

  • product はIAPから受け取った製品オブジェクトである: UnityEngine.Purchasing.Product
  • attributes:Singularに追加情報を渡すにはこのパラメータを使います。渡す属性がない場合は null を渡してください。
  • isRestored:トランザクションがリストアされるかどうかを示す。デフォルト:false
使用例
// 単品でIAP、追加属性なし
SingularSDK.InAppPurchase(myProduct, null);
// 単一の製品と属性を持つIAP
var attr = new Dictionary<string, object>() {
["my_first_attribute"] = "value1",
["my_second_attribute"] = "value2"};
 
SingularSDK.InAppPurchase(myProduct, attr);

// 単一の製品、余分な属性なし、カスタムイベント名を持つIAP。

SingularSDK.InAppPurchase("MyCustomProduct",
myProduct, null);

// 製品リスト付きIAP、余分な属性なし
SingularSDK.InAppPurchase(myProductList, null);

// 商品リスト、余分な属性なし、カスタム・イベント名を持つIAP

SingularSDK.InAppPurchase("MyCustomProducts",
myProductList, null);
収益を追跡する別の方法:Revenue メソッドと CustomRevenue メソッド

Unity IAPを使用できない場合、Singular SDKは購入に関する情報を "手動で "Singularに渡すための2つのメソッドを提供します:

  • Revenueを使用して、取引通貨、取引金額、その他オプションの詳細情報をSingularに渡します。
  • CustomRevenueはよく似ていますが、イベントにカスタム名を付けることができます。

注意:InAppPurchaseの代わりにRevenue/CustomRevenueを使用すると、Singularは購入レシートを確認できません。

SingularSDK.Revenueメソッド
説明 収益イベントをSingularに送る。
署名
public static void Revenue(string currency, double amount)

public static void Revenue(string currency,
double amount, string productSKU, string productName,
string productCategory, int productQuantity, double productPrice)
注: 通貨を3文字のISO 4217通貨コードで渡します。 "USD", "EUR", "INR".
使用例
// 商品詳細のない収益イベントを送信する
SingularSDK.Revenue("USD", 9.99);

// 商品詳細を含む収益イベントを送信する
SingularSDK.Revenue("USD", 50.50, "abc123", "myProductName", 
"myProductCategory", 2, 25.50)
SingularSDK.CustomRevenueメソッド
説明 カスタム名の収益イベントをSingularに送信する。
署名
public static void CustomRevenue(string eventName, 
string currency, double amount) public static void CustomRevenue(string eventName,
string currency, double amount, string productSKU,
string productName, string productCategory, int productQuantity,
double productPrice)
注: 通貨を3文字のISO 4217通貨コードで渡します。 "USD", "EUR", "INR".
使用例
// カスタム名で収益イベントを送信する
SingularSDK.CustomRevenue("MyCustomRevenue", "USD", 9.99);

// カスタム名+商品詳細で収益イベントを送信する
SingularSDK.CustomRevenue("MyCustomRevenue", "USD", 50.50, 
"abc123", "myProductName", "myProductCategory", 2, 25.50)

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

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を追加する必要があります。こちらのガイドに従ってください。

4.高度なオプション

4.1.ショートリファラーリンクの作成

注:この機能はSDKバージョン4.0.16+で利用可能です。

ショートリンクを使用すると、パラメータがいっぱいの長いシンギュラーリンクを、共有に便利な短くて安全なリンクに変換できます。

通常、ショートリンクを動的に作成し、アプリのユーザーが友達と共有してアプリの使用を招待できるようにします。

ショートリンクを作成するには

  • アプリのダウンロードにつながるシンギュラーリンクシンギュラーリンクのFAQを参照)。
  • リンクに動的に追加したいパラメータ(オプションの一覧はトラッキングリンクパラメータをご覧ください)。
  • アプリの新規インストールを、リンクを共有したユーザーまで追跡したい場合は、参照ユーザーの名前とID

createReferrerShortLinkメソッドを使用して、以下の例のようにショートリンクを作成します。

void callback(string shortLinkURL, string error){
    // shortLinkURLがNULLでない場合、ここに共有ロジックを追加する。エラーが発生した場合は、エラーの原因に応じて、関数に渡されたパラメータを再試行/中止/変更するロジックを追加します。
}

SingularSDK.createReferrerShortLink(
    "https://sample.sng.link/B4tbm/v8fp?_dl=https%3A%2F%2Fabc.com",
    "John Doe", // 紹介者名
    "342", // リファラーID
    new Dictionary<string, string>() { 
        // 追加したいパラメータを含む辞書オブジェクト
        {"channel", "sms"}
    },
    callback 
);

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

注意: バージョン 3.0.0 から、Singular SDK で広告収益帰属を設定するオプションが追加されました。

広告収益アトリビューションは、アプリのSingular SDKを更新しなくても、APIコールを使用する従来の方法で設定できます。ただし、SKAdNetworkキャンペーンの広告収益を測定したい場合は、SDKを通して広告収益アトリビューションを設定する必要があります。

Singular SDKに広告収益アトリビューションサポートを追加する:

  1. Singular SDKを最新バージョンにアップデートします。
  2. 広告収益データに使用しているメディエーションプラットフォームに応じて、適切なコードスニペットをSingular SDKインテグレーションに追加します。

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

アドモブ
    1. 注: この機能はAdmobアカウントで有効にする必要があります。

      See https://support.google.com/admob/answer/11322405#getstarted

注: Google AdMob Unity SDKが変更されました!

Google AdMob Unity SDKの最新バージョンおよび旧バージョンへの移行について詳しくは、こちらをご覧ください。こちらのGoogleドキュメントをご覧ください: Google AdMobモバイル広告SDK(Unity)マイグレーション

Admob Unity SDK v8.0.0+ (C#) Admob Unity SDK Legacy (C#)

以下のコードはAdmob Unity SDK v8.0.0+用です。

リワード広告イベントをリッスンする。 Google AdMob ドキュメント こちら

private void RegisterEventHandlers(RewardedAd ad)
{
// 広告の収益が見積もられた時点で引き上げられる。
ad.OnAdPaid += (AdValue adValue) =>
{
    // 特異なAdMonイベントの構築と送信
    SingularAdData data = new SingularAdData(
       "Admob",
        adValue.CurrencyCode,
        adValue.Value/1000000f);
    Singular.AdRevenue(data);
};
}
AppLovinMax
  1. AppLovin MAXのイベントOnInterstitialAdRevenuePaidEventから受け取ったオブジェクトを取得する。
C#
MaxSdkBase.AdInfo impressionData;
string adUnitId;
double revenue = MaxSdk.GetAdInfo(adUnitId).Revenue;

SingularAdData data = new SingularAdData(
"AppLovin",
"USD",
revenue); Singular.AdRevenue(data);
アイアンソース
  1. IronSourceのイベントOnImpressionSuccessから受け取ったオブジェクトを取得します。
  2. IronSourceのARM SDK Postbacksフラグがオンになっていることを確認してください。
  3. を参照。https://developers.is.com/ironsource-mobile/general/ad-revenue-measurement-postbacks/#step-1
C#
IronSourceImpressionData impressionData;
SingularAdData data = new SingularAdData(
"IronSource",
"USD",
impressionData.revenue); Singular.AdRevenue(data);
TradPlus
  1. TradplusAdsイベントから受信したオブジェクトを取得する:AddGlobalAdImpression
  2. TradPlusAdImpressionコールバックにSingularを追加する
C#
TradplusAds.Instance().AddGlobalAdImpression(OnGlobalAdImpression);

void OnGlobalAdImpression(Dictionary<string, object="object"> adInfo) {
   double revenue = 0;
   double.TryParse(
adInfo["ecpm"].ToString(),
NumberStyles.Float| NumberStyles.AllowThousands,
CultureInfo.InvariantCulture, out revenue); if(revenue != 0) revenue = revenue / 1000; SingularAdData data = new SingularAdData(
"TradPlus",
"USD",
revenue); SingularSDK.AdRevenue(data); }
その他(汎用)
  1. SingularAdDataオブジェクトを関連データで初期化する。
  2. データをSingularに報告
C#
SingularAdData data = new SingularAdData(
   あなたの広告プラットフォーム,
   通貨コード,
   9.90);

SingularSDK.AdRevenue(data);

4.3.アンインストールの追跡

:アンインストールの追跡は、エンタープライズのお客様のみご利用いただけます。

Android のアンインストール追跡

Android アプリのアンインストールトラッキングを有効にするには、まず、 アンインストールトラッキングの設定の詳細に従って、Singular プラットフォームでアプリを設定します。 その後、以下の手順に従ってください。

注: Googleは2018年4月にGCM APIを廃止しました。アンインストールトラッキングにはFCMを使用してください。

Firebase Cloud Messaging (FCM) を使用してアンインストールトラッキングを有効にする:

1.FCMと統合します:

アンインストールをトラッキングするには、Firebase Cloud Messaging (FCM) プラットフォームのサービスを利用できます。FCM をまだ使用していない場合は、 Android で Firebase Cloud Messaging クライアントアプリをセットアップする方法について Google の説明に従ってください。

FCMの要件(ソース)

FCMクライアントは、Google PlayストアアプリがインストールされたAndroid 4.1以上を実行するデバイス、またはGoogle APIがインストールされたAndroid 4.1を実行するエミュレータが必要です。なお、AndroidアプリのデプロイはGoogle Playストアに限定されません。

サポートされているバージョンのAndroidで動作していないユーザー/デバイスは、Singularアンインストールトラッキングの対象外となります。

2.AndroidManifest.xml ファイルを更新します:

AndroidManifest.xml ファイルを更新して、アプリに必要なインテント フィルタを追加します(MyFirebaseMessagingService を Firebase Service を実装するクラスで置き換えます):

<service android:name=".java.MyFirebaseMessagingService" android:exported="false">
  <intent-filter>
    <action android:name="com.google.firebase.MESSAGING_EVENT" />
  </intent-filter> 
</service>

3.FCM デバイストークンを登録し、送信します:

FCM トークンを取得したら、'RegisterTokenForUninstall' メソッドにパラメータとして渡します:

SingularSDK.RegisterTokenForUninstall(String fcmDeviceToken);

RegisterTokenForUninstall' メソッドは、'SingularSDK.InitializeSingularSDK()' メソッドの前に呼び出す必要があることに注意してください。

iOS のアンインストールトラッキング

iOS のアンインストールトラッキングは、Apple のプッシュ通知技術に基づいています。アプリが現在プッシュ通知をサポートしていない場合は、Apple の ガイドを参照してください。 アプリがすでにプッシュ通知をサポートしている場合は、SDK の初期化後に RegisterTokenForUninstall メソッドを使用して APNS から返されたデバイストークンを渡すだけです。

SingularSDK.RegisterTokenForUninstall メソッド
説明 APNSから返されたデバイス・トークンを渡す。APNSトークンは通常ネイティブ形式のバイナリデータですが、文字列として渡す必要があることに注意してください。
署名
public static void RegisterTokenForUninstall
(string APNSToken)
使用例
// APNSトークンを16進文字列として渡す。
  SingularSDK.RegisterTokenForUninstall("ba85ab31a7c7
f5c2f012587f29fb0e596d4b67e7b7b2838fa1a8582c1f7dbdee");

4.4.グローバルプロパティの追加

Singular SDK では、アプリから送信されるセッションやイベントごとに Singular サーバーに送信する追加のカスタムプロパティを定義できます。 これらのプロパティは、ユーザー、アプリのモードやステータスなど、任意の情報を表すことができます。これらのプロパティを設定すると、レポートのディメンションとして使用できるようになり、データを分解するために使用できます。

例えば、ゲームアプリがある場合、"Level "というプロパティを定義し、初期値として "0 "を設定することができます。アプリから送信されるすべてのセッションとイベントは、"Level":"0".ユーザがレベルアップしたら、プロパティを "1 "にリセットします。すると、セッション数、イベント数、収益データなどのレポートをユーザーレベル別に取得することができます。

  • グローバル・プロパティは5つまで定義できます。
  • これらのプロパティは、あなたが設定を解除するか、ユーザーがアプリをアンインストールするまで、アプリの実行中(あなたが与えた最新の値で)持続します。
  • 各プロパティ名と値の長さは200文字までです。これより長いプロパティ名や値を渡すと、200文字に切り詰められます。
  • グローバル・プロパティにはアクセス可能で、ユーザレベルのエクスポートと ポストバックで使用できます。将来的には、集計レポートのサポートが追加される予定です。グローバルプロパティのサポートに関するご質問やアップデートにご興味がある場合は、Singularカスタマーサクセスマネージャーにお知らせください!

初期化前のグローバルプロパティの設定

SetGlobalProperty メソッドを使用して、SDKを初期化する前にSingularSDKを通してグローバルプロパティを設定することができます。 グローバルプロパティをセッションに含めたい場合は、'Initialize On awake'フラグをオフにしてください。

グローバルプロパティとその値はアプリの実行間で持続するため、設定しようとしているプロパティがすでに別の値に設定されている可能性があることに注意してください。既存のプロパティを新しい値で上書きするかどうかをSDKに指示するには、overrideExistingパラメータを使用します。

初期化後のグローバル・プロパティの設定

アプリの実行中いつでもグローバル・プロパティを設定、解除、取得するには、以下のメソッドを使用します。

SingularSDK.SetGlobalProperty 方法
説明

グローバル・プロパティを指定された値に設定する。

注s:

  • プロパティがまだ存在せず、他の 5 つのグローバル・プロパティが既に存在する場合、プロパティは追加されません。
  • プロパティが既に設定されている場合、overrideExisting パラメータは、既存の値をオーバーライドするかどうかを決定します。
  • このメソッドは、プロパティが正常に設定された場合は true を返し、そうでない場合は false を返します。
署名 public static bool SetGlobalProperty(string key, string value, bool overrideExisting)
使用例
bool result = SingularSDK.SetGlobalProperty("key", "value", false);
SingularSDK.GetGlobalProperties 方法
説明 すべてのグローバル・プロパティとその現在の値を Map として取得する。
署名 public static Dictionary<string, string> GetGlobalProperties()
使用例
Dictionary<string, string> props = SingularSDK.GetGlobalProperties();
SingularSDK.UnsetGlobalProperty 方法
説明 グローバル・プロパティを削除する。
署名 public static void UnsetGlobalProperty(string key)
使用例
SingularSDK.UnsetGlobalProperty(“test_key”);
SingularSDK.ClearGlobalProperties 方法
説明 すべてのグローバルプロパティを削除する。
署名 public static void ClearGlobalProperties()
使用例
SingularSDK.clearGlobalProperties();

4.5.古い Android デバイスでのインストール・リファラの収集

Android では、インストールリファラーは、Singular が不正行為を検出および分析するのに役立つだけでなく、アトリビューションを決定するための最も正確なツールです。これはGoogle Playストアが提供する識別子で、ユーザーがアプリをインストールする前にクリックした広告を指します。

最新バージョンのGoogle Playストアがあるデバイスでは、Singular SDKはインストールリファラーの値を自動的に収集します(Singularは最新のGoogle Play Referrer APIと統合されているため)。

古いデバイスでインストールリファラーを収集するには、Android SDKガイドの指示に従ってください。

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

5.1.データ共有の制限

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

データ共有の制限

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

  • limitDataSharing:NOを使用して、ユーザーが情報の共有に同意した (オプトインした) ことを示します。
  • ユーザーが同意しなかった場合はlimitDataSharing:YES を使用します。

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

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

SingularSDK.LimitDataSharing 方法
署名 SingularSDK.LimitDataSharing(bool shouldLimitDataSharing)
説明 個人データの共有に関するユーザーの同意(オプトイン)をSingularに通知する。
使用例
// ユーザーがデータ共有に同意した
SingularSDK.LimitDataSharing(false);

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

Singular SDKは、お客様がGDPRポリシーに準拠し、トラッキングに対するユーザーの同意または非同意についてSingularに知らせるのに役立ついくつかの方法を提供します。

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