Unreal Engine SDK - ディープリンクのサポート

ドキュメント

ディープリンクサポートの追加

ディープリンクは、ユーザーをアプリ内の特定のコンテンツに誘導します。アプリがインストールされたデバイスでユーザーがディープリンクをタップすると、アプリは製品ページや特定の体験など、目的のコンテンツに直接開きます。

Singularトラッキングリンクは、標準ディープリンク(インストール済みアプリ用)とディファードディープリンク(新規インストール用)の両方をサポートしています。包括的な情報については、ディープリンクFAQと シンギュラーリンクFAQをご覧ください。


必要条件

前提条件

iOSとAndroidプラットフォームでディープリンクを有効にするには、Singular Links Prerequisitesを完了してください。

注意事項

  • このガイドでは、お客様の組織がSingular Links(2019年に発表されたSingularのトラッキングリンク技術)を使用していることを前提としています。古いお客様はレガシーなトラッキングリンクを使用している可能性があります。
  • アプリのディープリンク先は、Singularのアプリページで設定する必要があります(ディープリンクURLの設定を参照)。

SDKの設定

Singularリンクハンドラの実装

Singular SDKは、アプリが開いたときにSingularトラッキングリンクからディープリンク、ディファードディープリンク、パススルーパラメータを取得するためのデリゲートベースのハンドラメカニズムを提供します。

利用可能なパラメータ

  • ディープリンク:リンクをクリックしたユーザーのアプリ内のリンク先URL(リンクの管理ページで設定)。
  • パススルー:追加コンテキストまたはキャンペーンメタデータのためにトラッキングリンクを介して渡されるカスタムデータ。
  • IsDeferred:リンクが遅延ディープリンクかどうかを示します(新規インストールの場合はtrue、既存インストールの場合はfalse)。

アプリにディープリンクハンドラーを追加する

アプリの起動時に入力されるディープリンクデータを処理するために、ディープリンクハンドラを設定します。これは、Singular SDKを初期化する前に行う必要があります。

実装ステップ

  1. 必要なSingular includeをクラスヘッダーファイルに追加します。
  2. OnSingularLinksResolvedコールバックを処理するメソッドを実装します。
  3. SDKを初期化する前にUSingularDelegatesオブジェクトを作成し、登録します。
  4. OnSingularLinksResolved.AddDynamic() を使用してハンドラメソッドを登録します。
  5. ハンドラメソッド内でディープリンクパラメータを処理します。
C++
// Add to the include section of your class header
#include "SingularLinkParams.h"
#include "SingularDelegates.h"

// In your class header, declare the handler method
UFUNCTION()
void OnSingularLinksResolved(const FSingularLinkParams& LinkParams);

// In your class implementation file, implement the handler method
void UYourGameInstance::OnSingularLinksResolved(const FSingularLinkParams& LinkParams)
{
    // Extract parameters from the tracking link
    const FString Deeplink = LinkParams.SingularLinksParams["deeplink"];
    const FString Passthrough = LinkParams.SingularLinksParams["passthrough"];
    const bool IsDeferred = LinkParams.SingularLinksParams["isDeferred"] == "true";

    // Log the parameters
    UE_LOG(LogTemp, Log, TEXT("Deep Link Resolved"));
    UE_LOG(LogTemp, Log, TEXT("Deeplink: %s"), *Deeplink);
    UE_LOG(LogTemp, Log, TEXT("Passthrough: %s"), *Passthrough);
    UE_LOG(LogTemp, Log, TEXT("Is Deferred: %s"), IsDeferred ? TEXT("true") : TEXT("false"));

    // Handle deep link routing
    if (!Deeplink.IsEmpty())
    {
        HandleDeepLinkNavigation(Deeplink, IsDeferred);
    }
}

void UYourGameInstance::HandleDeepLinkNavigation(const FString& Url, bool IsDeferred)
{
    // Your deep link routing logic
    UE_LOG(LogTemp, Log, TEXT("Routing to: %s (Deferred: %s)"), 
           *Url, IsDeferred ? TEXT("true") : TEXT("false"));

    // Example: Parse the URL and navigate to appropriate content
    if (Url.Contains(TEXT("product")))
    {
        NavigateToProduct(Url);
    }
    else if (Url.Contains(TEXT("promo")))
    {
        NavigateToPromotion(Url);
    }
    else
    {
        NavigateToHome();
    }
}

// Register the delegate BEFORE initializing the Singular SDK
void UYourGameInstance::InitializeSingular()
{
    // Create the delegates object
    USingularDelegates* SingularDelegates = 
        CreateDefaultSubobject<USingularDelegates>(TEXT("SingularLinksHandler"));

    // Register the deep link handler
    SingularDelegates->OnSingularLinksResolved.AddDynamic(
        this, 
        &UYourGameInstance::OnSingularLinksResolved
    );

    UE_LOG(LogTemp, Log, TEXT("Singular Link Handler registered"));

    // Now initialize the SDK
    bool Success = USingularSDKBPLibrary::Initialize(
        TEXT("YOUR_SDK_KEY"),
        TEXT("YOUR_SDK_SECRET"),
        60,    // Session timeout
        TEXT(""),    // Custom user ID
        true,  // Enable SKAdNetwork
        false, // Manual SKAN management
        0,     // Wait for tracking authorization
        false, // OAID collection
        true,  // Enable logging
        3,     // Log level
        false, // Clipboard attribution
        TEXT(""),    // Facebook App ID
        TEXT("")     // Custom SDID
    );

    if (Success)
    {
        UE_LOG(LogTemp, Log, TEXT("Singular SDK initialized successfully"));
    }
}

重要:デリゲートはUSingularSDKBPLibrary::Initialize() を呼び出す前に登録する必要があります。初期化後にハンドラを登録すると、ディープリンクコールバックを受け取ることができません。


ハンドラの動作

ディープリンク解決の理解

ディープリンクハンドラの動作は、ユーザがシンギュラーリンクをタップしたときにアプリがインストールされたばかりか、すでにインストールされているかによって異なります。

新規インストール (ディープリンクの遅延)

新規インストールでは、アプリの起動時に Open URL は存在しません。Singularはアトリビューションを完了し、トラッキングリンクにディープリンクの値が含まれているかどうかを判断します。

ディファードディープリンクフロー

  1. ユーザーがディープリンク値で設定されたSingularトラッキングリンクをクリックします。
  2. ユーザーがアプリをインストールし、初めて開きます。
  3. Singular SDKが最初のセッションをSingularサーバーに送信します。
  4. アトリビューションが完了し、トラッキングリンクからディープリンクが特定されます。
  5. ディープリンクの値がIsDeferred = true でハンドラに返されます。

ディファード・ディープリンクのテスト

  1. テストデバイスからアプリをアンインストールします(現在インストールされている場合)。
  2. iOS:IDFA をリセットします。Android: Google Advertising ID (GAID) をリセットします。
  3. デバイスからSingularトラッキングリンクをクリックします(ディープリンク値が設定されていることを確認します)。
  4. アプリをインストールして開きます。

アトリビューションが正常に完了し、遅延されたディープリンク値がハンドラーに渡されます。

開発テストのヒント異なるパッケージ名またはバンドルIDを使用して開発ビルドでディープリンクをテストする場合、開発アプリの識別子専用にトラッキングリンクを設定してください。テストリンクをクリックした後、アプリストアから本番アプリをダウンロードするのではなく、Unreal Engine またはプラットフォーム固有のツールを使用して、開発ビルドをデバイスに直接インストールしてください。


インストール済み (即時ディープリンク)

アプリが既にインストールされている場合、ユニバーサルリンク (iOS) または Android App Links テクノロジーを使用して、シングラーリンクをクリックするとアプリが即座に開きます。

即時ディープリンクフロー

  1. ユーザーはSingularトラッキングリンクをクリックします。
  2. オペレーティングシステムはSingularトラッキングリンク全体を含むOpen URLを提供します。
  3. SDKの初期化中に、SingularはURLを解析します。
  4. Singularはdeeplinkpassthroughの値を抽出します。
  5. 値はハンドラーを通してIsDeferred = false で返されます。

パススルーパラメータ

キャンペーンメタデータ、ユーザーセグメンテーション、またはカスタム情報のためのパススルーパラメータを使用して、トラッキングリンククリックから追加データを取得します。

passthrough (_p) パラメータがトラッキングリンクに含まれている場合、ハンドラーのPassthrough パラメータには対応するデータが含まれます。

C++
void UYourGameInstance::OnSingularLinksResolved(const FSingularLinkParams& LinkParams)
{
    // Extract passthrough data
    const FString PassthroughData = LinkParams.SingularLinksParams["passthrough"];

    if (!PassthroughData.IsEmpty())
    {
        // Parse JSON passthrough data
        TSharedPtr<FJsonObject> JsonObject;
        TSharedRef<TJsonReader<>> Reader = TJsonReaderFactory<>::Create(PassthroughData);

        if (FJsonSerializer::Deserialize(Reader, JsonObject) && JsonObject.IsValid())
        {
            // Extract campaign metadata
            FString CampaignId;
            if (JsonObject->TryGetStringField(TEXT("campaign_id"), CampaignId))
            {
                UE_LOG(LogTemp, Log, TEXT("Campaign ID: %s"), *CampaignId);
            }

            FString UserSegment;
            if (JsonObject->TryGetStringField(TEXT("segment"), UserSegment))
            {
                UE_LOG(LogTemp, Log, TEXT("User Segment: %s"), *UserSegment);
            }

            FString PromoCode;
            if (JsonObject->TryGetStringField(TEXT("promo_code"), PromoCode))
            {
                UE_LOG(LogTemp, Log, TEXT("Promo Code: %s"), *PromoCode);
                ApplyPromoCode(PromoCode);
            }

            // Use the data in your app
            ApplyCampaignSettings(CampaignId, UserSegment);
        }
        else
        {
            UE_LOG(LogTemp, Warning, TEXT("Failed to parse passthrough data"));
        }
    }
}

void UYourGameInstance::ApplyCampaignSettings(const FString& CampaignId, const FString& Segment)
{
    // Your campaign-specific logic
    UE_LOG(LogTemp, Log, TEXT("Applying campaign settings for: %s (Segment: %s)"), 
           *CampaignId, *Segment);
}

パススルーのURL例
https://yourapp.sng.link/A1b2c/abc123?_dl=myapp://product/123&_p={"campaign_id":"summer2025","segment":"premium","promo_code":"SAVE20"}

ハンドラーは、キャンペーンのメタデータを含む JSON 文字列を含むpassthrough パラメータを受け取ります。


FSingularLinkParams リファレンス

パラメータ詳細

FSingularLinkParams オブジェクトには、ディープリンクハンドラーに渡されるトラッキングリンクの詳細が含まれます。

パラメータ タイプ 説明
deeplink FString Singularのリンク管理ページで設定されたディープリンク先のURL。この値はユーザーを特定のアプリ内コンテンツに誘導します。
passthrough FString トラッキングリンクに追加されるパススルーパラメータ。通常、キャンペーンメタデータ、ユーザーセグメンテーション、またはアプリが処理する必要のあるカスタムデータに使用されます。
isDeferred bool リンクが遅延ディープリンクとして設定されているかどうかを示します。新規インストール (遅延) の場合はtrue を、既存インストール (即時) の場合はfalse を返します。

メソッドのシグネチャ

C++
// Callback method signature for Singular Links
void OnSingularLinksResolved(const FSingularLinkParams& linkParams)

// Access parameters using the SingularLinksParams map:
const FString Deeplink = linkParams.SingularLinksParams["deeplink"];
const FString Passthrough = linkParams.SingularLinksParams["passthrough"];
const bool IsDeferred = linkParams.SingularLinksParams["isDeferred"] == "true";

ディープ・リンク・ルーティングの実装

ディープ・リンク・ルータの構築

ディープリンクの URL 構造に基づいてユーザーを特定のコンテンツにナビゲートする、集中型のディープリンク・ルーティング・システムを実装します。

C++
// Deep Link Router class implementation
class UDeepLinkRouter : public UObject
{
public:
    void RouteDeepLink(const FString& DeepLinkUrl, bool IsDeferred)
    {
        UE_LOG(LogTemp, Log, TEXT("Routing deep link: %s (Deferred: %s)"), 
               *DeepLinkUrl, IsDeferred ? TEXT("true") : TEXT("false"));

        // Parse the URL scheme
        if (DeepLinkUrl.StartsWith(TEXT("myapp://product/")))
        {
            FString ProductId = ExtractParameter(DeepLinkUrl, TEXT("myapp://product/"));
            NavigateToProduct(ProductId);
        }
        else if (DeepLinkUrl.StartsWith(TEXT("myapp://category/")))
        {
            FString CategoryName = ExtractParameter(DeepLinkUrl, TEXT("myapp://category/"));
            NavigateToCategory(CategoryName);
        }
        else if (DeepLinkUrl.StartsWith(TEXT("myapp://promo")))
        {
            NavigateToPromotions();
        }
        else if (DeepLinkUrl.StartsWith(TEXT("myapp://profile")))
        {
            NavigateToUserProfile();
        }
        else
        {
            // Default fallback
            UE_LOG(LogTemp, Warning, TEXT("Unknown deep link format, navigating to home"));
            NavigateToHome();
        }

        // Track deep link usage
        TrackDeepLinkEvent(DeepLinkUrl, IsDeferred);
    }

private:
    FString ExtractParameter(const FString& Url, const FString& Prefix)
    {
        FString Param;
        if (Url.Split(Prefix, nullptr, &Param))
        {
            // Remove query parameters if present
            FString CleanParam;
            if (Param.Split(TEXT("?"), &CleanParam, nullptr))
            {
                return CleanParam;
            }
            return Param;
        }
        return FString();
    }

    void NavigateToProduct(const FString& ProductId)
    {
        UE_LOG(LogTemp, Log, TEXT("Navigating to product: %s"), *ProductId);
        // Your product screen navigation logic
    }

    void NavigateToCategory(const FString& CategoryName)
    {
        UE_LOG(LogTemp, Log, TEXT("Navigating to category: %s"), *CategoryName);
        // Your category screen navigation logic
    }

    void NavigateToPromotions()
    {
        UE_LOG(LogTemp, Log, TEXT("Navigating to promotions"));
        // Your promotions screen navigation logic
    }

    void NavigateToUserProfile()
    {
        UE_LOG(LogTemp, Log, TEXT("Navigating to user profile"));
        // Your profile screen navigation logic
    }

    void NavigateToHome()
    {
        UE_LOG(LogTemp, Log, TEXT("Navigating to home screen"));
        // Your home screen navigation logic
    }

    void TrackDeepLinkEvent(const FString& DeepLink, bool IsDeferred)
    {
        // Track deep link usage with Singular
        TMap<FString, FString> EventAttributes;
        EventAttributes.Add(TEXT("deep_link_url"), DeepLink);
        EventAttributes.Add(TEXT("is_deferred"), IsDeferred ? TEXT("true") : TEXT("false"));

        USingularSDKBPLibrary::EventWithAttributes(
            TEXT("deep_link_opened"), 
            EventAttributes
        );
    }
};

ベストプラクティスディープリンクキャンペーンの効果を測定し、どのコンテンツが最もエンゲージメントを高めるかを理解するために、Singularでカスタムイベントとしてディープリンクの開封を追跡します。


重要な考慮事項

実装に関する注意事項

  • 登録のタイミング:ディープリンクハンドラーは、Singular SDKを初期化する前に必ず登録してください。SDKがトラッキングリンクを処理する前にハンドラを配置する必要があります。
  • スレッドの安全性:ハンドラーのコールバックはバックグラウンドスレッドで実行される可能性があります。UI の更新やナビゲーション ロジックは、Unreal Engine のスレッドセーフ メカニズムを使用してゲーム スレッドにディスパッチされるようにしてください。
  • URL スキーム:ルーティング ロジックとメンテナンスを簡素化するために、ディープ リンク用の一貫した URL スキーム (myapp://product/myapp://category/ など) を設計してください。
  • フォールバック処理:アプリのクラッシュやユーザーエクスペリエンスの低下を防ぐため、認識されなかったり、不正な形式のディープリンクに対しては、常にフォールバックナビゲーション(通常はホーム画面へのナビゲーション)を実装しましょう。
  • 両方のフローをテストする:即時ディープリンク(インストール済みアプリ)と遅延ディープリンク(新規インストール)の両方をテストし、すべてのシナリオで適切な処理が行われるようにします。
  • パラメータの検証:悪意のあるURLや不正なURLによるセキュリティ問題やクラッシュを防ぐため、ディープリンクから抽出されたすべてのパラメータを使用前に検証します。
  • プラットフォーム設定:Singular Links Prerequisitesガイドに記載されているように、プラットフォーム固有の設定(iOSユニバーサルリンク、Androidアプリリンク)を完了します。

本番用チェックリスト:(1) SDKの初期化前にハンドラーが登録されていること、(2) プラットフォーム固有の設定が完了していること、(3) Singularダッシュボードでディープリンクが設定されていること、(4) ルーティングロジックが期待されるURLパターンをすべて処理していること、(5) 即時フローと遅延フローの両方が正常にテストされていること。


その他のリソース