광고 구매 어트리뷰션

광고 구매을 사용자를 앱으로 유도한 특정 마케팅 캠페인에 연결하여 캠페인 비용, 인앱 구매, 광고 구매을 완벽하게 파악하여 정확한 ROI를 측정할 수 있습니다.

개요

광고 구매 어트리뷰션이란?

광고 구매 어트리뷰션은 모바일 앱 광고 구매을 사용자를 생성한 마케팅 캠페인에 연결하여 사용자 확보 비용을 광고 구매화를 포함한 평생 구매과 연결함으로써 진정한 캠페인 성과를 측정할 수 있도록 해줍니다.

• 캠페인 ROI: 연동 보고서에서 캠페인 비용, 인앱 구매, 광고 구매을 확인하여 실제 광고 투자 구매을 계산할 수 있습니다.
• 네트워크 최적화: 광고 구매 데이터를 광고 네트워크에 다시 전송하여 입찰 알고리즘과 캠페인 성과를 개선합니다.
• 데이터 소스: 애드몹, 앱러빈 맥스, 유니티 레벨플레이(아이언소스), 트레이드플러스 등 미디에이션 플랫폼의 사용자 수준 및 노출 수준 데이터를 지원합니다.

자세한 내용은 광고 구매 어트리뷰션 FAQ를 참조하세요.

구현 요구 사항

광고 구매 추적을 사용하려면 미디에이션 플랫폼 SDK와 연동하고 구매 콜백을 구성해야 합니다.

1. SDK 버전: 최신 Singular 코르도바 SDK 버전으로 업데이트해야 합니다.
2. 미디에이션 플랫폼: 미디에이션 플랫폼에 Cordova 호환 SDK를 연동하거나 타사 플러그인(AdMob, 앱러빈 MAX, 아이언소스 또는 트레이드플러스)을 사용하세요.
3. 구매 콜백: 플랫폼별 유료 이벤트 핸들러를 구현하여 노출 수준 구매 데이터를 캡처합니다.
4. 검증 로직: Singular로 데이터를 전송하기 전에 구매 및 통화 유효성 검사를 추가합니다.

SDK 방법

코드바.플러그인.Singular코드바에스디케이.광고구매

사용자 획득 캠페인에 대한 어트리뷰션을 위해 플랫폼, 통화 및 구매 금액과 함께 광고 구매 데이터를 Singular에 보고합니다.

메서드 서명:

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

파라미터:

• adData.adPlatform: 미디에이션 플랫폼 이름(예: "애드몹", "앱러빈", "아이언소스", "트레이드플러스").
• adData.currency: ISO 4217 세 글자 통화 코드(예: "USD", "EUR")
• adData.revenue: 지정된 통화로 표시된 구매 금액(0보다 커야 함)

전체 메서드 설명서는 광고 구매 참조를 참조하세요.

애드몹 연동

모든 광고 형식에 걸쳐 노출 수준 구매 보고를 위해 유료 이벤트 콜백을 사용하여 애드몹 광고 구매 추적을 구현하세요.

전제 조건

• 애드몹 계정에서 광고 구매 보고를 활성화합니다. 애드몹 지원보기
• 코르도바는 구글에서 공식적으로 지원하지 않으며 타사 플러그인이 필요합니다. 코드바-플러그인-애드몹-프리의 후속 버전으로 애드몹 플러스를 권장합니다. 시작 가이드를참조하세요.

구현 개요

광고 형식(앱 열기, 배너, 전면 광고, 네이티브, 보상형)을 로드할 때 광고가 구매을 창출할 때 트리거되는 유료 이벤트 핸들러를 구성합니다. 이벤트 데이터에서 구매 가치와 통화를 추출하고 두 값의 유효성을 검사하여 Singular로 전송합니다.

애드몹 리워드 광고 예시

리워드 광고 로드 및 추적

리워드 광고에 대한 이벤트 리스너를 구성하고 구매 추적을 위해 유료 이벤트를 캡처합니다.

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은 구매을 마이크로(백만 분의 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 및 무한대 제외
• 오류 처리: Try-catch 블록으로 충돌을 방지하고 자세한 오류 로깅 제공

모범 사례

데이터 유효성 검사

강력한 유효성 검사를 구현하여 잘못된 데이터가 Singular 분석에 도달하는 것을 방지하세요.

• 긍정적인 구매: 전송하기 전에 항상 구매이 0보다 큰지 확인합니다.
• 유효한 통화: ISO 4217 코드를 사용하고 비어 있지 않은 문자열을 확인합니다.
• 플랫폼 일관성: 앱 전체에서 일관된 플랫폼 이름을 사용하세요(예: 항상 "Admob" 또는 "ADMOB"이 아닌 "AdMob").
• 유형 검사: 데이터 유형이 예상 값과 일치하는지 확인합니다(구매의 경우 숫자, 통화/플랫폼의 경우 문자열).
• Null 검사: 널, 정의되지 않은 값, 비어있는 값을 적절하게 처리합니다.

통화 처리

여러 지역의 앱과 다양한 광고 네트워크에 대한 정확한 통화 보고를 보장합니다.

• 플랫폼 통화를 확인합니다: 미디에이션 플랫폼 문서에서 기본 통화를 확인하세요(대부분 USD 사용).
• 일관된 형식: 항상 대문자 세 글자로 구성된 ISO 4217 코드를 사용하세요.
• 전환 없음: 광고 네트워크에서 제공한 통화로 구매을 보고하세요. 통화를 변환하지 마세요.
• 네트워크별 통화: 애드 네트워크마다 다른 통화로 보고할 수 있습니다 - 각각 개별적으로 확인합니다.

플랫폼별 고려 사항

구매 보고 형식 및 단위의 플랫폼별 차이를 처리합니다.

• 애드몹: 애드몹 플러스 사용 시 모든 플랫폼에서 마이크로 단위로 보고된 구매은 1,000,000으로 나누어 달러로 변환됩니다.
• 트레이드플러스: 밀리 단위로 보고되는 eCPM - 1,000으로 나누면 달러로 변환됩니다.
• 앱러빈: 달러로 보고된 구매 - 직접 사용 가치
• IronSource: 달러 사용 가치로 직접 보고되는 구매

오류 처리 및 로깅

광고 구매 추적 디버깅 및 모니터링을 위한 포괄적인 로깅을 구현합니다.

• 유효성 검사 실패: 유효성 검사 실패 시 실제 수신된 값을 포함하여 자세한 오류 메시지를 기록합니다.
• 성공 로깅: 개발 중 성공적인 구매 보고서를 기록하여 연동을 확인합니다.
• 프로덕션 로깅: 오류 로그를 유지하면서 프로덕션에서 로깅의 장황함을 줄입니다.
• 디버그 모드: 디버그 플래그를 구현하여 문제 해결을 위한 상세 로깅을 전환합니다.

테스트 및 검증

프로덕션에 배포하기 전에 광고 구매 추적 구현을 검증하세요.

테스트 체크리스트

검증 테스트

1. 테스트 광고를 로드합니다: 미디에이션 플랫폼의 테스트 광고 단위 ID를 사용하여 광고 로딩을 확인합니다.
2. 구매 콜백을 확인합니다: 테스트 광고가 구매을 창출할 때 유료 이벤트 핸들러가 트리거되는지 확인합니다.
3. 데이터 형식 확인: 구매 값이 올바르게 변환되는지 확인합니다(애드몹의 경우 마이크로에서 달러로).
4. 통화 코드 검증: 통화 코드가 예상 형식(USD, EUR 등)과 일치하는지 확인합니다.
5. 콘솔 로그 모니터링: 콘솔 출력에서 성공적인 구매 보고서 및 오류를 검토합니다.
6. 오류 시나리오 테스트: 유효성 검사 로직이 오류를 포착하는지 확인하기 위해 의도적으로 유효하지 않은 데이터를 전달합니다.

Singular 대시보드 검증

구현 후 데이터가 Singular 대시보드에 올바르게 표시되는지 확인합니다.

1. 처리를 기다립니다: 초기 데이터가 처리되어 보고서에 표시될 때까지 24-48시간이 소요됩니다.
2. 광고 구매 보고서를 확인합니다: Singular 대시보드에서 광고 구매 어트리뷰션 보고서로 이동합니다.
3. 캠페인 어트리뷰션 확인: 정확한 획득 캠페인을 위해 구매 속성을 확인합니다.
4. 통화 확인: 구매이 올바른 통화로 표시되는지 확인합니다.
5. 플랫폼 분석 모니터링: 플랫폼 이름(애드몹 등)이 올바르게 표시되는지 확인합니다.