UnityパッケージマネージャSDK統合ガイド

 

始める前にSDKの前提条件

  • Singular SDKを統合する」の手順に従ってください:計画と前提条件
    これらのステップはSingular SDKを統合するための前提条件です。
  • Google EDM4U(Google External Dependency Manager for Unity)を使用しているか確認してください。
    Google EDM4Uとは何ですか?詳しくはこちらをご覧ください。
警告:バージョン5.3.0へのアップグレード時の変更点

バージョン5.3.0の時点で、プロジェクトがアプリ内課金を使用する場合、SingularはUnity In-App Purchase (IAP)ライブラリを必須の依存関係として必要とします。これはUnity Package Manager(package.json)を介してUnityプロジェクトにインポートする必要があります。

Singular Unity SDKでIAP関数へのアクセスを有効にする手順。

ステップ 1: Unity IAP を UPM 経由でインストールします:

  1. パッケージマネージャを開きます: Unity EditorでWindow Package Managerに移動します。
  2. Unity レジストリを選択します: Package Manager ウィンドウで、上部のドロップダウンメニューから Unity Registry を選択します。
  3. Unity IAPを検索します: リストをスクロールするか、検索バーを使ってアプリ内課金またはUnity IAPを探します。
  4. パッケージをインストールします: In-App Purchasingを見つけたらクリックし、右パネルのInstallボタンをクリックします。
  5. インストールを確認します: インストールが完了すると、Unityは自動的に必要なアセットと依存関係をプロジェクトに追加します。

ステップ2:スクリプトの設定 シンボルを定義します:

各プラットフォーム(AndroidとiOS)に対して、以下のスクリプティング定義シンボルを設定します:

  1. Player Settings > Player > Android/iOS > Script Compilationに移動します。
  2. スクリプト定義シンボルフィールドに「SINGULAR_SDK_IAP_ENABLED」を追加します。
    PlayerSettingIAP.png

    これはUnity EditorまたはUnity Cloud Dashboardから実行できます。

警告:上記の手順のいずれかが正しく完了していないと、コンパイル時にエラーが発生し、プロジェクトが正常にビルドされない可能性があります。

警告: .unitypackage」から「UPM」SDKバージョンにアップグレードしていますか?以下に示すように、特定のアップグレード手順を実行する必要があります!
重要: UPM SDK のインストールを進める前に、以下のアップグ レード手順を実行してください。

アップグレードを行うには、.unitypackageから非推奨の統合プロセスを使用してインポートされた既存のSingular SDKファイルを手動で削除する必要があります。
これは Unity Package Manager (UPM)でSDKをインポートする前に完了しておく必要があります!

Unity Package Manager(UPM)を使用してSDKを統合する前に、以下のファイルのリストを削除してください。特に注意して、ここに記載されているSingularファイルのみを削除してください:

  1. プロジェクトの/Codeフォルダから:
    unity_upgrade_code_folder_file_removal.png

  2. プロジェクトの/Codeフォルダから:プロジェクトの/Plugins/Androidフォルダから、AARとJARを削除します:
    unity_upgrade_plugin_android_folder_file_removal.png

  3. プロジェクトの/Plugins/iOSフォルダから、iOSの.hファイルと.mファイル、および.xcframeworkを削除します:
    unity_upgrade_plugin_ios_folder_file_removal.png

1.SDKのインストール

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

Unity Package Manager (UPM)を使用したSingular Unity SDKのインストール
  1. Package Managerウィンドウで

    • ボタンをクリックします。
    • "Add package from git URL" を選択
    • 非Kids SDKの場合
      Singular Unity SDKのGitHub URLを入力:
      https://github.com/singular-labs/Singular-Unity-SDK.git
    • キッズSDKの場合
      Singular Unity Kids SDK の GitHub URL:
      https://github.com/singular-labs/Singular-Unity-SDK.git#kids
      を入力します。

    unity-git-url.png

  2. 追加」ボタンをクリックしてください。
重要:GoogleのEDM4Uを使用していない場合は、以下の手順に従ってください。

1.2.Android用の設定

ヒント: Unityを使用する場合、AndroidManifestをどのように更新しますか?
  1. Unity v2018.3以降では、Playerウィンドウの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プロパティを有効にするだけで、独自のGradleビルドファイルを追加できます(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にアクセスすることができます。

Proguard を使用していますか?

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

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

1.3.iOS 用のヒント

ヒント:Unityでビルドした後、Xcodeでビルドする前にCocoa Podsをアップデートしてください。

Podsがあるフォルダから以下のコマンドを実行することをお勧めします。

pod repo update
pod update
ヒント: applicationDidBecomeActive()からIDFV識別子をログに記録する。

iOSでテストする場合は、以下のコードを:Classes > UnityAppController > applicationDidBecomeActivefunction.

// Printing Identifier for Vendor (IDFV) to Xcode Console for use in Singular SDK Console


NSLog(@"Singular === IDFV: %@", [[[UIDevice currentDevice] identifierForVendor] UUIDString]);

idfv.png

これにより、Xcode Logs の App Open でIDFV 識別子を取得できるようになります。Singular SDK コンソールでこの識別子を使用して、テストデバイスを追加します。

idfv3.png

ヒント: Deeplink サポートの注意事項
  1. Signing & Capabilities で Associated Domain を追加します。関連ドメインが正しく設定されていないと、Singularトラッキングリンクをクリックしてもアプリは開きません。

  2. チームIDがSingularプラットフォームのアプリのページにも追加されていることを確認してください。これにより、Singularはユニバーサルリンク機能を有効にするために必要なApple App Site Association Fileを構築し、ホストすることができます。

2.SDKの統合

2.1.SingularSDKObjectの作成

SingularSDKObjectを階層に追加します。

Singularプレハブオブジェクトを使ってSingularSDKObjectを追加します。

Singular プレハブオブジェクトを階層ペインに移動します。

  • プロジェクトペインから次の場所に移動します:Packages > Singular > SingularSDK > Prefabs.
  • SingularSDKObject を階層ペインに移動します。
    unity_prefab.png
プレハブのGameObject を使用しない場合は、以下の手順で手動で "SingularSDKObject" GameObject を追加してください。

階層ペインに

  1. メインシーンに空のGameObjectを作成します。
  2. GameObjectに名前を付ける:SingularSDKObjectと名付ける。
    重要: SingularのSDKを機能させるには、GameObjectの名前を "SingularSDKObject "にする必要があります。
  3. SingularSDKObjectをクリックします。
  4. Inspection Paneに移動します。
  5. Inspectionペインから、Add Componentをクリックします。
  6. 検索フィールドに「Singular」と入力し、「Singular SDK」スクリプトを選択します。
    unity_add_script.png

SingularSDKObject の設定を構成します。

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

    sdk_keys.png
    重要: Singular Reporting API Keyを使用しないでください。上記の手順に従って、適切なキーとシークレットを取得してください。
    unity_singularsdkobject_settings.png

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

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

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

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

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

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

    • SKAN有効(チェック済み)

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

    • トラッキング認証を待つWait For Tracking Authorization)、0に設定(オフ

      アプリがApp Tracking Transparency(ATT)プロンプトを表示している場合、このタイムアウトを300秒に設定することを推奨します。このタイムアウトを追加すると、Singular SDKのセッションが遅延し、ユーザーがSingularのサーバーにイベントをログする前にAppTrackingTransparency Consentを承認/拒否できるようになります。ユーザーがATTプロンプトに応答すると、Singular SDKは遅延なく続行します。これにより、同意が提供されたときに、インストール帰属のためのIDFA識別子をキャプチャすることができます。ATTを表示しない場合、このオプションのデフォルト値は0(待機なし)のままにしてください。

    • ログを有効にする(チェック)

      Singular SDKからのログを有効にします。Log Level"オプションと一緒に使用する必要があります。
      "Log Level "は以下のenumマッピングで指定された "int "数値で指定する必要があります。この範囲の数字が小さいほど、ログはより詳細になります。

      //Based on Android Logger.java log levels enum: android.util.Log
      public enum LogLevel {
         Verbose = 2,
         Debug   = 3,
         Info    = 4,
         Warn    = 5,
         Error   = 6,
         Assert  = 7
         }

      注: 現在、ほとんどのログはAndroidでのみ利用可能です。

    • Ddlタイムアウト秒数を0に設定

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

    • セッションタイムアウト秒数を0に設定

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

    • ショートリンク・リゾルブのタイムアウトを0に設定

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

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

    Facebookを有効にする(META Install Referrer)

    META Install Referrer Attribution メソッドをサポートするには、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はデフォルトで有効になっています。 マネージドモード(Singularダッシュボードで選択したコンバージョンモデルを使用して、SKANコンバージョン値をSingularが更新するモード)で有効になります。

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

追加情報

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

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

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

ロジックを使用してSKAN変換値を手動で管理する場合は、以下を実行する必要があります:

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

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

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

シグネチャ public void SkanUpdateConversionValue(int value)
使用例
// A sign-up event happened


Singular.Event("SignUp");

// Update the conversion value to 7


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

  void OnConversionValueUpdated(int value) {
    // Use the conversion 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 SDKが最初のセッションを送信する前に同意を求め、IDFAを取得することが重要です。

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

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

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

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

シングルトラッキングリンクは、ディープリンクと ディファードディープリンクの両方を組み込むことができます。詳細については、ディープリンクFAQと シンギュラーリンクFAQを参照してください。

注意事項

プラットフォームのサポートとハンドラコードの詳細については、以下のセクションを参照してください:

Androidでのディープリンクのサポート

Androidでのディープリンクのサポート

  1. Project > Assets > Plugins > Android > AndroidManifest.xmlファイルをエディタで開きます。
  2. アクティビティ名のプロパティをデフォルトから更新します:
    <activity android:name="com.unity3d.player.UnityPlayerActivity"

    から

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

    または

    重要: カスタムアクティビティを実装している場合:
    1. onNewIntentを実装しているSingularUnityBridgeの インポート文を追加します。

      import com.singular.unitybridge.SingularUnityBridge;
    2. アクティビティのonNewIntentメソッドからSingularUnityBridge.onNewIntent(intent);を呼び出します:

      @Override
      protected void onNewIntent(Intent intent) {
          setIntent(intent);
      
          // Call this method from your custom activity in onNewIntent
      
      
          SingularUnityBridge.onNewIntent(intent);
      }

    警告:アプリ用にカスタムアクティビティを作成し、それがUnity Playerアクティビティを継承していない場合は、現在のアクティビティオブジェクトがNULLである可能性がある場合に対処するために、onNewIntentメソッドにガードを追加することを検討してください。

  3. 適切なアクティビティにIntent Filterを追加して、選択したホスト名でAndroid App Linksをサポートします。hostandroid:hostの値は、トラッキングリンク用に設定されたSingular Linksドメインと一致する必要があります。
    • Singularは、アプリを開くためのAndroid App Linksテクノロジーをサポートしています。
    • Singular Links Androidの前提条件を完了してください。

      サンプルインテントフィルタ:
    <!-- Added Intent Filter for Singular Android Links Deeplinking -->
    <!-- Replace example with your value -->
    <intent-filter android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="http" />
      <data android:scheme="https" />
      <data android:host="example.sng.link" />
      <data android:pathPrefix="/A"/>
      <data android:pathPrefix="/B"/>
      <data android:pathPrefix="/E"/>
      <data android:pathPrefix="/F"/>
    </intent-filter>
iOSでディープリンクをサポートする

iOSでのディープリンクのサポート

SingularはiOSユニバーサルリンクと アプリスキームを使ってiOS上でディープリンクします。以下の手順に従って、Singular LinksでiOSユニバーサルリンクとアプリスキームのディープリンクを使用できるようにしてください。

  1. SingularのAttribution > Manage Linksページで、リンク用に少なくとも1つのサブドメインを設定します。詳細については、Singular Links FAQを参照してください。
  2. ユニバーサルリンク(iOSでのディープリンク)を設定するには:
    • Apple Developer Portalにログインします。
    • Identifiersに移動し、Universal Linksサポートを追加したいアプリを選択します。

      identifiers.png

    • Capabilitiesメニューで、Associated Domainsチェックボックスをチェックし、Saveをクリックします。

      associateddomains.png

  3. Associated Domains "権限をアプリに追加します:
    • XCodeで、Project settings > Capabilities > Associated Domainsに進みます。

    • Singular Linksドメインを追加します。

      associateddomains2.png

  4. Apple Developer Portalから「App Prefix」(別名「Team ID」)をコピーします。
  5. SingularでApps Configurationに行き、アプリを見つけ、iOS App Advanced Settingsを展開し、Team IDフィールドに値を貼り付けます。 これにより、Singularはユニバーサルリンク用の apple-app-site-associationファイルをSingularドメインでホストできるようになります。

    mceclip3.png

  6. 注意:このステップは、Universal Linksがディープリンクできない場合に必要です。
    チームID」の下に、iOSの「アプリスキーム」を入力し、ユニバーサルリンクのディープリンクのフォールバックとして、従来のアプリスキームのディープリンクを有効にします。
    mceclip4.png

    あなたのアプリがディープリンクのためにiOSアプリスキームをサポートするのが初めての場合、アプリスキームがあなたのXcodeプロジェクトで "URLタイプ "として登録されていることを確認してください:
    Screenshot of Xcode showing the URL Types section with a URL that reads "com.example.myphotoapp."

    iOS アプリのアプリスキームのサポートに関する詳細については、このトピックに関する Apple の開発者向けヘルプ記事を参照してください。

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 Key and SDK Secret are set on the 


// game object associated with 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が他者と共有することはありません。
  • Singular SDKメソッドで設定されたユーザーIDの値は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)。

SingularSDK.Event(Events.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>.

使用例

// 1) Send the standard event Login


SingularSDK.Event(Events.sngLogin);
// 2) An example custom event passing two key value pairs


SingularSDK.Event("myEventName", "Key1", "Value1", "Key2", 1234);
// 3) An example JSON Event passing a dictionary


// Create a dictionary for attributes


Dictionary<string, object> attributes = new Dictionary<string, object>();

// Add attributes


attributes["key1"] = "value1";
attributes["key2"] = "value2";
attributes["key3"] = "value3";
// Add more attributes as needed



SingularSDK.Event(attributes, "myEventName");

3.2.収益の追跡

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

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

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

SingularSDK.InAppPurchaseメソッド
説明 購入イベントを追跡するために、Singular に IAP 製品を送信します。
署名
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)

注釈

  • productはIAPから受け取ったproductオブジェクトです:UnityEngine.Purchasing.Productです。
  • 属性です: Singularに追加情報を渡すには、このパラメータを使用します。渡す属性がない場合はnull を渡してください。
  • isRestored: トランザクションが復元されるかどうかを示します。デフォルト:false。
使用例
// IAP with a single product and no extra attributes


SingularSDK.InAppPurchase(myProduct, null);
// IAP with a single product and attributes


var attr = new Dictionary<string, object>() {
["my_first_attribute"] = "value1",
["my_second_attribute"] = "value2"};
 
SingularSDK.InAppPurchase(myProduct, attr);
// IAP with with a single product, 


// no extra attributes and a custom event name



SingularSDK.InAppPurchase("MyCustomProduct",
myProduct, null);
// IAP with list of products, no extra attributes


SingularSDK.InAppPurchase(myProductList, null);
// IAP with with list of products, no extra attributes


// and a custom event name



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)
public static void Revenue(string currency, double amount, Dictionary<string, object> attributes)
注意:通貨は、"USD"、"EUR"、"INR" のような 3 文字の ISO 4217 通貨コードで渡します。
使用例
// Send a revenue event with no product details


SingularSDK.Revenue("USD", 1.99);
// Send a revenue event with product details


SingularSDK.Revenue("USD", 4.99, "coin_package_abc123", "Coin Pack 5", "Bundles", 1, 4.99);
// Send a revenue event with JSON Dictionary for attributes


Dictionary<string, object> attributes = new Dictionary<string, object>();

// Add attributes


attributes["productSKU"] = "coin_package_abc123";
attributes["productName"] = "Coin Pack 5";
attributes["productCategory"] = "Bundles";
attributes["productQuantity"] = 2;
attributes["productPrice"] = 4.99;

SingularSDK.Revenue("USD", 9.98, attributes);
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)
public static void CustomRevenue(string eventName, string currency, double amount, Dictionary<string, object> attributes)
注意:通貨は、"USD"、"EUR"、"INR" のような 3 文字の ISO 4217 通貨コードで渡します。
使用例
// Send a revenue event with a custom name


SingularSDK.CustomRevenue("MyCustomRevenue", "USD", 9.99);
// Send a revenue event with a custom name + product details


SingularSDK.CustomRevenue("MyCustomRevenue", "USD", 50.50, "abc123", "myProductName", "myProductCategory", 2, 25.50);
// Send a revenue event with a custom name + JSON Dictionary for attributes


// Create a dictionary for attributes


Dictionary<string, object> attributes = new Dictionary<string, object>();

// Add attributes


attributes["productSKU"] = "coin_package_abc123";
attributes["productName"] = "Coin Pack 5";
attributes["productCategory"] = "Bundles";
attributes["productQuantity"] = 2;
attributes["productPrice"] = 4.99;
// Add more attributes as needed



SingularSDK.CustomRevenue("MyCustomRevenue", "USD", 9.98, attributes);

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以上でご利用いただけます。

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

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

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

  • アプリのダウンロードにつながるSingularリンクSingularリンクのFAQを参照してください)。
  • リンクに必要なパラメータを動的に追加することができます(オプションのリストはトラッキングリンクパラメータをご覧ください)。
  • 新規アプリのインストールを、リンクを共有したユーザーにさかのぼって追跡したい場合は、参照元ユーザーのリファラー名とリファラーIDを指定する必要があります。

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

void callback(string shortLinkURL, string error){
    // Add your share logic here if shortLinkURL is not null


    // If there was an error, add logic to retry/abort/modify the params


    // passed to the function, based on the cause of the error


}

SingularSDK.createReferrerShortLink(
    "https://sample.sng.link/B4tbm/v8fp?_dl=https%3A%2F%2Fabc.com",
    "John Doe", // Referrer Name


    "342", // Referrer ID


    new Dictionary<string, string>() { 
        // a Dictionary object containing any parameters you want to add


        {"channel", "sms"}
    },
    callback 
);

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

SingularはGoogle AdMob、AppLovin、Unity LevelPlay (IronSource)、TradPlusなどの広告収益アトリビューション用のメディエーションプラットフォームと統合されています。また、Singularは一般的な広告収益SDKの統合により、他のメディエーションプラットフォームもサポートしています。

メディエーションプラットフォームから広告収益アトリビューションデータを取得するには、Singular SDKインテグレーションにコードスニペットを追加します。これにより、SKAdNetworkキャンペーンの広告収入データを取得することもできます。

メディエーションプラットフォームからユーザーレベルの広告収益を取得することで、Singularはこのデータを受け入れることができるメディアソースにアトリビューションされた広告収益を送り返し、AdROASキャンペーンを実施することができます。

SDKの実装方法とコードスニペットはこちら[HERE]をご覧ください。

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

注意:アンインストールのトラッキングは Enterprise のお客様のみご利用いただけます。

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)
使用例
// pass the APNS token as a hex-string 


  SingularSDK.RegisterTokenForUninstall("ba85ab31a7c7
f5c2f012587f29fb0e596d4b67e7b7b2838fa1a8582c1f7dbdee");

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

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

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

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

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

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

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

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

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

SingularSDK.SetGlobalPropertyメソッド
説明

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

注意事項

  • プロパティがまだ存在せず、他のグローバルプロパティがすでに 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(boolshouldLimitDataSharing)
説明 個人データの共有に関するユーザーの同意(オプトイン)を Singular に通知します。Limit Data Sharing メソッドは、アプリが第三者にユーザーデータを送信するかどうかを制御するオプションを提供します。これは、ユーザーの好みやプライバシー要件に基づいてデータ共有を制限したい場合に便利です。
使用例
// User has opted in to sharing data


SingularSDK.LimitDataSharing(false);

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

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

SingularSDK.TrackingOptInメソッド
説明 トラッキングに対するユーザーの同意(オプトイン)をSingularに通知します。TrackingOptIn()メソッドは、Singularのサーバーに "gdpr "イベントを送信するために使用されます。このメソッドを呼び出さない場合、アプリはユーザーが同意したかのようにトラッキングを続けますが、特にGDPRオプトインとしてマークされることはありません。アプリがGDPR(一般データ保護規則)に準拠する必要がある場合は、ユーザーの同意が適切に記録されるように、この関数を呼び出す必要があります。
使用例
SingularSDK.TrackingOptIn();
SingularSDK.StopAllTrackingメソッド
説明 このアプリでのこのユーザーのすべてのトラッキング活動を停止します。
注意: このメソッドは、アプリが再起動した後でも、SDKを効果的に無効にします(状態は永続的です)!トラッキングを再度有効にする唯一の方法は、resumeAllTracking()を呼び出すことです。
使用例
SingularSDK.StopAllTracking();
SingularSDK.ResumeAllTrackingメソッド
説明 このアプリのこのユーザのトラッキングを再開します。
使用例
SingularSDK.ResumeAllTracking();
SingularSDK.IsAllTrackingStopped メソッド
説明 このアプリのこのユーザーのトラッキング状況を確認します。StopAllTracking()を使用してトラッキングが停止され、再開されていない場合はtrueを返します。
使用例
SingularSDK.IsAllTrackingStopped();