Unity

AdStage DeepLink 統合ガイド（Unity）

概要

AdStage DeepLink SDK for Unity は、次の機能を提供します。

リアルタイムディープリンク：URL Scheme、App Link/Universal Links による即時処理
ディファードディープリンク：アプリのインストール後、初回起動時に自動で復元
動的ディープリンクの作成：サーバー API を通じて、トラッキング可能なリンクを作成
アトリビューションのトラッキング：UTM パラメータに基づくマーケティング分析
クロスプラットフォーム：Android/iOS で同じ API

対応するディープリンクのタイプ

URL Scheme：myapp://promo/summer
Android App Links：https://go.myapp.com/abc123
iOS Universal Links：https://go.myapp.com/abc123
ディファードディープリンク：アプリ未インストール時はストア → インストール → アプリ起動時に復元

プロジェクト設定

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

Package Manager からインストールする場合：

Window → Package Manager → + → Add package from git URL
https://github.com/nbase-io/NBase-SDK-Unity.git?path=/AdStageSDK-Package

または manifest.json を直接編集する場合：

{
  "dependencies": {
    "com.nbase.adstage": "https://github.com/nbase-io/NBase-SDK-Unity.git?path=/AdStageSDK-Package#3.0.0"
  }
}

2. 必須の依存関係

パッケージのインストール時に自動で含まれます。

Newtonsoft.Json：JSON シリアライズ
Native プラグイン：iOS/Android ブリッジ

Unity プロジェクト設定

1. SDK の初期化

using AdStageSDK;
using UnityEngine;
 
public class AdStageInitializer : MonoBehaviour
{
    void Start()
    {
        // AdStage の初期化
        AdStage.Initialize(
            apiKey: "your-api-key-here"
        );
        
        // ディープリンクリスナーの登録
        SetupDeepLinkListener();
        
        Debug.Log("✅ AdStage SDK の初期化が完了しました");
    }
    
    private void SetupDeepLinkListener()
    {
        AdStage.SetDeepLinkListener(
            onDeepLink: (data) => {
                Debug.Log($"✅ ディープリンクを受信: {data.shortPath}");
                if (data.parameters != null && data.parameters.Count > 0)
                {
                    foreach (var param in data.parameters)
                    {
                        Debug.Log($"  - {param.Key}: {param.Value}");
                    }
                }
            },
            onError: (error) => {
                Debug.LogError($"❌ ディープリンクの処理に失敗しました: {error}");
            }
        );
    }
}

Android プラットフォーム設定

1. AndroidManifest.xml の設定

Assets/Plugins/Android/AndroidManifest.xml を作成します。

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myapp">
    
    <application
        android:allowBackup="true"
        android:icon="@drawable/app_icon"
        android:label="@string/app_name">
        
        <activity
            android:name="com.unity3d.player.UnityPlayerActivity"
            android:theme="@style/UnityThemeSelector"
            android:screenOrientation="fullSensor"
            android:launchMode="singleTask"
            android:configChanges="mcc|mnc|locale|touchscreen|keyboard|keyboardHidden|navigation|orientation|screenLayout|uiMode|screenSize|smallestScreenSize|fontScale|layoutDirection|density"
            android:exported="true">
            
            <!-- デフォルトのランチャー -->
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
            
            <!-- URL Scheme ディープリンク -->
            <intent-filter>
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <data android:scheme="your_app_scheme" />
            </intent-filter>
        </activity>
        
    </application>
</manifest>

2. launchMode の重要事項

android:launchMode="singleTask"

✅ singleTask：既存の Activity を再利用（推奨）
⚠️ singleTop：スタックの最上部にあるときだけ再利用
❌ standard：毎回新しいインスタンスを作成（ディープリンクが重複して発生）

iOS プラットフォーム設定

1. Xcode で Info.plist を設定

<!-- URL Scheme の設定 -->
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLName</key>
        <string>com.example.myapp</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>your_ios_scheme</string>
        </array>
    </dict>
</array>

ディープリンクの作成

public async void CreateDetailedDeepLink()
{
    try
    {
         var builder = new DeepLinkBuilder("Unity Test Link")
             .SetDescription("Unity SDK テスト")
             .SetCampaign("unity_test")
             .SetChannel("app_channel")
             .SetRedirectType(RedirectType.APP)
             .SetAndroidConfig("your.package.name","your_aos_scheme", "https://yourdomain.com")
             .SetIOSConfig("your.appstoreid", "your_ios_scheme", "https://yourdomain.com")
             .SetWebConfig("https://yourdomain.com")
             .AddParameter("user_id", "value")
             .AddParameter("test", "true");
        
         AdStage.CreateDeeplink(
             builder: builder,
             onSuccess: (shortUrl) =>
             {
                 InAppLog("✅ ディープリンクの作成に成功しました！");
                 InAppLog($"  URL: {shortUrl}");
             },
             onError: (error) =>
             {
                 InAppLog($"❌ ディープリンクの作成に失敗しました: {error}");
             }
         );
        
    }
    catch (System.Exception e)
    {
        Debug.LogError($"❌ エラー: {e.Message}");
    }
}

RedirectType の説明

public enum RedirectType
{
    STORE,  // ストアに移動
    
    APP,    // アプリ未インストール時 → ストアに移動
            // アプリインストール済みの場合 → アプリを起動（リアルタイムディープリンク）
    
    WEB     // 常にウェブ URL に移動
            // アプリのインストール有無に関係なし
}

Android のディープリンクフロー：

ユーザーがディープリンクをクリック (myapp://abc123)
  ↓
Android System が Intent を作成
  ↓
UnityPlayerActivity の開始／再開
  ↓
AdStageLifecyclePlugin.onActivityCreated/Resumed()
  ↓
AdStageUnityWrapper.handleIntent(intent)
  ↓
AdStage.handleIntent(context, intent)
  ↓
DeeplinkHandler.handleIntent()
  ├─ URI の抽出: myapp://abc123
  ├─ shortPath のパース: abc123
  ├─ API の呼び出し: GET /deeplinks/abc123
  └─ DeeplinkListener.onDeeplinkReceived()
       ↓
UnitySendMessage("AdStageCallbackReceiver", "OnDeepLinkReceived", json)
  ↓
AdStageCallbackReceiver.OnDeepLinkReceived(json)
  ↓
ユーザーのコールバックを呼び出し

iOS のディープリンクフロー：

ユーザーがディープリンクをクリック (myapp://abc123)
  ↓
iOS System が URL を渡す
  ↓
AdStageUnityAppController.application:openURL: または
AdStageUnityAppController.application:continueUserActivity:
  ↓
AdStageUnityBridge.AdStageIOS_HandleDeepLink(url)
  ↓
AdStageManager.shared.handleDeepLink(url)
  ↓
DeepLinkManager.handleDeepLink()
  ├─ URL のパース
  ├─ API の呼び出し
  └─ DeepLinkDelegate.onDeepLinkReceived()
       ↓
UnitySendMessage("AdStageCallbackReceiver", "OnDeepLinkReceived", json)
  ↓
AdStageCallbackReceiver.OnDeepLinkReceived(json)
  ↓
ユーザーのコールバックを呼び出し

トラブルシューティング

1. Unity Editor でディープリンクが動作しない

正常な動作です！ AdStage SDK はモバイルプラットフォーム（Android/iOS）でのみ動作します。 Editor では AdStage.Initialize() を呼び出しても IsInitialized() が false を返し、ディープリンクのコールバックは実機でのみ受信されます。

確認方法：

#if UNITY_EDITOR
Debug.Log("📊 [Editor Mode] ディープリンクは実機でのみ動作します");
#endif

テスト方法： 実際の Android/iOS ビルドをデバイスにインストールしてから、以下のトラブルシューティングにある Intent / URL Scheme のテスト（2 番、3 番）で、ディープリンクの受信を確認してください。

2. Android のビルド後にディープリンクを受信できない

チェックリスト：

AndroidManifest.xml を確認
- android:launchMode="singleTask" の設定を確認
- Intent Filter が正しいかを確認
adb logcat を確認

adb logcat | grep -i adstage

Intent のテスト

# URL Scheme のテスト
adb shell am start -W -a android.intent.action.VIEW -d "myapp://promo/summer" com.example.myapp
 
# HTTPS App Link のテスト
adb shell am start -W -a android.intent.action.VIEW -d "https://go.myapp.com/abc123" com.example.myapp

3. iOS のビルド後にディープリンクを受信できない

チェックリスト：

Info.plist を確認
- CFBundleURLTypes の設定
- Associated Domains の設定
Universal Links の検証

# Apple App Site Association ファイルを確認
curl https://go.myapp.com/.well-known/apple-app-site-association

Xcode Console を確認
- エラーメッセージを確認
- ディープリンク受信のログを確認

4. ディファードディープリンクが復元されない

Android:

# Install Referrer を確認
adb shell dumpsys package com.example.myapp | grep -i referrer

解決方法：

AndroidManifest.xml に権限を追加します。

<uses-permission android:name="com.google.android.finsky.permission.BIND_GET_INSTALL_REFERRER_SERVICE" />

Play Console で Install Referrer を設定

5. ディープリンクが重複して呼び出される

原因： launchMode="standard" を使用している

解決：

<!-- AndroidManifest.xml -->
android:launchMode="singleTask"

6. Unity 2021+ IL2CPP のビルドエラー

問題：

TypeLoadException: Could not load type 'AdStageSDK.DeepLinkData'

解決： link.xml ファイルを作成します

Assets/link.xml:

<linker>
    <assembly fullname="AdStageSDK" preserve="all"/>
    <assembly fullname="AdStageSDK.Models" preserve="all"/>
    <assembly fullname="Newtonsoft.Json" preserve="all"/>
</linker>

7. JSON シリアライズのエラー

問題：

JsonSerializationException: Error converting value

解決：

// Parameters には Dictionary<string, object> を使用
var parameters = new Dictionary<string, object>
{
    { "key1", "value1" },
    { "key2", 123 },  // int も使用可能
    { "key3", true }  // bool も使用可能
};

8. Android App Links の検証に失敗する

確認方法：

# Digital Asset Links の検証
curl https://go.myapp.com/.well-known/assetlinks.json

チェックリスト：

✅ HTTPS を使用している
✅ Content-Type：application/json
✅ SHA256 フィンガープリントが正確か確認
✅ パッケージ名が一致している

FAQ

Q: Unity Editor でディープリンクをテストできますか？
A: いいえ。SDK はモバイルプラットフォームでのみ動作するため、ディープリンクのテストは実際の Android/iOS 端末で行う必要があります。

Q: Android と iOS で同じディープリンク URL を使えますか？
A: はい。URL Scheme と HTTPS リンクのどちらも同じように使えます。

Q: ディファードディープリンクはどのように動作しますか？
A: アプリのインストール → 初回起動 → Install Referrer の照会 → 保存されたディープリンクの復元 → コールバックの呼び出し

Q: ディープリンクのパラメータ数に上限はありますか？
A: サーバー側の上限はありませんが、URL の長さの上限（約 2000 文字）を考慮してください。

Q: オフラインでもディープリンクは動作しますか？
A: リアルタイムディープリンクにはネットワークが必要です。ディファードディープリンクはキャッシュされるため、オフラインでも復元されます。

Q: Unity WebGL でも動作しますか？
A: WebGL ではネイティブプラグインを使用できないため、対応していません。ウェブ環境では URL パラメータを直接パースしてください。

サポート

お問い合わせ先：

メール：support@nbase.io

Unity

AdStage DeepLink 統合ガイド（Unity）

目次

概要

対応するディープリンクのタイプ

プロジェクト設定

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

2. 必須の依存関係

Unity プロジェクト設定

1. SDK の初期化

Android プラットフォーム設定

1. AndroidManifest.xml の設定

2. launchMode の重要事項

iOS プラットフォーム設定

1. Xcode で Info.plist を設定

ディープリンクの作成

RedirectType の説明

トラブルシューティング

1. Unity Editor でディープリンクが動作しない

2. Android のビルド後にディープリンクを受信できない

3. iOS のビルド後にディープリンクを受信できない

4. ディファードディープリンクが復元されない

5. ディープリンクが重複して呼び出される

6. Unity 2021+ IL2CPP のビルドエラー

7. JSON シリアライズのエラー

8. Android App Links の検証に失敗する

FAQ

サポート

目次