Cordova SDK - SKAdNetworkのサポート

フォローする
Avatar
Jared Ornstead
Updated
ドキュメント

SKAdNetworkのサポート

SKAdNetworkは、iOSアプリインストールキャンペーンのためのAppleのプライバシー重視のアトリビューションフレームワークです。Singular Cordova SDKはデフォルトのマネージドモードでSKAdNetworkを有効にし、ダッシュボードで設定されたコンバージョンモデルに基づいてSingularが自動的にコンバージョン値を更新します。

追加の設定は必要ありません：最新の Cordova SDK を使用している場合、SKAdNetwork はすぐに動作します。基本的な機能のためにコードの変更や追加の設定は必要ありません。

SKANモードについて

マネージドモード（デフォルト）

マネージドモードでは、ダッシュボードで設定したコンバージョンモデルに基づいて、Singularが自動的にコンバージョン値の更新を処理します。これは最小限のコードで最適なコンバージョントラッキングを提供するため、ほとんどのアプリに推奨されるアプローチです。

  • 自動更新：Singularはユーザーイベントと設定されたモデルに基づいてすべてのコンバージョン値の更新を管理します。
  • ダッシュボードの設定：コードを変更することなく、Singularダッシュボードでコンバージョンモデルをデザインします。
  • 最適化：Appleの制約の中でコンバージョン値の更新を最大化するSingularの専門知識をご利用ください。
  • 24時間ウィンドウ管理：SingularはSKAdNetworkの24時間更新ウィンドウをインテリジェントに処理し、データ収集を最大化します。

マニュアルモード（上級者向け）

マニュアルモードでは、変換値の更新を完全にコントロールすることができ、SKANの変換値をいつ、どのように更新するかを決定するカスタムロジックを実装することができます。このモードは、マネージドモードでは対応できない特定の要件がある場合にのみ使用します。

高度な機能です：マニュアルモードでは、変換値の更新ウィンドウや制限など、AppleのSKAdNetworkの制約を理解し、慎重に実装する必要があります。ほとんどのアプリはマネージドモードを使用してください。

SKAdNetworkサポートを無効にする

SKAdNetwork トラッキングはデフォルトで有効になっています。無効にするには、SingularConfigオブジェクトをビルドする際に、skAdNetworkEnabled コンフィギュレーションプロパティをfalseに設定してください。

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

// Disable SKAdNetwork
singularConfig.withSkAdNetworkEnabled(false);

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

マニュアルモードの設定

カスタム変換値ロジックを実装するには、Manual Modeを有効にし、提供されるSDKメソッドを使用して、アプリのライフサイクル全体を通して変換値を更新および監視します。

マニュアルモードを有効にする

SingularConfigオブジェクトをビルドする際に、manualSkanConversionManagement コンフィギュレーションプロパティをtrueに設定し、変換値の更新を制御できるようにします。

JavaScript 
// Create configuration with manual SKAN mode
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  "YOUR_SDK_KEY",
  "YOUR_SDK_SECRET"
);

// Enable manual SKAN conversion management
singularConfig.withManualSkanConversionManagement();

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

重要：手動更新メソッドは、manualSkanConversionManagement が有効な場合にのみ機能します。マネージドモードが有効な場合、手動更新は無視されます。

変換値の更新（SKAN 2.0-3.0）

skanUpdateConversionValue メソッドを使用して、カスタムロジックに基づいてSKAdNetworkの変換値を手動で更新します。変換値は0～63の整数でなければなりません。

JavaScript 
// Check if running on iOS
if (device.platform === 'iOS') {
  // User completed signup - update conversion value to 7
  function onUserSignUp() {
    // Track the sign-up event
    cordova.plugins.SingularCordovaSdk.event('SignUp');

    // Update SKAN conversion value
    cordova.plugins.SingularCordovaSdk.skanUpdateConversionValue(7, function(success) {
      if (success) {
        console.log('Conversion value updated successfully');
      } else {
        console.warn('Failed to update conversion value');
      }
    });
  }

  // User completed purchase - update based on purchase amount
  function onPurchaseComplete(purchaseAmount) {
    // Track revenue event
    cordova.plugins.SingularCordovaSdk.revenue('USD', purchaseAmount);

    // Calculate conversion value based on purchase tier
    var conversionValue = calculateConversionValue(purchaseAmount);
    cordova.plugins.SingularCordovaSdk.skanUpdateConversionValue(conversionValue, function(success) {
      if (success) {
        console.log('Conversion value updated to: ' + conversionValue);
      }
    });
  }

  function calculateConversionValue(amount) {
    // Your custom logic to determine conversion value
    if (amount >= 100) return 63;  // High value
    if (amount >= 50) return 40;   // Medium value
    if (amount >= 10) return 20;   // Low value
    return 10;                      // Minimal value
  }
}

変換値の更新（SKAN 4.0）

iOS 16.1+では、skanUpdateConversionValues メソッドを使用して、SKAdNetwork 4.0の変換値を細かい値、粗い値、ロックパラメータで更新します。これにより、変換値の更新をより細かく制御できます。

JavaScript 
// Check if running on iOS
if (device.platform === 'iOS') {
  function updateSKAN4ConversionValue(fineValue, coarseValue, shouldLock) {
    // Map coarse value string to number
    var coarseMap = { low: 0, medium: 1, high: 2 };

    // Update SKAdNetwork 4.0 conversion values
    cordova.plugins.SingularCordovaSdk.skanUpdateConversionValues(
      fineValue,
      coarseMap[coarseValue],
      shouldLock,
      function(success) {
        if (success) {
          console.log('SKAN 4.0 updated: fine=' + fineValue + ', coarse=' + coarseValue + ', lock=' + shouldLock);
        }
      }
    );
  }

  // Example: High-value user completes tutorial
  function onTutorialComplete() {
    updateSKAN4ConversionValue(15, 'medium', false);
  }

  // Example: Premium purchase - lock the value
  function onPremiumPurchase() {
    updateSKAN4ConversionValue(63, 'high', true);
  }
}

現在のコンバージョン値の取得

Singular SDKが追跡している現在の変換値を取得します。これは現在の状態に基づいた条件ロジックを実装するのに便利で、マネージドモードとマニュアルモードの両方で機能します。

JavaScript 
// Check if running on iOS
if (device.platform === 'iOS') {
  function checkAndUpdateConversionValue() {
    cordova.plugins.SingularCordovaSdk.skanGetConversionValue(function(currentValue) {
      if (currentValue !== null) {
        console.log('Current conversion value: ' + currentValue);

        // Only update if current value is below threshold
        if (currentValue < 30) {
          cordova.plugins.SingularCordovaSdk.skanUpdateConversionValue(30, function(success) {
            if (success) {
              console.log('Updated conversion value to 30');
            }
          });
        }
      } else {
        console.warn('Conversion value not available');
      }
    });
  }
}

コンバージョン値の更新を監視する

コンバージョン値が変更されるたびにリアルタイムの通知を受け取るハンドラを設定します。これにより、コンバージョン値の更新に反応し、分析を記録したり、他のアプリの動作をトリガーしたりすることができます。

JavaScript 
// Create configuration with conversion value handler
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  "YOUR_SDK_KEY",
  "YOUR_SDK_SECRET"
);

// Set up conversion value update handler
singularConfig.withConversionValueUpdatedHandler(function(conversionValue) {
  console.log('Conversion value updated to: ' + conversionValue);

  // Log the update to your analytics
  logConversionValueUpdate(conversionValue);

  // Trigger app-specific behavior
  if (conversionValue >= 50) {
    unlockPremiumFeature();
  }
});

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

function logConversionValueUpdate(value) {
  // Your analytics logging logic
  console.log('Analytics: SKAN CV = ' + value);
}

function unlockPremiumFeature() {
  // Your custom logic
  console.log('Premium feature unlocked based on high conversion value');
}

ベストプラクティスアプリ全体の現在のコンバージョン状態の同期ビューを維持するために、コンバージョン値ハンドラを使用します。これは、デバッグやカスタムロジックが正しく動作することを確認するために特に便利です。

その他のリソースSKAdNetworkのセットアップとベストプラクティスに関する包括的なガイドは、SingularのSKAdNetworkガイドをご覧ください。

App Tracking Transparency (ATT)のサポート

App Tracking Transparency (ATT)は、デバイスのIDFA (Identifier for Advertisers)にアクセスしてユーザーデータを共有する前に、ユーザーの同意を必要とするAppleのプライバシーフレームワークです。ATTを正しく実装することは、iOSのアトリビューションとユーザー獲得キャンペーンの精度を最大化するために非常に重要です。

ATTがアトリビューションに重要な理由

iOS 14.5以降、アプリはIDFAにアクセスする前に、ATTフレームワークを通じてユーザーの許可を要求する必要があります。IDFAがなくてもフィンガープリンティングや確率的な方法でアトリビューションは可能ですが、IDFAがあることでアトリビューションの精度が大幅に向上し、決定論的なマッチングが可能になります。

  • 決定論的アトリビューション：IDFAは、広告インプレッションとインストールを直接結びつける正確なデバイスレベルのアトリビューションを可能にします。
  • 広告ネットワークの最適化：広告ネットワークは、IDFAにアクセスすることで、キャンペーンをより最適化し、より正確なレポートを提供できます。
  • ユーザーレベルのインサイト：IDFAにアクセスすることで、より詳細なユーザー行動分析とコホート追跡が可能になります。

推奨ATTプロンプトを実装し、ユーザーの同意を求めることを強くお勧めします。ユーザーにメリット（パーソナライズされた広告、より良いアプリ体験）を説明し、オプトイン率を最大化する。

実装要件

iOS 14.5+（iOS 18を含む）では、トラッキングのためにIDFAにアクセスする前に、ATTrackingManagerフレームワークを使用してユーザーの同意を求めます。Singular SDKはATTをサポートしており、同意の前に初期化を行い、同意が得られるかタイムアウトが発生するまでイベントを遅延させることができます。

ステップ1：ATTフレームワーク設定を追加する

Info.plistファイルをユーザー向けの使用説明で更新することで、ATTフレームワークをサポートするようにiOSアプリを設定します。

  1. Info.plistに追加します：iOSプロジェクトのInfo.plistファイル（platforms/ios/[YourAppName]/[YourAppName]-Info.plist にあります）に、NSUserTrackingUsageDescription キーを含めます。
  2. 明確な説明を提供する：ATTプロンプトでユーザーに表示される、アプリがトラッキング許可を必要とする理由の明確な説明を追加します。
Info.plist 
<key>NSUserTrackingUsageDescription</key>
<string>This app uses tracking to provide personalized ads and improve your experience.</string>

重要:使用方法の説明は、ATTプロンプトでユーザーに表示されます。トラッキングがユーザーにどのような利益をもたらすかについて、明確かつ簡潔に、そして正直に説明してください。

ステップ2: ATTサポートプラグインのインストール

サードパーティのCordovaプラグインをインストールし、アプリでATT機能を有効にします。cordova-plugin-tracking-transparency プラグインは、Apple の ATTrackingManager への JavaScript インターフェイスを提供します。

bash 
cordova plugin add cordova-plugin-tracking-transparency

プラグインのリファレンス：詳細なドキュメントと使用例については、cordova-plugin-tracking-transparency GitHub リポジトリを参照してください。

ステップ3：SDK待ちタイムアウトの設定

waitForTrackingAuthorizationWithTimeoutInterval プロパティを設定することで、初期化する前にユーザーのATT応答を待つようにSingular SDKを設定します。 この遅延により、ユーザーが許可を与えた場合にIDFAがキャプチャされるようになります。

重要です：Singular SDKが最初のセッションを送信する前に、必ずATTの同意を要求し、IDFAを取得してください。これを怠ると、そのデバイスのアトリビューションデータのIDFAが永久に失われます。

JavaScript 
// Create configuration with ATT wait timeout
var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
  "YOUR_SDK_KEY",
  "YOUR_SDK_SECRET"
);

// Wait up to 5 minutes for ATT consent
singularConfig.withWaitForTrackingAuthorizationWithTimeoutInterval(300);

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

推奨値アプリがATTプロンプトを表示する場合は、タイムアウトを300秒（5分）に設定してください。これにより、プロンプトの表示が遅れたり表示されなかったりしても、ユーザーエクスペリエンスが低下することなく、ユーザーがプロンプトを見て応答するのに十分な時間が確保されます。

ステップ4：ATT同意を要求する

アプリにATTリクエストフローを実装し、ユーザーエクスペリエンスの適切なタイミングでトラッキング許可をユーザーに促します。

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

function initializeApp() {
  // Check if running on iOS
  if (device.platform === 'iOS') {
    // Request ATT authorization
    cordova.plugins.idfa.requestPermission().then(function(response) {
      var status = response.tracking;
      console.log('ATT Status:', status);
      // Possible values: 'authorized', 'denied', 'restricted', 'notDetermined'

      // Initialize Singular after ATT prompt
      initializeSingular();
    }).catch(function(error) {
      console.error('ATT Error:', error);
      // Initialize Singular even if ATT fails
      initializeSingular();
    });
  } else {
    // Android - initialize immediately
    initializeSingular();
  }
}

function initializeSingular() {
  // Create configuration with wait timeout
  var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
    "YOUR_SDK_KEY",
    "YOUR_SDK_SECRET"
  );

  singularConfig.withWaitForTrackingAuthorizationWithTimeoutInterval(300);
  singularConfig.withLoggingEnabled();

  // Initialize SDK
  cordova.plugins.SingularCordovaSdk.init(singularConfig);
  console.log('Singular SDK initialized');
}

フローを理解する

初期化遅延を設定すると、アプリのフローは以下のように動作します：

  1. セッション記録が開始されます：アプリが開くと、Singular SDKはセッションとユーザーイベントの記録を開始しますが、まだSingularサーバーには送信しません。
  2. 同意を待ちます：SDKは、App Tracking Transparencyの同意が許可/拒否されるか、設定された時間が経過するのを待ちます。
  3. データ送信：同意が解決されるかタイムアウトが発生すると、SDKはセッションとキューに入ったイベントをSingularサーバーに送信します（IDFAの有無は問いません）。
  4. アトリビューション開始：SingularはIDFAが利用可能な場合、それを利用してアトリビューションプロセスを開始します。

ATTシナリオ

次の表は、考えられるシナリオと IDFA の可用性をまとめたものです：

シナリオ IDFAの利用可能性
ユーザーが同意ダイアログを見て、設定された時間が経過する前に同意する。 IDFA が利用可能
ユーザーが同意ダイアログを見て、設定された時間が経過する前に同意を拒否する。 IDFAが利用できない
設定時間が経過し、同意ダイアログが表示され、同意する。 IDFA は、同意の後に報告されるユーザーイベントでのみ利用可能である。
設定時間が経過し、同意ダイアログが表示され、同意が拒否される。 IDFA は利用できない
ユーザが同意ダイアログを表示し、アクションを起こさずにアプリを終了し、設定時間が経過した後にアプリを開いて同意を与えた。 アプリが再び開かれると、キューに入れられたイベントがSingularサーバーに送信されます。同意が付与された後に追跡されるイベントには IDFA が関連付けられます。
ユーザーは同意ダイアログを表示され、アクションを起こさずにアプリを終了し、後でアプリを開いて同意を拒否します。 キューに入れられたイベントは、アプリが再び開かれたときにSingularサーバーに送信されます。IDFAは、これらのイベントやその後に追跡されるイベントでは使用できません。

ATTベストプラクティス

  • メッセージングを事前に促す：トラッキング許可が必要な理由と、それがユーザーにどのようなメリット（より良い広告、より良い体験）をもたらすかを説明するATT前の画面をユーザーに見せましょう。これにより、オプトイン率が大幅に向上します。
  • タイミングが重要：初回起動直後ではなく、アプリフローの自然なタイミングでATTプロンプトを表示しましょう。まずはユーザーにアプリを体験してもらい、信頼を築きましょう。
  • タイムアウトの設定： waitForTrackingAuthorizationWithTimeoutInterval を30～300秒に設定します。タイムアウト後、SingularはSKAN 4.0のアトリビューションで処理を進めます（IDFAなし）。
  • 徹底的にテストする：許可されたシナリオと拒否されたシナリオの両方をテストし、ユーザーの選択に関係なくアプリが正しく機能することを確認します。
  • ユーザーの選択を尊重してください：トラッキングを拒否したユーザーに対して何度もプロンプトを表示したり、オプトインを迫るような攻撃的なメッセージを表示したりしないでください。
  • エラー処理： restricted （ペアレンタルコントロールなど）またはnotDetermined のトラッキングステータスをチェックし、分析のためにログを記録します。
  • SKAN 4.0との統合：SKANのポストバックを最適化するために、コンバージョン値の更新がATTの同意と一致していることを確認する（例えば、イベントを値0～63にマッピングするためにSingularのダッシュボードを使用する）。

App Storeレビュー：ATTを適切に実装していないアプリや、フレームワークを回避しようとするアプリは、App Storeの審査で却下される可能性があります。Appleのガイドラインに従って実装し、ユーザーのプライバシーの選択を尊重するようにしてください。

その他のリソース