Unity SDK - 基本的な統合

ドキュメント

前提条件

統合プロセスを円滑に進めるため、Singular Unity SDK をインストールする前に、以下の前提条件の手順を完了してください。

必須の前提条件:


インストール

Unity Package Manager (UPM) 経由でのインストール

Singular Unity SDKは、Unity Package Manager(UPM)を通じて Git URLを使用してインストールされます。以下の手順に従って、プロジェクトにSDKを追加してください。

インストール手順

  1. パッケージマネージャーを開く:Unityで、 [Window] > [Package Manager] を選択します。
  2. Git からパッケージを追加:左上の[+] ボタンをクリックし、 「Git URL からパッケージを追加」を選択します。
  3. Git URLの入力:
    • Standard SDKの場合: https://github.com/singular-labs/Singular-Unity-SDK.git
    • キッズ SDK の場合:入力 https://github.com/singular-labs/Singular-Unity-SDK.git#kids
  4. インストールを完了する: 「追加」をクリックして SDK パッケージをインストールします。

Google EDM4Uを使用していない場合:プロジェクトで 外部依存関係マネージャーを 使用していない場合は、ネイティブ 依存関係を 手動でダウンロードして追加する必要があります。

依存関係の手動インストール

  1. 依存関係のダウンロード:SingularのS3バケットから適切な Plugins.zip ファイルをダウンロードしてください:
  2. アセットに抽出:ダウンロードしたファイルを抽出 し、Unity プロジェクト内の Assets > Pluginsに移動します。
  3. iOSフレームワークの設定: Assets > Plugins > iOSに移動し、 Singular.xcframework を選択します。
  4. バイナリの埋め込み:インスペクター パネルで、 「Add to Embedded Binaries」 オプションにチェックを入れます。

Androidの設定に関するヒント

SDKが正しく機能するように、Androidのビルド設定を構成してください。 Unityでは、AndroidのマニフェストやGradle ファイルをカスタマイズする複数の方法が用意されています。

AndroidManifest.xml の更新方法
#

AndroidManifestは、次の2つの方法のいずれかを使用して変更できます:

方法 1: Unity カスタムマニフェスト

  1. [ファイル] > [ビルド設定] > [プレイヤー設定] > [パブリッシング設定] に移動します。
  2. パブリッシング設定セクション内の 「カスタムメインマニフェスト」を有効にします。
  3. Unityは、 Assets/Plugins/Android/AndroidManifest.xml にデフォルトのAndroidManifest.xmlファイルを生成します。
  4. このファイルを編集して、必要な権限や設定を追加してください。

出典:Unity Android マニフェスト ドキュメント

方法 2: Android Studio

  1. Unityからプロジェクトをエクスポートします。 [ファイル] > [ビルド設定] > [プロジェクトのエクスポート] を選択します。
  2. エクスポートしたプロジェクトを Android Studio で開きます。
  3. AndroidManifest.xml ファイルを Android Studio内で 直接編集します。
Gradle ビルドファイルの更新方法
#

方法 1: Unity カスタムテンプレート

  1. [ファイル] > [ビルド設定] > [プレイヤー設定] > [パブリッシング設定] に移動します。
  2. パブリッシング設定セクション内の 「カスタム Gradle テンプレート」を有効にします。
  3. Unityは、 Assets/Plugins/Android/mainTemplate.gradlemainTemplate.gradle ファイルを生成します。
  4. このファイルにカスタム Gradle 設定を追加します。

出典:Unity Gradle 概要ドキュメント

方法 2: Android Studio

  1. Unityからプロジェクトをエクスポートします。
  2. Android Studioでプロジェクトを開きます。
  3. アプリのbuild.gradle ファイルを直接編集します。
重複クラスエラーの解決
#

UnityでAndroidアプリをビルドする際、複数のSDKが同じ 推移的依存関係を含んでいることが原因で、「Duplicate class」エラーが発生することがあります。これは、AppLovin SDKと Singular SDKの両方を使用している場合に、Android Vending Licensingライブラリでよく発生します。

エラー例:

Duplicate class com.android.vending.licensing.ILicensingService found in modules 
applovin-sdk-13.5.0.aar -> jetified-applovin-sdk-13.5.0-runtime (com.applovin:applovin-sdk:13.5.0) 
and singular_sdk-12.11.0.aar -> jetified-singular_sdk-12.11.0-runtime (com.singular.sdk:singular_sdk:12.11.0)

解決策 1: External Dependency Manager (EDM4U) の使用

プロジェクトで External Dependency Manager for Unity(推奨)を使用している場合は、 Dependencies XML ファイルに除外ルールを追加してください。

  1. Unityプロジェクト内の*Dependencies.xml ファイルを探します (通常はAssets/Editor または同様の場所にあります)。
  2. SDK依存関係のいずれかに除外ルールを追加します:
XML
<dependencies>
  <androidPackages>
    <androidPackage spec="com.applovin:applovin-sdk:13.5.0">
      <androidSdkPackageIds>
        <exclude group="com.android.vending" module="licensing"/>
      </androidSdkPackageIds>
    </androidPackage>
    <androidPackage spec="com.singular.sdk:singular_sdk:12.11.0" />
  </androidPackages>
</dependencies>

注:この方法は、Gradleテンプレートを修正するよりも永続的です。 Android Resolverは解決処理中にカスタムテンプレートの変更を上書きする可能性があるためです。

解決策 2: カスタム Gradle テンプレートの使用

EDM4Uを使用していない場合は、Gradle設定ファイルに 直接除外ルールを適用してください。

  1. [ファイル] > [ビルド設定] > [Player設定] > [パブリッシング設定] に移動します。
  2. 「カスタムメインGradleテンプレート」 または「カスタムランチャーGradleテンプレート」を有効にします。
  3. Assets/Plugins/Android/mainTemplate.gradle (またはlauncherTemplate.gradle )を開きます。
  4. dependencies ブロックに除外ルールを追加します:
Gradle
dependencies {
    implementation('com.applovin:applovin-sdk:13.5.0') {
        exclude group: 'com.android.vending', module: 'licensing'
    }
    implementation 'com.singular.sdk:singular_sdk:12.11.0'
}

別の方法:依存関係ブロックの後に以下を追加して、 グローバルな除外を適用します:

Gradle
configurations.all {
    exclude group: 'com.android.vending', module: 'licensing'
}

解決の確認

  1. 除外を適用した後、 Library/Beeおよび Temp フォルダを削除してプロジェクトをクリーンアップします。
  2. UnityでAndroidプロジェクトを再ビルドします。
  3. ビルド出力に重複クラスエラーが 表示されなくなったことを確認します。

動作原理:両方の SDKは、 同じ Android ライセンスライブラリを推移的依存関係としてバンドルしています この除外設定により、Gradle は 1 つのコピーのみを使用するよう指示され、 競合が解決されます。

ProGuardの設定
#

プロジェクトでコード難読化にProGuardを使用している場合は、 Singular SDKが削除されないように、 proguard-unity.txt ファイルに以下の keepルールを追加してください:

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

iOS設定のヒント

適切なアトリビューション、ディープリンク、 およびテスト機能を有効にするために、iOS固有の設定を構成してください。

CocoaPodsの依存関係を更新する
#

UnityプロジェクトをiOS向けにビルドした後、Xcodeでビルドする前に、 CocoaPodsの依存関係を更新し、 最新のSDKバージョンが 利用可能であることを確認してください。

Terminal
cd /path/to/your/ios/project
pod repo update
pod update
テスト用のIDFVのログ出力
#

統合のテストを行うには、IDFV(Identifier for Vendor)をログに記録し、 Singular SDKコンソールにテストデバイスを 素早く追加できるようにします。

IDFVのログ記録を追加する

  1. Unityからビルドした後、Xcodeプロジェクトを開きます。
  2. Classes」>「UnityAppController.mm」に移動します。
  3. applicationDidBecomeActive メソッドを探します。
  4. IDFVをログ出力するために、以下のコードを追加します:
Objective-C
// Log IDFV for testing
NSLog(@"Singular === IDFV: %@", [[[UIDevice currentDevice] identifierForVendor] UUIDString]);
  1. Xcodeでアプリをビルドして実行します。
  2. XcodeのコンソールログでIDFVの出力を確認します。
  3. IDFVをコピーし、Singular SDKコンソールにテストデバイスとして追加します。 Singular SDK Console.
ディープリンクのサポートを設定する
#

Xcodeプロジェクトで関連ドメインを設定し、ディープリンク用にユニバーサルリンクを有効にします。

  1. 関連ドメインの追加:Xcodeで、 アプリターゲットの「署名と機能」 タブに移動します。
  2. 機能の有効化: [+] Capabilityをクリックし、 「Associated Domains」を追加します。
  3. ドメインの追加:Singularのトラッキング ドメインを applinks:yourdomain.sng.link の形式で追加します
  4. チーム ID の設定:Singular ダッシュボードで、 アプリの設定に移動し、Apple チーム ID を入力します。 これにより、Singular はユニバーサルリンクに必要な Apple App Site Association (AASA) ファイルを生成・ホストできるようになります。

重要:関連ドメインとチームIDが適切に設定されていない場合、 ユニバーサルリンクは機能せず、 ユーザーはSingularのトラッキングリンクから アプリを開くことができません。

⚠️ 重要:UnityAppController の競合の解決
#

UnityAppControllerを登録する他のSDK (Firebase、Adjust、AppsFlyerなど)を使用している場合、 Singularが正常に初期化できない競合が発生する可能性があります。 Unityでは、一度に1つのクラスしかUnityAppControllerとして 登録できません。

この競合を解決するには:

  1. Xcodeプロジェクト内の SingularSwizzledAppController.m ファイルを開きます
  2. このファイル内のすべてのコードのコメント解除を行います。
  3. SingularAppDelegate.mを開き、 以下の行がコメントアウトされていないことを確認してください:
    IMPL_APP_CONTROLLER_SUBCLASS(SingularAppDelegate)

これにより、UnityAppControllerをサブクラス化せずに メソッドスウィズリングを使用することで、Singularを他のSDKと併用できるようになります。


SDKの統合

SingularSDK GameObjectを作成する

Singular SDKが機能するには、Unityシーンの階層内にGameObjectが必要です。 このGameObjectは、提供されているプレハブを使用するか、手動で作成して 追加できます。

方法 1: Singular プレハブを使用する(推奨)
#

シーンにプレハブを追加する

  1. プロジェクトペインで、 Packages > Singular > SingularSDK > Prefabs へ移動します。
  2. SingularSDKObjectプレハブを [Hierarchy] ペインにドラッグします。
  3. これで、インスペクターでプレハブの設定ができるようになりました。
方法 2: GameObject を手動で作成する
#

GameObjectの手動作成

  1. Hierarchyペインで右クリックし、 「Create Empty」を 選択します。
  2. GameObjectの名前を「SingularSDKObject 」とします(正確な 名前が必要です)。
  3. GameObject を選択した状態で、 インスペクターペインに移動します。
  4. コンポーネントの追加」をクリックします。
  5. 「Singular」を検索し、 Singular SDKスクリプトコンポーネントを選択します。

重要:SDKが正しく機能するためには、GameObjectの名前を 正確に SingularSDKObject とする必要があります。 。

SDK設定の構成

Unityの インスペクター を通じて、SDKの認証情報と初期化設定を構成します。SDKがSingularのサーバーと通信するには、APIキーとシークレットが必要です。

API 認証情報の追加

  1. SingularSDKObjectの選択:ヒエラルキー内のSingularSDKObjectを クリックします。
  2. 認証情報の確認: Singularアカウントにログインし、 [Developer Tools] > [SDK Integration] > [SDK Keys] に移動します。
  3. キーのコピー: SDK Key SDK Secretをコピーします。
  4. インスペクターに貼り付け:Unityのインスペクターペインで、 認証情報を「Singular API Key」および 「Singular API Secret」フィールドに貼り付けます。

重要:Singular Reporting API Keyは絶対に使用しないでください。 SDK Integration ページにある、SDK専用のAPI KeyとSecretのみを使用してください。誤った認証情報を使用すると、データが Singularに 送信されなくなります。

統合の確認:設定後、 Singular SDKコンソール を使用して実装をテストし、 イベントが正しく追跡されていることを確認してください。

インスペクタのデフォルト設定

SingularSDKObjectには、適切なデフォルト設定が用意されています。これらの 設定 を理解することで、アプリの要件に合わせてSDKの動作をカスタマイズできます。

デフォルトの設定オプション
#
  • Awake時に初期化:デフォルトで有効。 GameObjectが Awake状態になると、SDKが自動的に初期化されます。 プライバシー 同意やその他の要件により初期化を遅延させる必要がある場合は、 これを無効にしてください。
  • SKAN有効:デフォルトで有効(iOS のみ)。 マネージドモードでSKAdNetworkアトリビューションを有効にします。このモードでは、 Singular が設定された コンバージョンモデルに基づいてコンバージョン値を自動的に更新します。
  • トラッキングの承認を待機: 0(無効)に設定します。アプリで iOS App Tracking Transparency (ATT)のプロンプトが表示される場合は、これを 300 秒に設定してください。これにより、 SDK セッションがユーザーが ATT プロンプトに応答するまで遅延され、同意が得られた場合に IDFA を確実に 取得できるようになります。ATT を使用しない場合は、 0 のままに してください。
  • ログ記録を有効にする:デフォルトで有効。 統合やトラブルシューティングを支援するために、 SDKのデバッグログを出力します。 本番環境のビルドでは無効にする必要があります。 「ログレベル」設定(下記参照)と連動します。
  • ログレベル:デフォルトは 3(Info)に設定されています。 ログの詳細度を制御します。数値が小さいほど、より詳細な ログが出力されます:
    C#
    // Based on Android Logger log levels
    public enum LogLevel {
       Verbose = 2,  // Most verbose
       Debug   = 3,
       Info    = 4,  // Default
       Warn    = 5,
       Error   = 6,
       Assert  = 7   // Least verbose
    }

    注:詳細なログは主に Android で利用可能です。

  • DDLタイムアウト(秒):0に設定(60秒の デフォルト値を使用)。サーバーからの遅延 ディープリンクデータをSDKが待機する時間を決定します。遅延ディープリンクが見つからない場合、サーバーはこのタイムアウト後に検索を 停止します。
  • セッションタイムアウト(秒):0に設定( 60秒の デフォルトを使用)。アプリがバックグラウンド状態になってから、 フォアグラウンドに戻った際に SDKが新しいセッションを作成するまでの時間を定義します。
  • ショートリンク解決タイムアウト:0に設定 (デフォルトは 10秒)。ショートリンクの 解決を待機する最大時間。 ショートリンクが解決できない場合に 長時間の待機を防ぐことで、 ユーザーエクスペリエンスを保護します。

その他の設定オプション

Facebook (Meta) インストールリファラー設定
#

2025年6月18日現在:Metaの Advanced Mobile Measurement (AMM) により、Meta Install Referrerの実装は不要になりました AMMレポートが有効になっている場合、Meta Install Referrerを 設定する必要はありません。

従来のMeta Install Referrerアトリビューション メソッドをサポートする必要がある場合は、SingularSDKObject 設定にFacebookアプリIDを追加してください。

設定手順

  1. シーンの 階層 からSingularSDKObjectを選択します。
  2. インスペクターペインで、 「Facebook App ID」 フィールドを探します。
  3. Facebook App IDを入力します(Facebook Developer Consoleで確認できます)。

追加リソース:


SDKの初期化

プライバシーコンプライアンス:Singular SDKを実装する際は、GDPR、CCPA、COPPAなど、 事業展開地域のプライバシー関連法規を遵守してください。詳細については、 「SDKのオプトインおよびオプトアウトに関するガイドライン」を参照してください。

アプリが起動するたびにSingular SDKを初期化してください。SDKの初期化は Singularのアトリビューション機能すべてに不可欠であり、ユーザーリテンション指標を 算出するための新しいセッションを作成します。

自動初期化

デフォルトでは、UnityのAwake() メソッドを通じてシーンが読み込まれる際、 SingularSDK.cs スクリプトが自動的にSDKを初期化します。 インスペクターで「Initialize On Awake」が有効になっている場合、 追加のコードは不要です。

手動初期化

特定のタイミング(例:ユーザーの同意取得後など)で SDKを初期化する必要がある場合は、自動初期化を無効にし、 初期化メソッドを手動で呼び出してください。

手動初期化の設定

  1. シーンの階層でSingularSDKObjectを選択します。
  2. インスペクターペインで、「Initialize On Awake」のチェックを外します。
  3. 初期化の準備が整ったら、コード内で SingularSDK.InitializeSingularSDK() を呼び出してください。

InitializeSingularSDK メソッド

自動初期化が無効になっている場合、このメソッドを使用して SDK を手動で初期化します。 。

C#
using UnityEngine;
using Singular;

public class GameInitializer : MonoBehaviour
{
    void Start()
    {
        // Perform any required setup (e.g., consent management)
        CheckUserConsent();

        // Initialize Singular SDK after consent is obtained
        // SDK Key and Secret are configured on the SingularSDKObject
        SingularSDK.InitializeSingularSDK();
    }

    void CheckUserConsent()
    {
        // Your consent logic here
    }
}

スレッドセーフ:Singular Unity SDK のメソッドは、 他の Unity API 呼び出しに使用しているのと同じスレッドから常に呼び出してください。この SDK は、 複数のスレッド間でスレッドセーフではありません。


詳細設定

Google Ads iOS 統合コンバージョン測定に必要な設定

アプリで iOS 14.5 以降のユーザーを対象とした Google Ads キャンペーンを実行する場合、iOS 統合コンバージョン測定 (ICM) をサポートするために、追加の SDK 設定手順が必要です。これには以下が含まれます:

  • GoogleのOn-Device Measurement (ODM) SDKの統合
  • Singular iOS SDK v12.8.1 以降への更新(Unity 版は v5.5.0 以降、Flutter/Cordova 版は v1.8.0 以降、React Native 版は v3.9.0 以降)
  • SingularConfig-ObjC リンカーフラグを追加し、enableOdmWithTimeoutInterval を有効にする

注: enableOdmWithTimeoutInterval を有効にすると、SDKの初期化が遅延し、ディープリンクのコールバックが延期される可能性があります。後からの修正作業を避けるため、SDKの初期実装時にこの設定を完了させてください。

iOS ICMの技術要件の詳細を参照


セッションタイムアウトの設定

アプリがバックグラウンド状態にある間、アプリがフォアグラウンドに戻った際に SDK が新しいセッションを作成するまでの時間をカスタマイズします。

セッションタイムアウトの設定

デフォルトのセッションタイムアウトは60秒です。この値を変更するには:

  1. シーン階層でSingularSDKObjectを選択します。
  2. インスペクタペインで、「Session Timeout Sec」フィールドを探します。
  3. 希望するタイムアウト値を秒単位で入力します(例:2分の場合は120)。
  4. デフォルトの60秒タイムアウトを使用する場合は、0のままにします。

ベストプラクティス:セッションタイムアウトを設定する際は、アプリの一般的な使用パターンを考慮してください。短いセッションが頻繁に行われるゲームではタイムアウトを短くすると効果的ですが、生産性アプリではより長いタイムアウトが必要になる場合があります。


.unitypackage から UPM へのアップグレード

従来の.unitypackage インストール 方法から最新のUnity Package Manager (UPM) への移行を行う場合は、以下の 重要なアップグレード手順に従ってください。

移行手順:.unitypackage から UPM へ
#

重要:UPMパッケージをインストールする前に、 既存のSingular SDKファイルをすべて手動で削除する必要があります。 これを怠ると、競合やビルドエラーが発生します。

アップグレード手順

Unity Package Manager経由でSDKをインストールする前に、 以下の手順を順に実行してください:

ファイル削除の手順
#

1. コードファイルの削除

プロジェクトの /Code フォルダ(通常はAssets/Singular/Code ) に移動し、Singularに関連するすべてのC#スクリプトを削除します。

2. Android依存関係の削除

/Plugins/Android フォルダに移動し、以下のSingularファイルを削除します:

  • 名前に「singular」が含まれるすべての .aar ファイル
  • 名前に「singular」が含まれるすべての .jar ファイル
  • singular-sdk.aar
  • install-referrer-*.aar
  • singular-unitybridge.aar

3. iOSの依存関係を削除する

/Plugins/iOSへ移動し、 以下の Singular ファイルを削除してください:

  • すべての.h ヘッダーファイル(例: SingularSDK.h
  • すべての.m 実装ファイル (例:SingularUnityBridge.m
  • Singular.xcframework フォルダ

重要:Singular固有のファイルのみを削除してください。 プロジェクトが依存している可能性のある他のプラグイン ファイルを削除しないよう注意してください。

4. クリーン状態の確認

  1. ファイルを削除した後、Unityを完全に終了してください。
  2. プロジェクトディレクトリ内のLibraryフォルダを削除し、 Unity にアセットの再インポートを強制します。 Unity プロジェクトを再度開きます。
  3. Unityプロジェクトを再度開きます。
  4. Unityによるアセットの再インポートが完了するまで待ちます。
  5. UPMのインストールを進める前に、 コンパイルエラーがないことを確認してください。

5. UPMパッケージのインストール

これで、Unity Package Manager 経由で Singular SDK をインストールする準備が整いました。 このガイドの上部に記載されている UPM のインストール手順に従ってください。