ドキュメント

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

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

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

必要条件

前提条件

アプリのディープリンクを有効にするには、Singular Links Prerequisitesを完了してください。

注意事項

この記事は、Singular Links（Singularのトラッキングリンク技術）を使用していることを前提としています。古いお客様は従来のトラッキングリンクを使用している可能性があります。
アプリのディープリンク先は、Singularのアプリページで設定する必要があります（アトリビューショントラッキングのためのアプリの設定を参照）。

Singularリンクハンドラの実装

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

利用可能なパラメータ

ディープリンク (_dl)：リンクをクリックしたユーザーのアプリ内のリンク先URL
ディファードディープリンク（_ddl）：リンクをクリックした後にアプリをインストールしたユーザーのリンク先URL
パススルー (_p)：追加コンテキストのためにトラッキングリンクを通して渡されるカスタムデータ

プラットフォーム設定

アトリビューショントラッキングとナビゲーションのためにSingular SDKにディープリンクデータを渡すためのネイティブプラットフォームコードを設定します。

Androidの設定

MainActivityの更新

MainActivity ファイルを修正してIntent オブジェクトを Singular SDK に渡すことで、Singular SDK がローンチ関連データを処理し、ディープリンクを処理できるようにします。

import singular_cordova_sdk.SingularCordovaSdk;

@Override
public void onNewIntent(Intent intent) {
    SingularCordovaSdk.handleNewIntent(intent);
}

Intent オブジェクトには、アプリの起動方法と起動理由に関する情報が含まれており、Singular はこれをアトリビューショントラッキングとディープリンクナビゲーションに使用します。

場所通常はplatforms/android/app/src/main/java/[your-package]/MainActivity.javaにあります。

iOSの設定

AppDelegateを更新する

AppDelegate ファイルでlaunchOptions とuserActivity オブジェクトを Singular SDK に渡すことで、Singular SDK が起動関連データを処理し、ディープリンクを処理できるようにします。

import UIKit
import SingularCordovaSdk

class AppDelegate: UIResponder, UIApplicationDelegate {
    
    var window: UIWindow?
    var viewController: MainViewController?
    
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        // Initialize window
        window = UIWindow(frame: UIScreen.main.bounds)
        
        // Configure view controller
        viewController = MainViewController()
        window?.rootViewController = viewController
        
        // Initialize Singular SDK with launch options
        SingularCordovaSdk.setLaunchOptions(launchOptions)
        
        // Make window visible
        window?.makeKeyAndVisible()
        
        return true
    }
    
    func application(
        _ application: UIApplication,
        continue userActivity: NSUserActivity,
        restorationHandler: @escaping ([Any]?) -> Void
    ) -> Bool {
        return SingularCordovaSdk.startSession(with: userActivity)
    }
}

これらのメソッドは、Singular SDKがアプリの起動方法と起動理由に関する重要な情報を受け取れるようにするもので、Singularはアトリビューショントラッキングとディープリンクナビゲーションに使用します。

場所 platforms/ios/[YourAppName]/Classes/AppDelegate.swift、またはObjective-Cプロジェクトの場合はAppDelegate.m 。

SDKの設定

初期化中にwithSingularLink コールバックを実装して、ディープリンクと遅延ディープリンクを処理するようにSingular SDKを設定します。

withSingularLinkコールバックを追加

基本実装

SDKの初期化中に、入力されるディープリンクと遅延ディープリンクデータを処理するために、withSingularLink コールバックを設定します。

// Create configuration
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  'YOUR_SDK_KEY',
  'YOUR_SDK_SECRET'
);

// Define link handler function
var linkHandler = function(data) {
  var deeplink = data.deeplink;
  var passthrough = data.passthrough;
  var isDeferred = data.isDeferred;
  
  console.log('Deep link:', deeplink);
  console.log('Passthrough:', passthrough);
  console.log('Is deferred:', isDeferred);
  
  // Add link handling logic here
  if (deeplink) {
    handleDeepLink(deeplink, isDeferred);
  }
};

// Attach link handler to configuration
singularConfig.withSingularLink(linkHandler);

// Initialize SDK
cordova.plugins.SingularCordovaSdk.init(singularConfig);

注意: withSingularLink コールバックは、アプリがシンギュラーリンクを介して開いた場合にのみトリガーされます。詳細については、Singular Links FAQを参照してください。

高度な実装

ナビゲーションロジック、パススルーデータの解析、本番アプリのエラー処理など、包括的なディープリンク処理を実装します。

document.addEventListener('deviceready', initializeApp, false);

function initializeApp() {
  // Create configuration
  var config = new cordova.plugins.SingularCordovaSdk.SingularConfig(
    'YOUR_SDK_KEY',
    'YOUR_SDK_SECRET'
  );
  
  // Configure deep link handler
  config.withSingularLink(function(params) {
    console.log('=== Singular Link Resolved ===');
    console.log('Full params:', JSON.stringify(params));
    
    var deeplink = params.deeplink;
    var passthrough = params.passthrough;
    var isDeferred = params.isDeferred;
    
    // Log for debugging
    console.log('Deep link:', deeplink || 'null');
    console.log('Passthrough:', passthrough || 'null');
    console.log('Is deferred:', isDeferred);
    
    // Handle passthrough data
    if (passthrough) {
      handlePassthroughData(passthrough);
    }
    
    // Handle deep link navigation
    if (deeplink) {
      handleDeepLinkNavigation(deeplink, isDeferred);
    }
  });
  
  // Initialize SDK
  cordova.plugins.SingularCordovaSdk.init(config);
}

function handlePassthroughData(passthroughString) {
  try {
    var data = JSON.parse(passthroughString);
    
    // Apply promo code if present
    if (data.promo_code) {
      applyPromoCode(data.promo_code);
    }
    
    // Set user segment
    if (data.segment) {
      setUserSegment(data.segment);
    }
    
    // Track campaign
    if (data.campaign_id) {
      trackCampaign(data.campaign_id);
    }
  } catch (error) {
    console.error('Error parsing passthrough:', error);
  }
}

function handleDeepLinkNavigation(url, isDeferred) {
  // Parse URL to extract route and parameters
  var urlObj = parseDeepLink(url);
  
  console.log('Navigating to: ' + urlObj.route);
  console.log('Parameters:', urlObj.params);
  console.log('Deferred install:', isDeferred);
  
  // Route based on deep link structure
  switch (urlObj.route) {
    case 'product':
      navigateToProduct(urlObj.params.id);
      break;
    case 'promo':
      navigateToPromo(urlObj.params.code);
      break;
    case 'category':
      navigateToCategory(urlObj.params.name);
      break;
    default:
      navigateToHome();
  }
}

function parseDeepLink(url) {
  // Parse myapp://product/123?variant=blue
  var parts = url.split('?');
  var path = parts[0];
  var queryString = parts[1];
  
  var pathParts = path.replace(/^[^:]+:\/\//, '').split('/');
  var route = pathParts[0];
  
  // Parse parameters
  var params = {};
  
  // Add path parameters
  if (pathParts.length > 1) {
    params.id = pathParts[1];
  }
  
  // Add query parameters
  if (queryString) {
    queryString.split('&').forEach(function(pair) {
      var keyValue = pair.split('=');
      params[keyValue[0]] = decodeURIComponent(keyValue[1]);
    });
  }
  
  return { route: route, params: params };
}

// Navigation functions
function navigateToProduct(productId) {
  console.log('Navigating to product:', productId);
  // Your navigation logic
}

function navigateToPromo(promoCode) {
  console.log('Navigating to promo:', promoCode);
  // Your navigation logic
}

function navigateToCategory(categoryName) {
  console.log('Navigating to category:', categoryName);
  // Your navigation logic
}

function navigateToHome() {
  console.log('Navigating to home');
  // Your navigation logic
}

// Utility functions
function applyPromoCode(code) {
  console.log('Applying promo code:', code);
}

function setUserSegment(segment) {
  console.log('Setting user segment:', segment);
}

function trackCampaign(campaignId) {
  console.log('Tracking campaign:', campaignId);
}

パラメータの詳細

シンギュラーリンクコールバックで提供されるパラメータを理解することで、堅牢なディープリンクロジックを構築することができます。

パラメータ	タイプ	説明
`deeplink`	文字列	ユーザーがリンクをクリックした際のアプリ内のリンク先URL (例:`myapp://product/123`)
`passthrough`	文字列	トラッキングリンクを通して渡されるカスタムデータ（通常、追加のコンテキストのためにJSONエンコードされる
`isDeferred`	ブール	遅延ディープリンクかどうかを示します（ユーザーはリンクをクリックした後にアプリをインストールします）。

ベストプラクティス

URLを安全に解析する：悪意のあるリダイレクトを防ぐために、ナビゲーションに使用する前に、常にディープリンクのURLを検証し、サニタイズする。
欠落データの処理：ディープリンクのパラメータにアクセスする前に、NULLまたは未定義の値がないかチェックする。
遅延リンクのテスト：新規インストール後の適切なナビゲーションを確保するために、即時および遅延の両方のディープリンクシナリオをテストする。
デバッグのためのログ：開発中に詳細なロギングを有効にして、ディープリンクが正しく受信され、解析されたことを確認します。
コンテキストにパススルーを使用する：パススルーパラメータを活用して、キャンペーン ID、プロモーションコード、またはユーザーセグメントなどの追加コンテキストを送信します。
マーケティングとの調整：マーケティングチームと協力して、アプリのディープリンクURL構造を定義し、文書化する。

メソッドの完全なドキュメントについては、withSingularLinkリファレンスを参照してください。

ハンドラの動作

コールバックトリガーを理解する

withSingularLink コールバックの動作は、アプリがインストールされたばかりか、既にデバイス上に存在しているかによって異なります。

新規インストールのシナリオ

新規インストールでは、アプリの起動時に Open URL はありません。Singular は最後のタッチポイントへのアトリビューションを完了し、トラッキングリンクに設定済みのディープリンクまたはディファードディープリンク (DDL) 値が含まれているかどうかを判断する必要があります。

どのように機能するか

アトリビューションプロセスは、Singular SDKが最初のセッションをSingularサーバーに送信するときに発生します。
該当する場合、ディープリンクの値がSDKのwithSingularLink ハンドラーに返されます。
ディープリンクはdeeplink パラメータに表示され、isDeferred はtrueに設定されます。
サーバーとの通信が必要なため、この処理には数秒かかる場合があります。

すでにインストールされているシナリオ

アプリがすでにインストールされている場合、シングラーリンクをクリックするとすぐにアプリが開きます。オペレーティングシステムは完全なトラッキングリンクURLを提供し、Singular SDKは初期化中にこれを解析してdeeplink とpassthrough の値を抽出します。

仕組み

ハンドラーがトリガーされると、ディープリンクが即座に利用可能になります。
isDeferred パラメータはfalseに設定されます。
サーバーとの通信が不要なため、コールバックの実行が高速になります。

ディープリンクのテスト

以下の手順に従って、開発環境でディファード・ディープリンクの動作をテストしてください。

テスト要件：

テストデバイスからアプリをアンインストールします（現在インストールされている場合）。
広告識別子（iOSの場合はIDFA、Androidの場合はGAID）をリセットします。
デバイスからSingularトラッキングリンクをクリックします。リンクがディープリンク値で設定されていることを確認します。
アプリをインストールして開く
アトリビューションが完了し、DDL値がハンドラーに渡されることを確認します。

開発ビルドのテスト：異なるパッケージ名（例えば、com.example.prod の代わりにcom.example.dev ）を持つアプリの開発バージョンでテストする場合、トラッキングリンクが開発アプリのパッケージ名専用に設定されていることを確認してください。テストリンクをクリックした後、アプリストアからダウンロードするのではなく、開発ビルドをテストデバイスに直接インストールしてください（CLIまたはIDE経由）。

高度な機能

パススルーデータ

トラッキングリンクにパススルー (_p) パラメータが含まれている場合、ハンドラーのpassthrough パラメータに対応するデータが含まれます。キャンペーンメタデータ、ユーザーセグメンテーションデータ、またはアプリで必要なカスタム情報を取得するために使用します。

// Example tracking link with passthrough:
// https://example.sng.link/A?_dl=myapp://product/123&_p={"campaign":"summer","promo":"SAVE20"}

singularConfig.withSingularLink(function(data) {
  var deeplink = data.deeplink;
  var passthrough = data.passthrough;
  
  if (passthrough) {
    // Parse JSON passthrough data
    var passthroughData = JSON.parse(passthrough);
    console.log('Campaign:', passthroughData.campaign);
    console.log('Promo code:', passthroughData.promo);
  }
});

クエリパラメータの転送

トラッキングリンクのURLからすべてのクエリパラメータを取得するには、Singularトラッキングリンクに_forward_params=2 パラメータを追加します。すべてのクエリパラメータはハンドラーのdeeplink パラメータに含まれます。

// Example tracking link with parameter forwarding:
// https://example.sng.link/A?_dl=myapp://product&_forward_params=2&category=electronics&sort=price

singularConfig.withSingularLink(function(data) {
  var deeplink = data.deeplink;
  // deeplink will contain: myapp://product?category=electronics&sort=price
  
  console.log('Deep link with parameters:', deeplink);
  // Parse and use the forwarded parameters
});

重要: withSingularLink コールバックは、Singular リンク経由でアプリが開いた場合にのみトリガーされます。ディープリンクを使用しない通常のアプリの起動では、ハンドラはトリガーされません。

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

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

必要条件

前提条件

Singularリンクハンドラの実装

プラットフォーム設定

Androidの設定

MainActivityの更新

iOSの設定

AppDelegateを更新する

SDKの設定

withSingularLinkコールバックを追加

基本実装

高度な実装

パラメータの詳細

ベストプラクティス

ハンドラの動作

コールバックトリガーを理解する

新規インストールのシナリオ

すでにインストールされているシナリオ

ディープリンクのテスト

高度な機能

パススルーデータ

クエリパラメータの転送