広告収益のアトリビューション

広告収入を、ユーザーをアプリに呼び込んだ特定のマーケティングキャンペーンに関連付け、キャンペーンコスト、アプリ内収益、広告収入を完全に可視化し、正確なROI測定を実現します。

概要

広告収益アトリビューションとは

広告収益アトリビューションは、モバイルアプリの広告収益をユーザーを生み出したマーケティングキャンペーンに結び付け、ユーザー獲得コストを広告収益化を含むライフタイム収益に結び付けることで、真のキャンペーンパフォーマンスを測定できるようにします。

• キャンペーンROI：キャンペーンコスト、アプリ内課金、広告収益を統合レポートで表示し、広告費に対する真のリターンを算出します。
• ネットワークの最適化：広告収益データを広告ネットワークに送信し、入札アルゴリズムとキャンペーンパフォーマンスを改善します。
• データソース：AdMob、AppLovin MAX、Unity LevelPlay（IronSource）、TradPlusなどのメディエーションプラットフォームからのユーザーレベルおよびインプレッションレベルのデータをサポートします。

詳細については、広告収益アトリビューションFAQをご覧ください。

実装要件

広告収益のトラッキングには、媒介プラットフォームSDKとの統合と収益コールバックの設定が必要です。

1. SDKのバージョン：最新のSingular Cordova SDKバージョンにアップデートしてください。
2. 仲介プラットフォーム：メディエーション・プラットフォーム用のCordova互換SDKを統合するか、サードパーティー・プラグイン（AdMob、AppLovin MAX、IronSource、TradPlus）を使用します。
3. 収益コールバック：プラットフォーム固有の有料イベント ハンドラーを実装し、インプレッション レベルの収益データを取得します。
4. 検証ロジック：データをSingularに送信する前に、収益と通貨の検証を追加します。

SDK メソッド

コードバプラグイン.SingularCordovaSdk.adRevenue

広告収益データをプラットフォーム、通貨、収益額と共に Singular に報告し、ユーザーの獲得キャンペーンにアトリビューションします。

メソッドの署名

cordova.plugins.SingularCordovaSdk.adRevenue(adData: Object): void

パラメータ

• adData.adPlatform：メディエーションプラットフォーム名（例："AdMob"、"AppLovin"、"IronSource"、"TradPlus")
• adData.currency：ISO 4217の3文字の通貨コード（"USD"、"EUR "など
• adData.revenue：指定した通貨での収益額 (0より大きくなければなりません)

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

AdMobとの統合

すべての広告フォーマットでインプレッションレベルの収益レポートを作成するために、有料イベントコールバックを使用してAdMob広告の収益トラッキングを実装します。

前提条件

• AdMobアカウントで広告収益レポートを有効にする。AdMob サポートを参照してください。
• Cordova は Google によって公式にサポートされていないため、サードパーティ製のプラグインが必要です。AdMob Plusは cordova-plugin-admob-free の後継として推奨されています。入門ガイドをご覧ください。

実装の概要

広告フォーマット（App Open、Banner、Interstitial、Native、Rewarded）をロードする際、広告が収益を発生させた際にトリガーされる有料イベントハンドラを設定します。 イベントデータから収益の値と通貨を抽出し、両方の値を検証して Singular に送信します。

AdMobリワード広告の例

リワード広告のロードとトラッキング

リワード広告のイベントリスナーを設定し、収益追跡のために有料イベントをキャプチャします。

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

async function initializeAdMob() {
  const admob = window.cordova.plugins.AdMobPlus;
  
  // Initialize RewardedAd with your ad unit ID
  const rewarded = admob.RewardedAd.create({
    adUnitId: 'ca-app-pub-xxxxxxxxxxxxx/yyyyyyyyyy',
    isTesting: true // Set to false for production
  });

  // Handle the 'paid' event to capture revenue details
  rewarded.on('paid', (event) => {
    const { value, currencyCode } = event;
    
    // Validate revenue and currency data
    if (value > 0 && currencyCode) {
      // Convert from micros to dollars
      const revenueAmount = value / 1_000_000.0;
      
      // Create ad data object
      const adData = new cordova.plugins.SingularCordovaSdk.SingularAdData(
        'AdMob',
        currencyCode,
        revenueAmount
      );

      // Send Ad Revenue data to Singular
      cordova.plugins.SingularCordovaSdk.adRevenue(adData);

      // Log for debugging
      console.log('Ad Revenue reported to Singular:', {
        adPlatform: 'AdMob',
        currency: currencyCode,
        revenue: revenueAmount
      });
    } else {
      console.error('Invalid ad revenue data:', { value, currencyCode });
    }
  });

  // Handle ad lifecycle events
  rewarded.on('load', async () => {
    console.log('Rewarded ad loaded');
    await rewarded.load(); // Preload next ad
  });

  rewarded.on('show', () => {
    console.log('Rewarded ad shown');
  });

  rewarded.on('dismiss', async () => {
    console.log('Rewarded ad dismissed');
    await rewarded.load(); // Load new ad for future use
  });

  rewarded.on('error', (error) => {
    console.error('Error with rewarded ad:', error);
  });

  // Initial ad load
  await rewarded.load();
}
        

実装上の注意事項

• 収益コンバージョン：AdMobはマイクロ（100万分の1）単位で収益を返します - 1,000,000で割ってドルに変換します。
• データの検証：送信前に収益が0より大きく、通貨コードが存在することを確認する。
• イベント処理：すべてのライフサイクルイベント（ロード、ショー、ディスイズ、エラー）を登録し、完全な広告管理を実現します。
• プリロード：待ち時間を最小限に抑えるため、広告が表示された直後に次の広告をロードします。

ダイレクトプラットフォームレポート

メディエーションプラットフォームの統合がないシナリオやカスタム広告の実装では、検証済みのデータを使用して広告収益を直接レポートします。

手動広告収益レポート

ヘルパー関数の作成

あらゆるソースからの広告収益をレポートするための包括的な検証を備えた再利用可能な関数を構築します。

// Reusable ad revenue reporting function with validation
function reportAdRevenue(mediationPlatform, currencyCode, revenueAmount) {
  // Validate mediation platform
  if (!mediationPlatform || typeof mediationPlatform !== 'string' || mediationPlatform.trim() === '') {
    console.error('Invalid mediation platform:', mediationPlatform);
    return;
  }

  // Validate currency code (ISO 4217 format)
  if (!currencyCode || typeof currencyCode !== 'string' || currencyCode.length !== 3) {
    console.error('Invalid currency code:', currencyCode);
    return;
  }

  // Validate revenue amount
  if (typeof revenueAmount !== 'number' || revenueAmount <= 0 || isNaN(revenueAmount) || !isFinite(revenueAmount)) {
    console.error('Invalid revenue amount:', revenueAmount);
    return;
  }

  try {
    // Create SingularAdData object
    const adData = new cordova.plugins.SingularCordovaSdk.SingularAdData(
      mediationPlatform,
      currencyCode.toUpperCase(), // Ensure uppercase
      revenueAmount
    );

    // Report Ad Revenue to Singular
    cordova.plugins.SingularCordovaSdk.adRevenue(adData);

    // Log success
    console.log('Ad Revenue reported successfully:', {
      mediationPlatform: adData.mediationPlatform,
      currencyCode: adData.currencyCode,
      revenueAmount: adData.revenueAmount
    });
  } catch (error) {
    // Log any errors that occur during the process
    console.error('Failed to report Ad Revenue:', error);
  }
}

// Usage examples
document.addEventListener('deviceready', function() {
  // Example: Report revenue from a custom ad network
  reportAdRevenue('CustomNetwork', 'USD', 0.05);
  
  // Example: Report revenue from direct ad placement
  reportAdRevenue('FacebookAudienceNetwork', 'EUR', 0.03);
}, false);

検証機能

• プラットフォームの検証：プラットフォーム名が空でなく、トリミングされていることを確認します。
• 通貨検証：3文字のISO 4217コードフォーマットを検証し、大文字に変換します。
• 収益の検証：正数のチェック、NaNとInfinityの除外
• エラー処理：トライ・キャッチ・ブロックがクラッシュを防ぎ、詳細なエラー・ログを提供します。

ベストプラクティス

データの検証

不正なデータがSingular analyticsに到達するのを防ぐため、堅牢な検証を実装します。

• 正の収益：送信前に収益がゼロより大きいことを常に確認する
• 有効な通貨：ISO 4217コードを使用し、空でない文字列を検証します。
• プラットフォームの一貫性：アプリ全体で一貫したプラットフォーム名を使用すること（例：「Admob」や「ADMOB」ではなく、常に「AdMob」を使用すること
• 型チェック：データ型が期待値と一致していることを確認する（収益は数値、通貨/プラットフォームは文字列
• Nullチェック：NULL、未定義、空の値を適切に処理する。

通貨の取り扱い

マルチリージョンアプリや多様な広告ネットワークに対して、正確な通貨レポーティングを保証します。

• プラットフォームの通貨を確認する：メディエーションプラットフォームのデフォルト通貨を確認する。
• 一貫したフォーマット：常に大文字の3文字のISO 4217コードを使用します。
• 変換なし：広告ネットワークが提供する通貨で収益を報告する。
• ネットワークごとの通貨：異なる広告ネットワークは異なる通貨で報告する可能性がある。

プラットフォーム固有の考慮事項

収益報告フォーマットとユニットのプラットフォームの違いに対応する。

• AdMob：AdMob Plusを使用している場合、すべてのプラットフォームで収益をドルに変換するために1,000,000で割ります。
• TradPlus:eCPMはミリ単位で報告され、1,000で割るとドルに変換されます。
• AppLovin:ドル建てで収益が報告されます。
• IronSource：ドル建てで収益を報告-直接使用

エラー処理とロギング

広告収益トラッキングのデバッグとモニタリングのために包括的なロギングを実装します。

• 検証の失敗：検証に失敗した場合、実際に受信した値を含む詳細なエラーメッセージをログに記録します。
• 成功ロギング：開発中に成功した収益レポートをログに記録し、統合を検証します。
• 本番ロギング：エラーログを維持しながら、本番環境でのロギングの冗長性を削減します。
• デバッグモード：トラブルシューティングのための詳細なロギングを切り替えるデバッグフラグを実装する。

テストと検証

本番環境にデプロイする前に、広告収益トラッキングの実装を検証する。

テストチェックリスト

検証テスト

1. 広告のロードテスト：メディエーション・プラットフォームのテスト広告ユニットIDを使用して、広告のロードを検証します。
2. 収益コールバックの検証：テスト広告の収益発生時に有料イベントハンドラがトリガーされることを確認します。
3. データフォーマットの確認収益値が正しく変換されることを確認します（AdMobの場合はマイクロからドルへ）。
4. 通貨コードの検証通貨コードが期待されるフォーマット（USD、EURなど）と一致していることを確認する。
5. コンソールログの監視成功した収益レポートとエラーのコンソール出力を確認する
6. テストエラーシナリオ：意図的に無効なデータを渡し、検証ロジックがエラーを検出することを検証します。

単一ダッシュボードの検証

実装後、データがSingularダッシュボードに正しく表示されることを確認します。

1. 処理を待つ：初期データが処理され、レポートに表示されるまで24～48時間待ちます。
2. 広告収益レポートを確認する：Singularダッシュボードの広告収益アトリビューションレポートに移動します。
3. キャンペーンのアトリビューションを確認します：正しい獲得キャンペーンの収益属性を確認する
4. 通貨を検証する：収益が正しい通貨で表示されることを確認
5. プラットフォームの内訳を監視する：プラットフォーム名（AdMobなど）が正しく表示されているか確認する