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(adData: SingularAdData | {
    ad_platform: string;
    ad_currency: string;
    ad_revenue: number;
    [key: string]: any;
}): void

キー名は厳密に照合されます。 SDKは ad_platform、 ad_currency 、および ad_revenueを参照します。この3つのいずれかが欠けている場合、 adRevenue() は何も送信せずに戻り、エラーも発生させません。そのため、キー名を打ち間違えると失敗ではなく無反応という形で現れます。ペイロードを SingularAdData で構築すれば、このリスクを回避できます。

必須パラメータ:

  • ad_platform: メディエーションプラットフォーム名（例: "AdMob"、"AppLovin"、"IronSource"、"TradPlus"）
  • ad_currency: ISO 4217の3文字通貨コード（例: "USD"、"EUR"）
  • ad_revenue: 指定した通貨での収益額（0より大きい必要があります）

SingularAdDataによるペイロードの構築

SingularAdData はコンストラクタで3つの必須値を受け取り、オプションフィールドごとにチェーン可能なメソッドを提供します。パッケージから Singularとともにインポートしてください。 

import { Singular, SingularAdData } from 'singular-react-native';

const adData = new SingularAdData('AdMob', 'USD', 0.05)
  .withAdUnitId('ca-app-pub-1234567890123456/9876543210')
  .withAdType('Rewarded')
  .withPrecision('precise');

Singular.adRevenue(adData);

オプションの広告データフィールド

以下のフィールドはすべて任意です。メディエーションプラットフォームが報告する値をできるだけ送信してください。ペイロードが充実するほど、Singularの広告収益レポートはより詳細になります。ビルダーの代わりにプレーンオブジェクトを構築する場合は、2列目のペイロードキーを使用してください。

ビルダーメソッド ペイロードキー 詳細
withNetworkName() ad_mediation_platform インプレッションを報告するメディエーションプラットフォーム。デフォルトはコンストラクタに渡された ad_platform の値です。
withAdType() ad_type 広告フォーマット。例: Rewarded、 Interstitial 、 Bannerなど。
withGroupType() ad_group_type メディエーションプラットフォームが報告する広告グループタイプ。
withImpressionId() ad_impression_id 一意のインプレッション識別子。Singularがインプレッションを重複排除できるようになります。
withAdPlacementName() ad_placement_name 人が読める形式のプレースメント名。
withPlacementId() ad_placement_id プレースメント識別子。
withAdUnitId() ad_unit_id 広告ユニット識別子。
withAdUnitName() ad_unit_name 人が読める形式の広告ユニット名。
withAdGroupId() ad_group_id 広告グループ識別子。
withAdGroupName() ad_group_name 人が読める形式の広告グループ名。
withAdGroupPriority() ad_group_priority メディエーションプラットフォームが報告する広告グループの優先度。
withPrecision() ad_precision メディエーションプラットフォームが報告する収益の精度。例: precise、 estimated 、 publisher_definedなど。
withLimitDataSharing() sng_attr_limit_data_sharing この広告収益イベントのみをデータ共有の制限対象としてマークします。SDK 全体の limitDataSharing 設定とは独立しています。Boolean。React Native SDK 4.3.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で割る必要があります。iOSはドル単位でそのまま報告します（0.005）。プラットフォーム判定に応じて変換ロジックを調整してください。

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/js/NativeSingular';
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 = {
      ad_platform: 'AdMob',
      ad_currency: currencyCode,
      ad_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統合

すべての広告フォーマットでリアルタイムの収益を報告するImpression-Level User Revenue 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/js/NativeSingular';
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 = {
    ad_platform: 'AppLovin',
    ad_currency: CURRENCY,
    ad_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');
};

実装上の注意:

  • すべての広告フォーマット: アプリで使用するすべての広告タイプ（Interstitial、Rewarded、Banner、MRec、App Open）にリスナーを登録してください
  • 通貨: AppLovinは通常USDで収益を報告します。ダッシュボードで確認してください
  • 共通ハンドラー: 一貫した検証のため、すべての広告フォーマットで単一の収益ハンドラー関数を使用してください

Unity LevelPlay（IronSource）統合

IronSource Adsおよびメディエーションネットワークからのインプレッションレベルデータを取得するため、Impression Level Revenue（ILR）SDK APIを使用してIronSource広告収益トラッキングを実装します。

前提条件

  • IronSource React Native SDKを統合してください。参照: スタートガイド
  • IronSourceダッシュボードでARM SDK Postbacksフラグを有効にしてください
  • 以下をご確認ください: 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/js/NativeSingular';

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 = {
      ad_platform: AD_PLATFORM,
      ad_currency: CURRENCY,
      ad_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フラグが有効になっていることを確認してください
  • イベントのサブスクライブ: IronSource SDKを初期化する前にリスナーを設定してください

TradPlus統合

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

前提条件

  • アプリにTradPlus React Native SDKを統合してください
  • ダッシュボードでTradPlusの広告ユニットを設定してください

実装の概要

広告インプレッションデータを受け取るには、 onImpressionSuccess イベントをサブスクライブしてください。 tpAdInfo.ecpmからeCPM値を抽出し、ミリ単位からドルに変換した（1000で割る）うえでSingularに送信してください。

eCPMの変換: TradPlusはeCPMをミリ単位で報告します。Singularに送信する前に、eCPM値を1000で割ってドル金額に変換してください。

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/js/NativeSingular';

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 = {
      ad_platform: AD_PLATFORM,
      ad_currency: CURRENCY,
      ad_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/js/NativeSingular';

/**
 * 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 = {
    ad_platform: adPlatform.trim(),
    ad_currency: currency.toUpperCase().trim(),
    ad_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の分析に流入しないよう、堅牢な検証を実装してください。

  • 正の収益: 送信前に必ず収益が0より大きいことを確認してください
  • 有効な通貨: ISO 4217コードを使用し、文字列が空でないことを確認してください
  • プラットフォーム名の一貫性: アプリ全体で一貫したプラットフォーム名を使用してください（例: "Admob"や"ADMOB"ではなく、常に"AdMob"）
  • 型チェック: データ型が期待値と一致することを確認してください（収益は数値、通貨とプラットフォームは文字列）
  • Nullチェック: null、undefined、空の値を適切に処理してください

重要: 誤った広告収益データはSingularで後から修正できません。以下を呼び出す前に必ずデータを検証してください: Singular.adRevenue()。

通貨の扱い

多地域展開のアプリやさまざまな広告ネットワークにおいて、正確な通貨報告を確保してください。

  • プラットフォームの通貨を確認: メディエーションプラットフォームのドキュメントでデフォルト通貨を確認してください（ほとんどはUSDを使用）
  • 一貫した形式: 常に大文字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メソッドリファレンス。