Unity SDK - 基本的な統合

ドキュメント

前提条件

Singular Unity SDKをインストールする前に、以下の前提条件を完了してください。

必要な前提条件


インストール

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

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

インストール手順

  1. Package Managerを開きます:Unityで、Window > Package Managerに移動します。
  2. Gitからパッケージを追加します:左上の[+]ボタンをクリックし、"Add package from git URL "を選択します。
  3. Git URLを入力します:
    • Standard SDKの場合: https://github.com/singular-labs/Singular-Unity-SDK.gitと入力します。
    • Kids 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. バイナリを埋め込みます:Inspectorペインで、オプション「Add to Embedded Binaries」をチェックします。

Android設定のヒント

Androidのビルド設定を構成して、適切なSDK機能を確保します。 Unityは、AndroidマニフェストとGradleファイルをカスタマイズする複数の方法を提供します。

AndroidManifest.xml を更新する方法
#

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

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

  1. File > Build Settings > Player Settings > Publishing Settingsに移動します。
  2. Publishing Settingsセクションの下にある"Custom Main Manifest "を有効にします。
  3. UnityはAssets/Plugins/Android/AndroidManifest.xmlにデフォルトのAndroidManifest.xmlファイルを生成します。
  4. このファイルを編集して、必要なパーミッションと設定を追加します。

ソースUnity Androidマニフェスト・ドキュメント

方法2:Android Studio

  1. File > Build Settings > Export Projectを使用してUnityからプロジェクトをエクスポートします。
  2. エクスポートしたプロジェクトをAndroid Studioで開きます。
  3. Android StudioでAndroidManifest.xml ファイルを直接編集します。
Gradleビルドファイルの更新方法
#

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

  1. File > Build Settings > Player Settings > Publishing Settingsに移動します。
  2. Publishing Settingsセクションで"Custom Gradle Template "を有効にします。
  3. UnityはAssets/Plugins/Android/mainTemplate.gradleに mainTemplate.gradle ファイルを生成します。
  4. このファイルにカスタムGradle設定を追加します。

ソースUnity Gradle概要ドキュメント

方法2:Android Studio

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

UnityでAndroidアプリをビルドする際、複数のSDKが同じtransitive dependenciesを含むことで発生する "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.10.0.aar -> jetified-singular_sdk-12.10.0-runtime (com.singular.sdk:singular_sdk:12.10.0)

解決策1:外部依存関係マネージャ(EDM4U)を使用する

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

  1. Unity プロジェクトで*Dependencies.xml ファイルを探します(通常、Assets/Editorまたは同様の場所)。
  2. SDKの依存関係の1つに除外ルールを追加します:
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.10.0" />
  </androidPackages>
</dependencies>

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

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

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

  1. File > Build Settings > Player Settings > Publishing Settingsに移動します。
  2. Custom Main Gradle Template "または"Custom Launcher Gradle Template "を有効にします。
  3. Assets/Plugins/Android/mainTemplate.gradle (またはlauncherTemplate.gradle) を開きます。
  4. 依存関係ブロックに除外ルールを追加します:
Gradle
dependencies {
    implementation('com.applovin:applovin-sdk:13.5.0') {
        exclude group: 'com.android.vending', module: 'licensing'
    }
    implementation 'com.singular.sdk:singular_sdk:12.10.0'
}

代替:依存関係ブロックの後にこれを追加して、グローバル除外を適用します:

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

解決の確認

  1. 除外を適用したら、Library/BeeTempフォルダを削除してプロジェクトをクリーンアップします。
  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の依存関係を更新する
#

iOS用のUnityプロジェクトをビルドした後、Xcodeでビルドする前に、CocoaPodsの依存関係を更新して、最新のSDKバージョンを確保します。

Terminal
cd /path/to/your/ios/project
pod repo update
pod update
テストのためのIDFVログ
#

統合をテストするために、Singular SDK Consoleでテストデバイスを素早く追加するために、IDFV(Identifier for Vendor)をログに記録してください。

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 Consoleでテストデバイスとして追加します。
ディープリンクサポートの設定
#

XcodeプロジェクトでAssociated Domainsを設定して、ディープリンク用のユニバーサルリンクを有効にします。

  1. 関連ドメインを追加します:Xcode で、アプリターゲットのSigning & Capabilitiesタブに移動します。
  2. ケイパビリティを有効にします: クリックし、"Associated Domains "を追加します。
  3. ドメインを追加します:Singularトラッキングドメインを追加します:applinks:yourdomain.sng.link
  4. チームIDの設定:Singularダッシュボードでアプリの設定に移動し、AppleチームIDを追加します。 これにより、Singularはユニバーサルリンクに必要なApple App Site Association(AASA)ファイルを生成し、ホストできるようになります。

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


SDKを統合する

SingularSDK GameObjectの作成

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

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

プレハブをシーンに追加

  1. ProjectペインでPackages > Singular > SingularSDK > Prefabs に移動します。
  2. SingularSDKObjectプレハブを階層ペインにドラッグします。
  3. これでプレハブは Inspector で設定できるようになりました。
方法 2: GameObject を手動で作成する
#

手動でGameObjectを作成する

  1. 階層ペインで右クリックし、Create Empty を選択します。
  2. GameObject にSingularSDKObject という名前を付けます(正確な名前が必要です)。
  3. GameObjectを選択した状態で、Inspectorペインに移動します。
  4. Add Componentをクリックします。
  5. Singular」を検索し、Singular SDKスクリプトコンポーネントを選択します。

重要:SDKを正しく機能させるには、GameObjectの名前を正確にSingularSDKObject

SDK設定の構成

Unity InspectorでSDKの認証情報と初期化設定を行います。APIキーとシークレットはSDKがSingularのサーバーと通信するために必要です。

APIクレデンシャルを追加

  1. SingularSDKObjectを選択します:階層内の SingularSDKObject をクリックします。
  2. クレデンシャルを探します: Singularアカウントにログインし、Developer Tools > SDK Integration > SDK Keysに移動します。
  3. キーをコピーします: SDK Keyと SDK Secretをコピーします。
  4. インスペクタに貼り付けます:UnityのInspectorペインで、Singular API Keyと Singular API Secretフィールドにクレデンシャルをペーストします。

重要です:SDK IntegrationページからSDK固有のAPI KeyとSecretのみを使用してください。間違った認証情報を使用すると、データがSingularに送信されなくなります。

インテグレーションを確認します:設定後、Singular SDK Consoleを使用して実装をテストし、イベントが正しくトラッキングされていることを確認してください。

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

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

デフォルトの設定オプション
#
  • Initialize On Awake:SDKはGameObjectが目覚めたときに自動的に初期化されます。 プライバシーの同意やその他の要件のために初期化を遅らせる必要がある場合は、これを無効にします。
  • SKANを有効にする:ManagedモードでSKAdNetworkのアトリビューションを有効にし、設定したコンバージョンモデルに基づいてSingularが自動的にコンバージョン値を更新します。
  • トラッキング認証を待つ:0(無効)に設定します。アプリがiOS App Tracking Transparency (ATT)プロンプトを表示する場合、これを300秒に設定します。これにより、ユーザーがATTプロンプトに応答するまでSDKセッションが遅延し、同意が得られた場合にIDFAを確実にキャプチャできます。ATTを使用しない場合は0のままにします。
  • ログを有効にします:SDKのデバッグ・ログを出力し、統合やトラブルシューティングに役立てます。 本番ビルドでは無効にする必要があります。Log Level設定(下記参照)と連動します。
  • ログレベル:デフォルトで3(情報)に設定され、ログの冗長性を制御します。数値が低いほど、より冗長なログが出力されます:
    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がフォアグラウンドに戻ったときに新しいセッションを作成する前に、アプリをバックグラウンドにできる時間を定義します。
  • Shortlink Resolve Timeout(ショートリンク解決タイムアウト):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. Inspectorペインで、"Facebook App ID "フィールドを見つけます。
  3. Facebook App IDを入力します(Facebook Developer Consoleで確認できます)。

その他のリソース


SDKを初期化する

プライバシーの遵守Singular SDKを実装する際は、GDPR、CCPA、COPPA、その他を含む、お客様の運用地域のプライバシー法を遵守してください。ガイダンスについては、SDK Opt-In and Opt-Out Practicesをご覧ください。

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

自動初期化

デフォルトでは、SingularSDK.cs スクリプトは、Unity のAwake() メソッドを通じてシーンがロードされると、自動的に SDK を初期化します。Inspector でInitialize On Awakeが有効になっている場合は、追加のコードは必要ありません。

手動での初期化

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

手動初期化のセットアップ

  1. シーン階層でSingularSDKObjectを選択します。
  2. Inspectorペインで、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
    }
}

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


詳細設定

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

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

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

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

  1. シーン階層のSingularSDKObjectを選択します。
  2. Inspector]ペインで、[Session Timeout Sec]フィールドを探します。
  3. 希望するタイムアウト値を秒単位で入力します(例:120で2分)。
  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にアセットを再インポートさせます。
  3. Unityプロジェクトを再度開きます。
  4. Unityがアセットを再インポートし終わるのを待ちます。
  5. コンパイルエラーがないことを確認してから、UPM のインストールを進めます。

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

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