React Native SDK - 広告収入のトラッキング

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

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

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

概要

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

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

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

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

重要な考慮事項

  1. 通貨コード：ISO 4217の3文字の通貨コード（USD、EUR、INR）を使用してください。ほとんどのメディエーション・プラットフォームはUSDでレポートします。
  2. データの正確性：Singularに送信する前に、収益と通貨データを検証してください。不正確なデータは遡って修正できません。

実装要件

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

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

SDKメソッド

Singular.adRevenue

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

メソッドの署名 

static adRevenue(data: {
    adPlatform: string;
    currency: string;
    revenue: number;
}): void

パラメータ

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

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

プラットフォーム統合

AdMobインテグレーション

インプレッションレベルの収益レポート用に、Google Mobile Ads SDKのペイドイベントコールバックを使用してAdMob広告の収益トラッキングを実装します。

前提条件

  • AdMobアカウントで広告収益レポートを有効にする。AdMob サポートを参照してください。
  • React Native Google Mobile Ads パッケージを統合します。入門ガイドを参照。

実装の概要

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

プラットフォームの違い：AdMobはプラットフォームによって異なる収益を報告します。Androidはマイクロ単位で収益を報告するため（例えば、$0.005は5000と表示される）、1,000,000で割る必要があります。プラットフォームの検出に基づいてコンバージョンロジックを調整します。

AdMobリワード広告の例

AdMobでリワード広告を読み込み、収益追跡のために有料イベントをキャプチャします。

New ArchitectureOld Architecture 
// TurboModule direct API (React Native 0.76+ New Architecture)
import React, { useEffect } from 'react';
import NativeSingular from 'singular-react-native/jsNativeSingular';
import { RewardedAd, AdEventType } from 'react-native-google-mobile-ads';
import { Platform } from 'react-native';

const AD_UNIT_ID = 'ca-app-pub-xxxxxxxxxxxxx/yyyyyyyyyy';

export default function AdMobRevenueTracker() {
  useEffect(() => {
    loadRewardedAd();
  }, []);

  const loadRewardedAd = () => {
    // Create RewardedAd instance
    const rewardedAd = RewardedAd.createForAdRequest(AD_UNIT_ID);

    // Set up event listener for ad events
    rewardedAd.addAdEventListener((type, error, data) => {
      if (type === AdEventType.LOADED) {
        console.log('Rewarded ad loaded');
      } else if (type === AdEventType.ERROR) {
        console.error('Rewarded ad failed to load:', error);
      } else if (type === AdEventType.PAID_EVENT) {
        // Handle paid event with revenue data
        handleAdRevenue(data);
      }
    });

    // Load the ad
    rewardedAd.load();
  };

  const handleAdRevenue = (data) => {
    const { value, currencyCode } = data;

    // Validate revenue and currency
    if (!value || value <= 0) {
      console.error('Invalid ad revenue value:', value);
      return;
    }

    if (!currencyCode || currencyCode.trim() === '') {
      console.error('Invalid currency code:', currencyCode);
      return;
    }

    // Convert revenue based on platform
    let revenue;
    if (Platform.OS === 'android') {
      // Android reports in micros - convert to dollars
      revenue = value / 1_000_000.0;
    } else {
      // iOS reports in dollars directly
      revenue = value;
    }

    const adRevenueData = {
      adPlatform: 'AdMob',
      currency: currencyCode,
      revenue: revenue
    };

    // Send to Singular
    NativeSingular.adRevenue(adRevenueData);

    console.log('Ad Revenue reported to Singular:', adRevenueData);
  };

  return null;
}

実装の注意事項

  • プラットフォームの検出： Platform.OSを使用してコンバージョンロジックを決定します（Androidは1,000,000で除算、iOSは値を直接使用）。
  • 収益の検証：送信前に収益が0より大きいことを確認する。
  • 通貨の検証：通貨コードが空でないことを確認
  • エラーログ：Singularに送信することなく、デバッグのために無効なデータをログします。

AppLovin MAXとの統合

インプレッションレベルユーザー収益APIを使用してAppLovin MAX広告収益トラッキングを実装し、全ての広告フォーマットでリアルタイムの収益レポートを作成します。

前提条件

  • AppLovin MAX React Native SDKを統合します。スタートアップガイドを参照
  • AppLovinダッシュボードでImpression-Level User Revenue APIを有効にする。

実装の概要

各広告フォーマット（Interstitial、Rewarded、Banner、MRec、App Open）に対して広告収益リスナーを設定し、収益イベントをキャプチャします。adInfo.revenue から収益を抽出し、プラットフォーム固有の通貨（通常USD）でSingularに送信します。

AppLovin MAXの収益トラッキング

すべてのAppLovin MAX広告フォーマットにグローバル収益リスナーを設定します。

New ArchitectureOld Architecture 
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';
import {
  InterstitialAd,
  RewardedAd,
  BannerAd,
  MRecAd,
  AppOpenAd
} from 'react-native-applovin-max';

// Currency constant - AppLovin typically reports in USD
const CURRENCY = 'USD';

// Generic handler for ad revenue
const handleAdRevenue = (adInfo) => {
  if (!adInfo) {
    console.error('AdInfo is null or undefined');
    return;
  }

  const revenue = adInfo.revenue;

  // Validate revenue
  if (!revenue || revenue <= 0) {
    console.error('Invalid revenue value:', revenue);
    return;
  }

  const adRevenueData = {
    adPlatform: 'AppLovin',
    currency: CURRENCY,
    revenue: revenue
  };

  // Send to Singular
  NativeSingular.adRevenue(adRevenueData);

  console.log('AppLovin ad revenue reported:', adRevenueData);
};

// Set up listeners for each ad type
export const setupAppLovinRevenueTracking = () => {
  InterstitialAd.addAdRevenuePaidListener(handleAdRevenue);
  RewardedAd.addAdRevenuePaidListener(handleAdRevenue);
  BannerAd.addAdRevenuePaidListener(handleAdRevenue);
  MRecAd.addAdRevenuePaidListener(handleAdRevenue);
  AppOpenAd.addAdRevenuePaidListener(handleAdRevenue);

  console.log('AppLovin MAX revenue tracking initialized');
};

実装上の注意事項

  • 全ての広告フォーマット：アプリが使用する全ての広告タイプ（インタースティシャル、リワード、バナー、MRec、アプリオープン）のリスナーを登録します。
  • 通貨AppLovinは通常USDで収益を報告します。
  • 共有ハンドラ：一貫した検証を保証するために、すべての広告フォーマットに単一の収益ハンドラ関数を使用します。

Unity LevelPlay（IronSource）との統合

IronSource広告と仲介ネットワークからのインプレッションレベルのデータに対して、Impression Level Revenue (ILR) SDK APIを使用してIronSource広告収益トラッキングを実装します。

前提条件

実装の概要

onImpressionDataSuccess イベントエミッターを購読し、インプレッションデータを受信します。impressionData.revenue から収益を抽出し、USD通貨でSingularに送信します。

IronSource収益トラッキング

IronSourceインプレッションデータコールバックのイベントリスナーを設定します。

New ArchitectureOld Architecture 
// TurboModule direct API (React Native 0.76+ New Architecture)
import { NativeModules, NativeEventEmitter } from 'react-native';
import NativeSingular from 'singular-react-native/jsNativeSingular';

const { IronSourceModule } = NativeModules;
const ironSourceEventEmitter = new NativeEventEmitter(IronSourceModule);

const AD_PLATFORM = 'IronSource';
const CURRENCY = 'USD'; // IronSource typically reports in USD

export const setupIronSourceRevenueTracking = () => {
  ironSourceEventEmitter.addListener('onImpressionDataSuccess', (impressionData) => {
    // Validate impression data
    if (!impressionData) {
      console.error('No impression data available');
      return;
    }

    const revenue = impressionData.revenue;

    // Validate revenue value
    if (!revenue || revenue <= 0) {
      console.error('Invalid revenue value:', revenue);
      return;
    }

    const adRevenueData = {
      adPlatform: AD_PLATFORM,
      currency: CURRENCY,
      revenue: revenue
    };

    // Send to Singular
    NativeSingular.adRevenue(adRevenueData);

    console.log('IronSource ad revenue reported:', adRevenueData);
  });

  console.log('IronSource revenue tracking initialized');
};

実装上の注意事項

  • ネイティブイベントエミッター：IronSourceはReact Nativeのネイティブイベントシステムをインプレッションコールバックに使用します。
  • ARMポストバック：IronSourceのダッシュボードでARM SDK Postbacks Flagが有効になっていることを確認してください。
  • イベントサブスクリプション：IronSource SDKを初期化する前にリスナーを設定します。

TradPlusとの統合

グローバルインプレッションリスナーを使用してTradPlus広告収益トラッキングを実装し、広告インプレッションからeCPMデータを取得します。

前提条件

  • TradPlus React Native SDKをアプリに統合する。
  • ダッシュボードでTradPlus広告ユニットを設定する

実装の概要

onImpressionSuccess イベントを購読して広告インプレッションデータを受信する。tpAdInfo.ecpm からeCPM値を抽出し、ミリからドルに変換（1000で割る）し、Singularに送信します。

eCPM変換：TradPlusはeCPMをミリ単位で報告します。 eCPMの値を1000で割ってドルに変換してからSingularに送信します。

TradPlus収益トラッキング

TradPlusインプレッション成功コールバックのイベントリスナーを設定します。

New ArchitectureOld Architecture 
// TurboModule direct API (React Native 0.76+ New Architecture)
import { NativeModules, NativeEventEmitter } from 'react-native';
import NativeSingular from 'singular-react-native/jsNativeSingular';

const { TradPlusModule } = NativeModules;
const tradPlusEventEmitter = new NativeEventEmitter(TradPlusModule);

const AD_PLATFORM = 'TradPlus';
const CURRENCY = 'USD'; // TradPlus typically reports in USD

export const setupTradPlusRevenueTracking = () => {
  tradPlusEventEmitter.addListener('onImpressionSuccess', (tpAdInfo) => {
    // Validate ad info
    if (!tpAdInfo) {
      console.error('AdInfo is null');
      return;
    }

    // eCPM is reported in milli-units - convert to dollars
    if (!tpAdInfo.ecpm || typeof tpAdInfo.ecpm !== 'number') {
      console.error('Invalid eCPM value:', tpAdInfo.ecpm);
      return;
    }

    const revenue = tpAdInfo.ecpm / 1000.0;

    // Validate revenue after conversion
    if (revenue <= 0) {
      console.error('Revenue out of expected range:', revenue);
      return;
    }

    const adRevenueData = {
      adPlatform: AD_PLATFORM,
      currency: CURRENCY,
      revenue: revenue
    };

    // Send to Singular
    NativeSingular.adRevenue(adRevenueData);

    console.log('TradPlus ad revenue reported:', adRevenueData);
  });

  console.log('TradPlus revenue tracking initialized');
};

実装上の注意事項：

  • eCPMフォーマット：TradPlusはeCPMをミリ単位でレポートします-Singularに送信する前に必ず1000で割ってください。
  • タイプのチェック：変換前にeCPMが数値であることを確認する。
  • コンバージョン後の検証：除算後に収益が0より大きいことを検証する

一般的な統合

一般的なadRevenue() メソッドを使用して、カスタムの仲介プラットフォームまたは直接統合の広告収益トラッキングを実装します。

汎用インテグレーションを使用する場合

  • 標準インテグレーションでカバーされていないカスタム媒介プラットフォーム
  • メディエーションなしのダイレクト広告ネットワーク統合
  • アプリに転送されるサーバー側の広告収益計算
  • モックデータを使用した広告収益トラッキングのテスト

ジェネリック実装例

適切な検証を行うことで、あらゆるソースからの広告収入をレポートする再利用可能な関数を作成します。

New ArchitectureOld Architecture 
// TurboModule direct API (React Native 0.76+ New Architecture)
import NativeSingular from 'singular-react-native/jsNativeSingular';

/**
 * Report ad revenue to Singular with validation
 * 
 * @param {string} adPlatform - Name of the ad platform or mediation provider
 * @param {string} currency - ISO 4217 three-letter currency code (e.g., 'USD', 'EUR')
 * @param {number} revenue - Revenue amount in the specified currency
 */
export const reportAdRevenue = (adPlatform, currency, revenue) => {
  // Validate platform
  if (!adPlatform || adPlatform.trim() === '') {
    console.error('Invalid ad platform:', adPlatform);
    return;
  }

  // Validate currency code
  if (!currency || currency.trim() === '' || currency.length !== 3) {
    console.error('Invalid currency code:', currency);
    return;
  }

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

  const adRevenueData = {
    adPlatform: adPlatform.trim(),
    currency: currency.toUpperCase().trim(),
    revenue: revenue
  };

  // Send to Singular
  NativeSingular.adRevenue(adRevenueData);

  console.log('Ad Revenue reported to Singular:', adRevenueData);
};

// Example usage
export const trackCustomAdRevenue = () => {
  // Example: Custom mediation platform
  reportAdRevenue('CustomPlatform', 'USD', 0.05);

  // Example: Direct network integration
  reportAdRevenue('FacebookAudienceNetwork', 'EUR', 0.03);
};

検証機能

  • プラットフォームの検証：プラットフォーム名が空でなく、トリミングされていることを確認します。
  • 通貨検証：3文字のISO 4217コード形式を検証し、大文字に変換します。
  • 収益の検証：正数のチェック、NaNとInfinityの除外
  • 型の安全性：TypeScript インターフェースがコンパイル時の型チェックを保証

ベストプラクティス

データの検証

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

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

クリティカル：不適切な広告収入データは、Singularで遡って修正することはできません。Singular.adRevenue() を呼び出す前に必ずデータを検証してください。

通貨の取り扱い

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

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

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

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

  • AdMob Android：マイクロ単位で収益を報告-1,000,000で割ってドルに変換
  • AdMob iOS：ドル建てで収益を報告 - 変換せずに直接値を使用
  • TradPlus:eCPMはミリ単位で報告され、1,000で割るとドルに変換されます。
  • AppLovin:ドル建てで収益が報告される。
  • IronSource：ドル建てで報告される収益-直接使用価値

エラー処理とロギング

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

  • 検証の失敗：検証に失敗した場合、実際に受信した値を含む詳細なエラーメッセージをログに記録します。
  • 成功ロギング：成功した収益レポートをプラットフォーム、通貨、金額とともに開発中にログに記録します。
  • 本番監視：エラー追跡サービス（Sentry、Bugsnag）を使用して、本番環境での検証失敗を監視する。
  • 収益異常：統合の問題を示す可能性のある、異常に高いまたは低い収益値に関するアラート
  • プラットフォームカバレッジ：どの広告プラットフォームが収益を報告しているかを監視し、すべてが正しく統合されていることを確認する。

テスト戦略

本番展開前に広告収益トラッキングの実装を検証する。

  1. 広告のテスト：メディエーション・プラットフォームのテスト広告ユニットを開発中に使用する。
  2. イベントを検証する：テスト広告インプレッション後の広告収益イベントをSingularダッシュボードで確認する。
  3. 通貨の確認：通貨コードがSingularのレポートに正しく表示されるか確認する
  4. プラットフォームの正確性：プラットフォーム名が一貫しており、レポート内で認識可能であることを確認します。
  5. 収益額：収益額がテスト広告ユニットの予想範囲と一致していることを確認します。
  6. マルチプラットフォーム：iOSとAndroidの両方でテストし、プラットフォーム固有のコンバージョンロジックを検証します。

パフォーマンスの最適化

広告収益トラッキングによるアプリのパフォーマンスへの影響を最小限に抑えます。

  • 非同期処理：収益コールバックは非同期で実行され、メインスレッドのブロックはありません。
  • 最小限の検証：検証ロジックをシンプルかつ高速に保つ（型チェック、範囲チェック
  • バッチの考慮：大量アプリの場合、アナリティクスバックエンドがサポートしていれば、バッチ処理を検討する。
  • エラー処理：try-catchブロックを使用して、収益追跡エラーがアプリをクラッシュさせないようにする。

検証とトラブルシューティング

実装の確認

広告収益データがSingularに正しく流れていることを確認します。

  1. テスト広告を有効にする：メディエーションプラットフォームでテストモードを設定する。
  2. インプレッションをトリガーする：テスト広告を表示し、有料イベントをトリガーする
  3. ログの確認収益追跡ログが正しい値でコンソールに表示されることを確認します。
  4. ダッシュボードの確認：広告収益イベントのSingularダッシュボードを確認（15～30分かかる場合があります
  5. イベントの詳細：Singularのイベント詳細で通貨、プラットフォーム、収益額を確認する

よくある問題

  • 収益イベントがない：広告をロードする前に有料イベントハンドラが登録され、メディエーションSDKが正しく初期化されていることを確認する。
  • 収益ゼロ：プラットフォーム固有の変換ロジックを確認する（Android AdMobではマイクロからドルへ、TradPlusではミリからドルへ）。
  • 通貨の間違い：メディエーションプラットフォームが報告する通貨コードと一致しているか確認する。
  • プラットフォーム名の不一致：Singularが認識しているプラットフォームと一致する一貫したプラットフォーム名を使用してください。
  • イベントの欠落広告収益イベントが発生する前にSingular SDKが初期化されていること。
  • イベントの重複：有料イベントハンドラが、広告ロードのたびに登録されるのではなく、一度だけ登録されることを確認する。

その他のリソース詳細情報については、広告収益アトリビューションFAQおよびReact Native SDKメソッドリファレンスを参照してください。