보상형 광고

지원 중단됨: Google 모바일 광고 C++ SDK는 2024년 6월 17일부터 지원 중단되었으며 아직 사용하지 않는 프로젝트에 채택해서는 안 됩니다. 2025년 6월 17일에 유지보수 종료 (EoM)가 시작됩니다. 유지보수 종료일 전에 출시된 SDK 버전은 계속 작동하지만 유지보수 종료일 이후에는 더 이상 버그 수정이나 변경사항이 출시되지 않습니다.

Google 모바일 광고 C++ SDK 대신 AdMob의 iOS 및 Android SDK를 사용하는 것이 좋습니다. 지원이 필요하면 Google 모바일 광고 SDK 기술 포럼에 문의하세요.

보상형 광고는 사용자에게 상호작용에 대한 대가로 인앱 리워드를 제공하는 광고입니다. 이 가이드에서는 Google 모바일 광고 C++ SDK를 사용하여 보상형 광고를 Android 및 iOS 앱에 통합하는 방법을 설명합니다.

고객 성공사례인 우수사례 1과 우수사례 2를 읽어보세요.

기본 요건

• 시작하기를 완료합니다.
• (Android만 해당) JNI jobject 참조를 사용하는 데 익숙해야 합니다 (Android JNI 도움말 참고).

항상 테스트 광고로 테스트

앱을 빌드하고 테스트할 때는 운영 중인 실제 광고 대신 테스트 광고를 사용하세요. 이렇게 하지 않으면 계정이 정지될 수 있습니다.

테스트 광고를 로드하는 가장 쉬운 방법은 기기 플랫폼에 따라 달라지는 보상형 광고 전용 테스트 광고 단위 ID를 사용하는 것입니다.

• Android: ca-app-pub-3940256099942544/5224354917
• iOS: ca-app-pub-3940256099942544/1712485313

이 ID는 모든 요청에 대해 테스트 광고를 반환하도록 특별히 구성되었으며, 코딩, 테스트 및 디버깅 중에 앱에서 자유롭게 사용할 수 있습니다. 앱을 게시하기 전에 이 ID를 자체 광고 단위 ID로 바꿔야 합니다.

모바일 광고 SDK의 테스트 광고가 작동하는 방식을 자세히 알아보려면 테스트 광고를 참고하세요.

구현

보상형 광고를 통합하는 기본 단계는 다음과 같습니다.

1. 광고를 로드합니다.
2. 콜백을 등록합니다.
3. 광고를 표시하고 보상 이벤트를 처리합니다.

RewardedAd 구성

보상형 광고는 RewardedAd 객체에 표시되므로 보상형 광고를 앱에 통합하려면 먼저 RewardedAd 인스턴스를 만들고 초기화해야 합니다.

1. 앱의 C++ 코드에 다음 헤더를 추가합니다.

    #include "firebase/gma/rewarded_ad.h"

2. RewardedAd 객체를 선언하고 인스턴스화합니다.

    firebase::gma::RewardedAd* rewarded_ad;
    rewarded_ad = new firebase::gma::RewardedAd();

3. 상위 뷰를 AdParent 유형으로 전송하여 RewardedAd 인스턴스를 초기화합니다. 상위 뷰는 Android Activity에 대한 JNI jobject 참조 또는 iOS UIView에 대한 포인터입니다.

   // my_ad_parent is a jobject reference to an Android Activity or
   // a pointer to an iOS UIView.
   firebase::gma::AdParent ad_parent =
     static_cast<firebase::gma::AdParent>(my_ad_parent);
   firebase::Future<void> result = rewarded_ad->Initialize(ad_parent);
   

4. future를 변수로 유지하는 대신 RewardedAd 객체에서 InitializeLastResult()를 호출하여 초기화 작업의 상태를 주기적으로 확인할 수 있습니다. 이는 전역 게임 루프에서 초기화 프로세스를 추적하는 데 도움이 될 수 있습니다.

   // Monitor the status of the future in your game loop:
   firebase::Future<void> result = rewarded_ad->InitializeLastResult();
   if (result.status() == firebase::kFutureStatusComplete) {
     // Initialization completed.
     if(future.error() == firebase::gma::kAdErrorCodeNone) {
       // Initialization successful.
     } else {
       // An error has occurred.
     }
   } else {
     // Initialization on-going.
   }
   

firebase::Future 사용에 관한 자세한 내용은 Future를 사용하여 메서드 호출의 완료 상태 모니터링을 참고하세요.

광고 로드

광고는 RewardedAd 객체의 LoadAd() 메서드를 사용하여 로드됩니다. 로드 메서드에는 RewardedAd 객체가 초기화되어 있고 광고 단위 ID와 AdRequest 객체가 있어야 합니다. 로드 작업의 상태와 결과를 모니터링하는 데 사용할 수 있는 firebase::Future가 반환됩니다.

다음 코드는 RewardedAd가 초기화된 후 광고를 로드하는 방법을 보여줍니다.

firebase::gma::AdRequest ad_request;
firebase::Future<firebase::gma::AdResult> load_ad_result;
load_ad_result = rewarded_ad->LoadAd(rewarded_ad_unit_id, ad_request);

콜백 등록

보상형 광고 표시 및 수명 주기 이벤트 알림을 받으려면 FullScreenContentListener 클래스를 확장해야 합니다. 맞춤 FullScreenContentListener 서브클래스는 RewardedAd::SetFullScreenContentListener() 메서드를 통해 등록할 수 있으며, 광고가 표시되거나 닫힐 때뿐만 아니라 광고가 표시되거나 닫힐 때도 콜백을 수신합니다.

다음 코드는 클래스를 확장하고 광고에 할당하는 방법을 보여줍니다.

  class ExampleFullScreenContentListener
      : public firebase::gma::FullScreenContentListener {

   public:
    ExampleFullScreenContentListener() {}

    void OnAdClicked() override {
      // This method is invoked when the user clicks the ad.
    }

    void OnAdDismissedFullScreenContent() override {
     // This method is invoked when the ad dismisses full screen content.
    }

    void OnAdFailedToShowFullScreenContent(const AdError& error) override {
      // This method is invoked when the ad failed to show full screen content.
      // Details about the error are contained within the AdError parameter.
    }

    void OnAdImpression() override {
      // This method is invoked when an impression is recorded for an ad.
    }

    void OnAdShowedFullScreenContent() override {
      // This method is invoked when the ad showed its full screen content.
    }
  };

  ExampleFullScreenContentListener* example_full_screen_content_listener =
    new ExampleFullScreenContentListener();
  rewarded_ad->SetFullScreenContentListener(example_full_screen_content_listener);

RewardedAd는 일회용 객체입니다. 즉, 보상형 광고가 표시된 후에는 다시 표시되지 않습니다. 이전 광고가 닫히자마자 다음 보상형 광고가 로드될 수 있도록 FullScreenContentListener의 OnAdDismissedFullScreenContent() 메서드에서 다른 보상형 광고를 로드하는 것이 좋습니다.

광고 표시 및 보상 이벤트 처리

보상형 광고를 게재하기 전에 보상을 받는 대가로 보상형 광고 콘텐츠를 볼 것인지 여부를 선택할 수 있는 옵션을 사용자에게 명확히 제공해야 합니다. 보상형 광고에는 항상 선택 옵션을 제공해야 합니다.

광고를 표시할 때 사용자의 보상을 처리할 UserEarnedReward 객체를 제공해야 합니다.

다음 코드는 RewardedAd를 표시하는 방법을 보여줍니다.

// A simple listener track UserEarnedReward events.
class ExampleUserEarnedRewardListener :
    public firebase::gma::UserEarnedRewardListener {
 public:
   ExampleUserEarnedRewardListener() { }

  void OnUserEarnedReward(const firebase::gma::AdReward& reward) override {
    // Reward the user!
  }
};

ExampleUserEarnedRewardListener* user_earned_reward_listener =
  new ExampleUserEarnedRewardListener();
firebase::Future<void> result = rewarded_ad->Show(user_earned_reward_listener);

FAQ

초기화 호출에 제한 시간이 있나요?

10초 후 미디에이션 네트워크에서 아직 초기화를 완료하지 않은 경우에도 Google 모바일 광고 C++ SDK는 Initialize()에서 반환된 firebase::Future를 완료합니다.

초기화 콜백을 받았을 때 일부 미디에이션 네트워크가 준비되지 않은 경우 어떻게 해야 하나요?

SDK 초기화가 완료된 후에 광고를 로드하는 것이 좋습니다. 미디에이션 네트워크가 준비되지 않은 경우에도 Google 모바일 광고 C++ SDK에서 해당 네트워크에 광고를 요청합니다. 따라서 미디에이션 네트워크에서 시간이 초과된 후에 초기화를 완료해도 해당 세션에서 향후 광고 요청을 처리할 수 있습니다.

GetInitializationStatus()를 호출하여 앱 세션 전체에서 모든 어댑터의 초기화 상태를 계속 폴링할 수 있습니다.

특정 미디에이션 네트워크가 준비되지 않은 이유를 확인하려면 어떻게 해야 하나요?

AdapterStatus.description()을 통해 어댑터에서 광고 요청을 처리할 준비가 되지 않은 이유를 알아볼 수 있습니다. 미디에이션 어댑터 상태 로깅의 예는 GitHub의 예시 빠른 시작 앱 소스 코드를 참고하세요.

추가 리소스

GitHub의 예제

• GitHub에서 예시 빠른 시작 앱의 소스 코드를 확인하세요.