前提条件
Singular Unity SDKをインストールする前に、以下の前提条件を完了してください。
必要な前提条件
- 計画ステップを完了します: Singular SDKの統合のガイドに従ってください:プランニングと前提条件』のガイドに従ってください。これらのステップはSingular SDKの統合には必須です。
- 依存関係マネージャーを確認します:プロジェクトがGoogle EDM4U(ExternalDependency Manager for Unity)を使用しているか確認してください。Google EDM4Uについて詳しくはこちらをご覧ください。
-
.unitypackageからアップグレードしますか?レガシーの
.unitypackageから新しいUPMパッケージに移行する場合は、アップグレード手順を読んでから進めてください。
インストール
Unity Package Manager (UPM) 経由でのインストール
Singular Unity SDKはGit URLを使用してUnity Package Managerからインストールします。以下の手順に従って、SDKをプロジェクトに追加してください。
インストール手順
- Package Managerを開きます:Unityで、Window > Package Managerに移動します。
- Gitからパッケージを追加します:左上の[+]ボタンをクリックし、"Add package from git URL "を選択します。
-
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と入力してください。
-
Standard SDKの場合:
- インストールを完了します: 追加」をクリックしてSDKパッケージをインストールしてください。
Google EDM4Uを使用していない場合あなたのプロジェクトが外部依存関係マネージャを使用していない場合、手動でネイティブ依存関係をダウンロードして追加する必要があります。
手動による依存関係のインストール
-
依存関係をダウンロードします:SingularのS3バケットから適切な
Plugins.zipファイルをダウンロードしてください:-
Standard SDK (v5.6.0)をダウンロードしてください:
標準SDKプラグインのダウンロード -
Kids SDK(v5.6.0):
Kids SDKプラグインのダウンロード
-
Standard SDK (v5.6.0)をダウンロードしてください:
- アセットに展開します:ダウンロードしたファイルを解凍し、UnityプロジェクトのAssets > Pluginsに移動します。
-
iOSフレームワークを設定します: Assets > Plugins > iOSに移動し、
Singular.xcframeworkを選択します。 - バイナリを埋め込みます:Inspectorペインで、オプション「Add to Embedded Binaries」をチェックします。
Android設定のヒント
Androidのビルド設定を構成して、適切なSDK機能を確保します。 Unityは、AndroidマニフェストとGradleファイルをカスタマイズする複数の方法を提供します。
AndroidManifest を変更するには、次の 2 つの方法のいずれかを使用します:
方法1:Unityカスタムマニフェスト
- File > Build Settings > Player Settings > Publishing Settingsに移動します。
- Publishing Settingsセクションの下にある"Custom Main Manifest "を有効にします。
-
UnityはAssets/Plugins/Android/AndroidManifest.xmlにデフォルトの
AndroidManifest.xmlファイルを生成します。 - このファイルを編集して、必要なパーミッションと設定を追加します。
方法2:Android Studio
- File > Build Settings > Export Projectを使用してUnityからプロジェクトをエクスポートします。
- エクスポートしたプロジェクトをAndroid Studioで開きます。
-
Android Studioで
AndroidManifest.xmlファイルを直接編集します。
方法1:Unityカスタムテンプレート
- File > Build Settings > Player Settings > Publishing Settingsに移動します。
- Publishing Settingsセクションで"Custom Gradle Template "を有効にします。
-
UnityはAssets/Plugins/Android/mainTemplate.gradleに
mainTemplate.gradleファイルを生成します。 - このファイルにカスタムGradle設定を追加します。
方法2:Android Studio
- Unityからプロジェクトをエクスポートします。
- Android Studioでプロジェクトを開きます。
-
アプリの
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ファイルに除外ルールを追加します。
-
Unity プロジェクトで
*Dependencies.xmlファイルを探します(通常、Assets/Editorまたは同様の場所)。 - SDKの依存関係の1つに除外ルールを追加します:
<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の設定ファイルに直接除外ルールを適用します。
- File > Build Settings > Player Settings > Publishing Settingsに移動します。
- Custom Main Gradle Template "または"Custom Launcher Gradle Template "を有効にします。
-
Assets/Plugins/Android/mainTemplate.gradle(またはlauncherTemplate.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'
}
代替:依存関係ブロックの後にこれを追加して、グローバル除外を適用します:
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固有の設定を行います。
iOS用のUnityプロジェクトをビルドした後、Xcodeでビルドする前に、CocoaPodsの依存関係を更新して、最新のSDKバージョンを確保します。
cd /path/to/your/ios/project
pod repo update
pod update
統合をテストするために、Singular SDK Consoleでテストデバイスを素早く追加するために、IDFV(Identifier for Vendor)をログに記録してください。
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 Consoleでテストデバイスとして追加します。
XcodeプロジェクトでAssociated Domainsを設定して、ディープリンク用のユニバーサルリンクを有効にします。
ディープリンクの設定ステップ
- 関連ドメインを追加します:Xcode で、アプリターゲットのSigning & Capabilitiesタブに移動します。
- ケイパビリティを有効にします: をクリックし、"Associated Domains "を追加します。
-
ドメインを追加します:Singularトラッキングドメインを追加します:
applinks:yourdomain.sng.link - チームIDの設定:Singularダッシュボードでアプリの設定に移動し、AppleチームIDを追加します。 これにより、Singularはユニバーサルリンクに必要なApple App Site Association(AASA)ファイルを生成し、ホストできるようになります。
重要:関連ドメインとチームIDが適切に設定されていないと、Universal Linksは機能せず、ユーザーはSingularのトラッキングリンクからアプリを開くことができません。
SDKを統合する
SingularSDK GameObjectの作成
Singular SDKを機能させるには、Unityのシーン階層にGameObjectが必要です。 このGameObjectは、提供されているプレハブを使用するか、手動で作成することで追加できます。
プレハブをシーンに追加
- ProjectペインでPackages > Singular > SingularSDK > Prefabs に移動します。
- SingularSDKObjectプレハブを階層ペインにドラッグします。
- これでプレハブは Inspector で設定できるようになりました。
手動でGameObjectを作成する
- 階層ペインで右クリックし、Create Empty を選択します。
-
GameObject に
SingularSDKObjectという名前を付けます(正確な名前が必要です)。 - GameObjectを選択した状態で、Inspectorペインに移動します。
- Add Componentをクリックします。
- Singular」を検索し、Singular SDKスクリプトコンポーネントを選択します。
重要:SDKを正しく機能させるには、GameObjectの名前を正確にSingularSDKObject 。
SDK設定の構成
Unity InspectorでSDKの認証情報と初期化設定を行います。APIキーとシークレットはSDKがSingularのサーバーと通信するために必要です。
APIクレデンシャルを追加
- SingularSDKObjectを選択します:階層内の SingularSDKObject をクリックします。
- クレデンシャルを探します: Singularアカウントにログインし、Developer Tools > SDK Integration > SDK Keysに移動します。
- キーをコピーします: SDK Keyと SDK Secretをコピーします。
- インスペクタに貼り付けます: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(情報)に設定され、ログの冗長性を制御します。数値が低いほど、より冗長なログが出力されます:
// 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秒)。ショートリンクを解決できない場合に長い待ち時間が発生しないようにすることで、ユーザーエクスペリエンスを保護します。
その他の設定オプション
2025年6月18日現在MetaのAdvanced Mobile Measurement(AMM)により、Meta Install Referrerを実装する必要がなくなりました。 AMMレポートが有効になっている場合は、Meta Install Referrerを設定する必要はありません。
従来のMeta Install Referrerアトリビューションメソッドをサポートする必要がある場合は、SingularSDKObject設定にFacebookアプリIDを追加してください。
設定の手順
- シーン階層でSingularSDKObjectを選択します。
- Inspectorペインで、"Facebook App ID "フィールドを見つけます。
- 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を初期化する必要がある場合は、自動初期化を無効にし、初期化メソッドを手動で呼び出します。
手動初期化のセットアップ
- シーン階層でSingularSDKObjectを選択します。
- Inspectorペインで、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
}
}
スレッドの安全性:他のUnity API呼び出しに使用するスレッドと同じスレッドから、常にSingular Unity SDKメソッドを呼び出してください。SDKは複数のスレッド間でスレッドセーフではありません。
詳細設定
セッションタイムアウトの設定
アプリがフォアグラウンドに戻ったときにSDKが新しいセッションを作成する前に、アプリがバックグラウンドにとどまることができる時間をカスタマイズします。
セッションタイムアウト設定
デフォルトのセッションタイムアウトは60秒です。この値を変更するには
- シーン階層のSingularSDKObjectを選択します。
- Inspector]ペインで、[Session Timeout Sec]フィールドを探します。
- 希望するタイムアウト値を秒単位で入力します(例:120で2分)。
- デフォルトの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がアセットを再インポートし終わるのを待ちます。
- コンパイルエラーがないことを確認してから、UPM のインストールを進めます。
5.UPM パッケージのインストール
これで、Unity Package Manager経由でSingular SDKをインストールする準備ができました。このガイドの一番上にあるUPMのインストール手順に従ってください。