광고 수익 어트리뷰션

사용자를 앱으로 유입시킨 특정 마케팅 캠페인에 광고 수익을 연결하여 캠페인 비용, 인앱 수익, 광고 수익을 한눈에 파악하고 정확한 ROI를 측정할 수 있습니다.

개요

광고 수익 어트리뷰션이란

광고 수익 어트리뷰션은 모바일 앱의 광고 수익을 사용자를 유입시킨 마케팅 캠페인에 연결합니다. 이를 통해 사용자 획득 비용과 광고 수익화를 포함한 생애 수익을 연결하여 실제 캠페인 성과를 측정할 수 있습니다.

• 캠페인 ROI: 캠페인 비용, 인앱 구매, 광고 수익을 하나의 리포트에서 확인하여 실제 광고 비용 대비 수익률을 계산합니다
• 네트워크 최적화: 광고 수익 데이터를 광고 네트워크로 다시 전송하여 입찰 알고리즘과 캠페인 성과를 개선합니다
• 데이터 소스: AdMob, AppLovin MAX, Unity LevelPlay(IronSource), TradPlus 등 미디에이션 플랫폼의 사용자 단위 및 노출 단위 데이터를 지원합니다

자세한 내용은 다음을 참조하세요: 광고 수익 어트리뷰션 FAQ.

구현 요구사항

광고 수익 트래킹에는 미디에이션 플랫폼 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

필수 파라미터:

• ad_platform: 미디에이션 플랫폼 이름(예: "AdMob", "AppLovin", "IronSource", "TradPlus")
• ad_currency: ISO 4217 세 자리 통화 코드(예: "USD", "EUR")
• ad_revenue: 지정된 통화의 수익 금액(0보다 커야 함)

SingularAdData로 페이로드 구성하기

SingularAdData 는 생성자에서 필수 값 세 개를 받고, 선택 필드마다 체이닝 가능한 메서드를 제공합니다. 패키지에서 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의 광고 수익 리포팅이 세분화됩니다. 빌더 대신 일반 객체를 구성하는 경우 두 번째 열의 페이로드 키를 사용하세요.

전체 메서드 문서는 다음을 참조하세요: adRevenue 레퍼런스.

플랫폼 연동

AdMob 연동

Google Mobile Ads SDK의 유료 이벤트 콜백을 사용하여 노출 단위 수익을 보고하는 AdMob 광고 수익 트래킹을 구현합니다.

사전 요구사항

• AdMob 계정에서 광고 수익 리포팅을 활성화하세요. 참조: AdMob 지원
• React Native Google Mobile Ads 패키지를 연동하세요. 참조: 시작 가이드

구현 개요

광고 형식(App Open, Banner, Interstitial, Native, Rewarded)을 로드할 때, 광고가 수익을 발생시키면 트리거되는 유료 이벤트 핸들러를 구성하세요. 이벤트 데이터에서 수익 값과 통화를 추출하고 두 값을 모두 검증한 후 Singular로 전송하세요.

AdMob 리워드 광고 예제

AdMob으로 리워드 광고를 로드하고 수익 트래킹을 위해 유료 이벤트를 수집합니다.

// 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;
}

import React, { useEffect } from 'react';
import { Singular, SingularAdData } from 'singular-react-native';
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 = new SingularAdData(
      'AdMob',
      currencyCode,
      revenue
    );

    // Send to Singular
    Singular.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 광고 형식에 대한 전역 수익 리스너를 설정합니다.

// 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');
};

import { Singular, SingularAdData } from 'singular-react-native';
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 = new SingularAdData(
    'AppLovin',
    CURRENCY,
    revenue
  );

  // Send to Singular
  Singular.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 노출 데이터 콜백을 위한 이벤트 리스너를 구성합니다.

// 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');
};

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

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 = new SingularAdData(
      AD_PLATFORM,
      CURRENCY,
      revenue
    );

    // Send to Singular
    Singular.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로 전송하세요.

TradPlus 수익 트래킹

TradPlus 노출 성공 콜백을 위한 이벤트 리스너를 구성합니다.

// 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');
};

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

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 = new SingularAdData(
      AD_PLATFORM,
      CURRENCY,
      revenue
    );

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

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

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

구현 참고사항:

• eCPM 형식: TradPlus는 eCPM을 밀리 단위로 보고합니다. Singular로 전송하기 전에 항상 1000으로 나누세요
• 타입 확인: 변환 전에 eCPM이 숫자인지 확인하세요
• 변환 후 검증: 나눗셈 후 수익이 0보다 큰지 검증하세요

일반 연동

표준 연동에서 다루지 않는 커스텀 미디에이션 플랫폼이나 직접 연동의 경우 일반 adRevenue() 메서드를 사용하여 광고 수익 트래킹을 구현합니다.

일반 연동을 사용해야 하는 경우

• 표준 연동에서 다루지 않는 커스텀 미디에이션 플랫폼
• 미디에이션 없이 광고 네트워크와 직접 연동하는 경우
• 서버 측에서 계산되어 앱으로 전달되는 광고 수익
• 목 데이터로 광고 수익 트래킹을 테스트하는 경우

일반 구현 예제

적절한 검증과 함께 모든 소스의 광고 수익을 보고하는 재사용 가능한 함수를 만듭니다.

// 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);
};

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

/**
 * 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 = new SingularAdData(
    adPlatform.trim(),
    currency.toUpperCase().trim(),
    revenue
  );

  // Send to Singular
  Singular.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);
};

검증 기능:

• 플랫폼 검증: 플랫폼 이름이 비어 있지 않고 공백이 제거되었는지 확인합니다
• 통화 검증: 세 자리 ISO 4217 코드 형식을 확인하고 대문자로 변환합니다
• 수익 검증: 양수인지 확인하고 NaN과 Infinity를 제외합니다
• 타입 안전성: TypeScript 인터페이스가 컴파일 시점의 타입 검사를 보장합니다

모범 사례

데이터 검증

잘못된 데이터가 Singular 분석에 유입되지 않도록 견고한 검증을 구현하세요.

• 양의 수익: 전송 전에 항상 수익이 0보다 큰지 확인하세요
• 유효한 통화: ISO 4217 코드를 사용하고 문자열이 비어 있지 않은지 확인하세요
• 플랫폼 일관성: 앱 전반에서 일관된 플랫폼 이름을 사용하세요(예: "Admob"이나 "ADMOB"이 아니라 항상 "AdMob")
• 타입 확인: 데이터 타입이 예상 값과 일치하는지 확인하세요(수익은 숫자, 통화/플랫폼은 문자열)
• Null 확인: null, undefined, 빈 값을 적절히 처리하세요

통화 처리

다중 지역 앱과 다양한 광고 네트워크에서 정확한 통화 보고를 보장하세요.

• 플랫폼 통화 확인: 미디에이션 플랫폼 문서에서 기본 통화를 확인하세요(대부분 USD 사용)
• 일관된 형식: 항상 대문자 세 자리 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가 올바르게 초기화되었는지 확인하세요
• 수익이 0: 플랫폼별 변환 로직을 확인하세요(Android AdMob은 마이크로에서 달러로, TradPlus는 밀리에서 달러로)
• 잘못된 통화: 통화 코드가 미디에이션 플랫폼이 보고하는 값과 일치하는지 확인하세요. 플랫폼 문서를 참조하세요
• 플랫폼 이름 불일치: Singular가 인식하는 플랫폼과 일치하는 일관된 플랫폼 이름을 사용하세요
• 이벤트 누락: 광고 수익 이벤트가 발생하기 전에 Singular SDK가 초기화되었는지 확인하세요
• 중복 이벤트: 유료 이벤트 핸들러가 광고 로드마다가 아니라 한 번만 등록되었는지 확인하세요