前提条件
統合プロセスを円滑に進めるため、Singular Unity SDK をインストールする前に、以下の前提条件の手順を完了してください。
必須の前提条件:
- 計画手順の完了:「Singular SDKの統合:計画と前提条件」のガイドに従ってください。これらの手順は、Singular SDKを統合する際に必須です。
- 依存関係マネージャーの確認:プロジェクトでGoogle EDM4U(Unity 用外部依存関係マネージャー)を使用しているか確認してください。Google EDM4U の詳細はこちら。
-
.unitypackageからのアップグレードをお考えですか?従来の
.unitypackageから新しいUPMパッケージへ移行する場合は、続行する前にアップグレード手順をお読みください。
インストール
Unity Package Manager (UPM) 経由でのインストール
Singular Unity SDKは、Unity Package Manager(UPM)を通じて Git URLを使用してインストールされます。以下の手順に従って、プロジェクトにSDKを追加してください。
インストール手順
- パッケージマネージャーを開く:Unityで、 [Window] > [Package Manager] を選択します。
- Git からパッケージを追加:左上の[+] ボタンをクリックし、 「Git URL からパッケージを追加」を選択します。
-
Git URLの入力:
-
Standard SDKの場合:
https://github.com/singular-labs/Singular-Unity-SDK.git -
キッズ SDK の場合:入力
https://github.com/singular-labs/Singular-Unity-SDK.git#kids
-
Standard SDKの場合:
- インストールを完了する: 「追加」をクリックして SDK パッケージをインストールします。
Google EDM4Uを使用していない場合:プロジェクトで 外部依存関係マネージャーを 使用していない場合は、ネイティブ 依存関係を 手動でダウンロードして追加する必要があります。
依存関係の手動インストール
-
依存関係のダウンロード:SingularのS3バケットから適切な
Plugins.zipファイルをダウンロードしてください:-
標準 SDK (v5.7.0):
Standard SDK プラグインのダウンロード -
Kids SDK (v5.6.0):
Kids SDKプラグインのダウンロード
-
標準 SDK (v5.7.0):
- アセットに抽出:ダウンロードしたファイルを抽出 し、Unity プロジェクト内の Assets > Pluginsに移動します。
-
iOSフレームワークの設定:
Assets > Plugins > iOSに移動し、
Singular.xcframeworkを選択します。 - バイナリの埋め込み:インスペクター パネルで、 「Add to Embedded Binaries」 オプションにチェックを入れます。
Androidの設定に関するヒント
SDKが正しく機能するように、Androidのビルド設定を構成してください。 Unityでは、AndroidのマニフェストやGradle ファイルをカスタマイズする複数の方法が用意されています。
AndroidManifestは、次の2つの方法のいずれかを使用して変更できます:
方法 1: Unity カスタムマニフェスト
- [ファイル] > [ビルド設定] > [プレイヤー設定] > [パブリッシング設定] に移動します。
- 「パブリッシング設定」セクション内の 「カスタムメインマニフェスト」を有効にします。
-
Unityは、
Assets/Plugins/Android/AndroidManifest.xml
にデフォルトの
AndroidManifest.xmlファイルを生成します。 - このファイルを編集して、必要な権限や設定を追加してください。
出典:Unity Android マニフェスト ドキュメント
方法 2: Android Studio
- Unityからプロジェクトをエクスポートします。 [ファイル] > [ビルド設定] > [プロジェクトのエクスポート] を選択します。
- エクスポートしたプロジェクトを Android Studio で開きます。
-
AndroidManifest.xmlファイルを Android Studio内で 直接編集します。
方法 1: Unity カスタムテンプレート
- [ファイル] > [ビルド設定] > [プレイヤー設定] > [パブリッシング設定] に移動します。
- 「パブリッシング設定」セクション内の 「カスタム Gradle テンプレート」を有効にします。
-
Unityは、
Assets/Plugins/Android/mainTemplate.gradle
に
mainTemplate.gradleファイルを生成します。 - このファイルにカスタム Gradle 設定を追加します。
方法 2: Android Studio
- Unityからプロジェクトをエクスポートします。
- Android Studioでプロジェクトを開きます。
-
アプリの
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 ファイルに除外ルールを追加してください。
-
Unityプロジェクト内の
*Dependencies.xmlファイルを探します (通常はAssets/Editorまたは同様の場所にあります)。 - SDK依存関係のいずれかに除外ルールを追加します:
<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設定ファイルに 直接除外ルールを適用してください。
- [ファイル] > [ビルド設定] > [Player設定] > [パブリッシング設定] に移動します。
- 「カスタムメインGradleテンプレート」 または「カスタムランチャーGradleテンプレート」を有効にします。
-
Assets/Plugins/Android/mainTemplate.gradle(またはlauncherTemplate.gradle)を開きます。 - dependencies ブロックに除外ルールを追加します:
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'
}
別の方法:依存関係ブロックの後に以下を追加して、 グローバルな除外を適用します:
configurations.all {
exclude group: 'com.android.vending', module: 'licensing'
}
解決の確認
- 除外を適用した後、 Library/Beeおよび Temp フォルダを削除してプロジェクトをクリーンアップします。
- UnityでAndroidプロジェクトを再ビルドします。
- ビルド出力に重複クラスエラーが 表示されなくなったことを確認します。
動作原理:両方の SDKは、 同じ Android ライセンスライブラリを推移的依存関係としてバンドルしています。 この除外設定により、Gradle は 1 つのコピーのみを使用するよう指示され、 競合が解決されます。
プロジェクトでコード難読化にProGuardを使用している場合は、
Singular SDKが削除されないように、
proguard-unity.txt ファイルに以下の
keepルールを追加してください:
-keep class com.singular.sdk.** { *; }
-keep public class com.android.installreferrer.** { *; }
-keep public class com.singular.unitybridge.** { *; }
iOS設定のヒント
適切なアトリビューション、ディープリンク、 およびテスト機能を有効にするために、iOS固有の設定を構成してください。
UnityプロジェクトをiOS向けにビルドした後、Xcodeでビルドする前に、 CocoaPodsの依存関係を更新し、 最新のSDKバージョンが 利用可能であることを確認してください。
cd /path/to/your/ios/project
pod repo update
pod update
統合のテストを行うには、IDFV(Identifier for Vendor)をログに記録し、 Singular SDKコンソールにテストデバイスを 素早く追加できるようにします。
IDFVのログ記録を追加する
- Unityからビルドした後、Xcodeプロジェクトを開きます。
- 「Classes」>「UnityAppController.mm」に移動します。
-
applicationDidBecomeActiveメソッドを探します。 - IDFVをログ出力するために、以下のコードを追加します:
// Log IDFV for testing
NSLog(@"Singular === IDFV: %@", [[[UIDevice currentDevice] identifierForVendor] UUIDString]);
- Xcodeでアプリをビルドして実行します。
- XcodeのコンソールログでIDFVの出力を確認します。
- IDFVをコピーし、Singular SDKコンソールにテストデバイスとして追加します。 Singular SDK Console.
Xcodeプロジェクトで関連ドメインを設定し、ディープリンク用にユニバーサルリンクを有効にします。
ディープリンクの設定手順
- 関連ドメインの追加:Xcodeで、 アプリターゲットの「署名と機能」 タブに移動します。
- 機能の有効化: [+] Capabilityをクリックし、 「Associated Domains」を追加します。
-
ドメインの追加:Singularのトラッキング
ドメインを
applinks:yourdomain.sng.linkの形式で追加します - チーム ID の設定:Singular ダッシュボードで、 アプリの設定に移動し、Apple チーム ID を入力します。 これにより、Singular はユニバーサルリンクに必要な Apple App Site Association (AASA) ファイルを生成・ホストできるようになります。
重要:関連ドメインとチームIDが適切に設定されていない場合、 ユニバーサルリンクは機能せず、 ユーザーはSingularのトラッキングリンクから アプリを開くことができません。
UnityAppControllerを登録する他のSDK (Firebase、Adjust、AppsFlyerなど)を使用している場合、 Singularが正常に初期化できない競合が発生する可能性があります。 Unityでは、一度に1つのクラスしかUnityAppControllerとして 登録できません。
この競合を解決するには:
-
Xcodeプロジェクト内の
SingularSwizzledAppController.mファイルを開きます。 - このファイル内のすべてのコードのコメント解除を行います。
-
SingularAppDelegate.mを開き、 以下の行がコメントアウトされていないことを確認してください:IMPL_APP_CONTROLLER_SUBCLASS(SingularAppDelegate)
これにより、UnityAppControllerをサブクラス化せずに メソッドスウィズリングを使用することで、Singularを他のSDKと併用できるようになります。
SDKの統合
SingularSDK GameObjectを作成する
Singular SDKが機能するには、Unityシーンの階層内にGameObjectが必要です。 このGameObjectは、提供されているプレハブを使用するか、手動で作成して 追加できます。
シーンにプレハブを追加する
- プロジェクトペインで、 Packages > Singular > SingularSDK > Prefabs へ移動します。
- SingularSDKObjectプレハブを [Hierarchy] ペインにドラッグします。
- これで、インスペクターでプレハブの設定ができるようになりました。
GameObjectの手動作成
- Hierarchyペインで右クリックし、 「Create Empty」を 選択します。
-
GameObjectの名前を「
SingularSDKObject」とします(正確な 名前が必要です)。 - GameObject を選択した状態で、 インスペクターペインに移動します。
- 「コンポーネントの追加」をクリックします。
- 「Singular」を検索し、 Singular SDKスクリプトコンポーネントを選択します。
重要:SDKが正しく機能するためには、GameObjectの名前を
正確に
SingularSDKObject とする必要があります。
。
SDK設定の構成
Unityの インスペクター を通じて、SDKの認証情報と初期化設定を構成します。SDKがSingularのサーバーと通信するには、APIキーとシークレットが必要です。
API 認証情報の追加
- SingularSDKObjectの選択:ヒエラルキー内のSingularSDKObjectを クリックします。
- 認証情報の確認: Singularアカウントにログインし、 [Developer Tools] > [SDK Integration] > [SDK Keys] に移動します。
- キーのコピー: SDK Keyと SDK Secretをコピーします。
- インスペクターに貼り付け: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)に設定されています。
ログの詳細度を制御します。数値が小さいほど、より詳細な
ログが出力されます:
// 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秒)。ショートリンクの 解決を待機する最大時間。 ショートリンクが解決できない場合に 長時間の待機を防ぐことで、 ユーザーエクスペリエンスを保護します。
その他の設定オプション
2025年6月18日現在:Metaの Advanced Mobile Measurement (AMM) により、Meta Install Referrerの実装は不要になりました。 AMMレポートが有効になっている場合、Meta Install Referrerを 設定する必要はありません。
従来のMeta Install Referrerアトリビューション メソッドをサポートする必要がある場合は、SingularSDKObject 設定にFacebookアプリIDを追加してください。
設定手順
- シーンの 階層 からSingularSDKObjectを選択します。
- インスペクターペインで、 「Facebook App ID」 フィールドを探します。
- 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を初期化する必要がある場合は、自動初期化を無効にし、 初期化メソッドを手動で呼び出してください。
手動初期化の設定
- シーンの階層でSingularSDKObjectを選択します。
- インスペクターペインで、「Initialize On Awake」のチェックを外します。
-
初期化の準備が整ったら、コード内で
SingularSDK.InitializeSingularSDK()を呼び出してください。
InitializeSingularSDK メソッド
自動初期化が無効になっている場合、このメソッドを使用して SDK を手動で初期化します。 。
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の初期実装時にこの設定を完了させてください。
セッションタイムアウトの設定
アプリがバックグラウンド状態にある間、アプリがフォアグラウンドに戻った際に SDK が新しいセッションを作成するまでの時間をカスタマイズします。
セッションタイムアウトの設定
デフォルトのセッションタイムアウトは60秒です。この値を変更するには:
- シーン階層でSingularSDKObjectを選択します。
- インスペクタペインで、「Session Timeout Sec」フィールドを探します。
- 希望するタイムアウト値を秒単位で入力します(例:2分の場合は120)。
- デフォルトの60秒タイムアウトを使用する場合は、0のままにします。
ベストプラクティス:セッションタイムアウトを設定する際は、アプリの一般的な使用パターンを考慮してください。短いセッションが頻繁に行われるゲームではタイムアウトを短くすると効果的ですが、生産性アプリではより長いタイムアウトが必要になる場合があります。
.unitypackage から UPM へのアップグレード
従来の.unitypackage インストール
方法から最新のUnity Package Manager (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. クリーン状態の確認
- ファイルを削除した後、Unityを完全に終了してください。
- プロジェクトディレクトリ内のLibraryフォルダを削除し、 Unity にアセットの再インポートを強制します。 Unity プロジェクトを再度開きます。
- Unityプロジェクトを再度開きます。
- Unityによるアセットの再インポートが完了するまで待ちます。
- UPMのインストールを進める前に、 コンパイルエラーがないことを確認してください。
5. UPMパッケージのインストール
これで、Unity Package Manager 経由で Singular SDK をインストールする準備が整いました。 このガイドの上部に記載されている UPM のインストール手順に従ってください。