보상형 동영상

AdMob 미디에이션을 통해 AdMob을 사용하여 C++ 앱에 보상형 동영상을 표시할 수 있습니다.

이 가이드에서는 보상형 동영상을 요청 및 표시하고, 보상형 동영상을 표시할 수 있는 시점을 확인하고, 사용자에게 보상을 지급하는 방법을 보여줍니다.

기본 요건

보상형 동영상 C++ API를 사용하려면 보상형 동영상을 게재할 앱에 미디에이션 네트워크 어댑터 및 SDK를 포함해야 합니다. 앱에 보상형 동영상 미디에이션을 추가하는 방법은 게시자의 iOSAndroid용 보상형 동영상 가이드를 참조하세요.

또한 C++ 앱에서 AdMob과 Firebase를 처음으로 설정하는 것이라면 AdMob C++ 시작하기 가이드를 참조하여 앱을 AdMob 및 Firebase와 통합하는 단계별 안내를 확인하세요.

rewarded_video 네임스페이스와 상호작용

rewarded_video 네임스페이스에는 Google 모바일 광고 SDK를 통해 보상형 동영상을 표시하는 메서드가 포함되어 있습니다. 자체적인 객체가 있는 배너 및 전면 광고와 달리 보상형 동영상은 rewarded_video 네임스페이스의 정적 메서드를 통해 제어됩니다.

rewarded_video 네임스페이스에 액세스하려면 앱의 C++ 코드에 다음 include 지시문을 추가합니다.

#include "firebase/admob/rewarded_video.h"

rewarded_video 네임스페이스와 상호작용하는 기본적인 단계는 다음과 같습니다.

  1. Initialize()를 호출하여 라이브러리와 미디에이션 어댑터를 초기화합니다.

    firebase::admob::rewarded_video::Initialize();
    
  2. 이제 라이브러리와 미디에이션 어댑터가 초기화되었으므로, LoadAd()를 호출하여 보상형 동영상을 로드할 수 있습니다.

    firebase::admob::AdRequest my_ad_request;
    // Set some or all of the member variables in the AdRequest struct.
    firebase::admob::rewarded_video::LoadAd("YOUR_REWARDED_AD_UNIT_ID", my_ad_request);
    

    광고 요청을 타겟팅하고 맞춤설정하는 예시는 AdMob 광고 요청 만들기를 참조하세요.

  3. 보상형 동영상이 로드되었으면 Show()를 호출하여 사용자에게 동영상을 표시합니다.

    // my_ad_parent is a reference to an iOS UIView or an Android Activity. This is
    // the parent UIView or Activity of the rewarded video.
    firebase::admob::rewarded_video::Show(my_ad_parent);
    
  4. 필요하면 2단계와 3단계를 반복합니다.

  5. Pause()를 호출하여 보상형 동영상과 관련된 백그라운드 처리를 모두 일시중지합니다.

    firebase::admob::rewarded_video::Pause();
    

    C++ 엔진이 일시중지되거나 애플리케이션이 포커스를 잃을 때마다 이 메서드를 호출하세요.

  6. 예를 들어 사용자가 Google Play에서 앱으로 돌아갈 때 Resume()을 호출하여 일시중지를 해제합니다.

    firebase::admob::rewarded_video::Resume();
    
  7. 앱에서 보상형 동영상 광고 표시를 마치면 Destroy()를 호출하여 보상형 동영상 네임스페이스에서 사용한 리소스를 모두 정리하고 할당을 취소합니다.

    firebase::admob::rewarded_video::Destroy();
    

위 단계에서는 보상형 동영상을 로드하고 표시할 때 앱에서 사용할 기본적인 메서드 호출을 설명했습니다. 그러나 이러한 메서드를 호출하기 전에는 이전 메서드 호출의 완료 상태를 모니터링하는 것이 좋습니다. 다음 섹션에서는 Future를 사용하여 이전에 호출한 rewarded_video 네임스페이스 메서드의 완료 상태를 확인하는 방법을 설명합니다.

Future를 사용하여 메서드 호출의 완료 상태 모니터링

Future로 이전에 호출한 rewarded_video 메서드의 완료 상태를 파악할 수 있습니다. 예를 들어 rewarded_video::Initialize() 메서드를 호출하면 새 Future가 생성 및 반환됩니다. 자세한 내용은 firebase::Future를 참조하세요. 앱은 Future의 상태를 조사하여 초기화 완료 시점을 파악할 수 있습니다. Future가 완료 상태이면 보상형 동영상을 로드할 준비가 된 것입니다.

rewarded_video 네임스페이스의 메서드 중 대부분에는 상응하는 '최종 결과' 메서드가 있으며, 앱에서는 이 메서드로 특정 작업의 가장 최근 Future를 검색할 수 있습니다. 예를 들어 Initialize() 메서드에는 InitializeLastResult()라는 메서드가 있으며, 이 메서드는 가장 최근에 이루어진 Initialize() 호출의 Future를 반환합니다.

if (firebase::admob::rewarded_video::InitializeLastResult().status() ==
    firebase::kFutureStatusComplete &&
    firebase::admob::rewarded_video::InitializeLastResult().error() ==
    firebase::admob::kAdMobErrorNone) {
  firebase::admob::rewarded_video::LoadAd("YOUR_REWARDED_AD_UNIT_ID",
      my_ad_request);
}

LoadAdLastResult() 메서드를 사용하여 마지막 LoadAd() 메서드 호출의 상태를 나타내는 Future를 가져옵니다. 이 Future가 완료 상태가 되면 앱에서 다음 번에 발생하는 적절한 중지 시점에 보상형 동영상을 표시할 수 있습니다.

if (firebase::admob::rewarded_video::LoadAdLastResult().status() ==
    firebase::kFutureStatusComplete &&
    firebase::admob::rewarded_video::LoadAdLastResult().error() ==
    firebase::admob::kAdMobErrorNone) {
  // my_ad_parent is a reference to an iOS UIView or an Android Activity.
  // This is the parent UIView or Activity of the rewarded video.
  firebase::admob::rewarded_video::Show(my_ad_parent);
}

리스너를 사용하여 광고 수명 주기 이벤트 알림 받기

AdMob rewarded_video 네임스페이스에서 제공되는 추상 Listener 클래스를 확장하여 SetListener() 메서드에 전달하면 보상과 보상형 동영상의 표시 상태 변경에 대한 알림을 받을 수 있습니다.

다음은 Listener 추상 클래스의 확장 클래스 구현 예시입니다.

// A simple listener that logs changes to rewarded video state.
class LoggingRewardedVideoListener
    : public firebase::admob::rewarded_video::Listener {
 public:
  LoggingRewardedVideoListener() {}
  void OnRewarded(firebase::admob::rewarded_video::RewardItem reward) override {
    LogMessage("Rewarding user with %f %s.", reward.amount,
               reward.reward_type.c_str());
  }
  void OnPresentationStateChanged(
      firebase::admob::rewarded_video::PresentationState state) override {
    LogMessage("Rewarded video PresentationState has changed to %d.", state);
  }
};

// After calling Initialize and waiting for the Initialize future to complete
// successfully, set the listener.
LoggingRewardedVideoListener rewarded_video_listener;
firebase::admob::rewarded_video::SetListener(&rewarded_video_listener);

보상 조사

rewarded_video 네임스페이스에서 제공되는 PollableRewardListener 클래스를 인스턴스화하여 SetListener() 메서드에 전달할 수도 있습니다. 이 클래스는 추상 Listener 클래스를 확장하지 않고도 보상에 액세스하기 위한 대체 옵션을 제공합니다.

조사 방식의 리스너에서 대기열을 사용하여 모바일 광고 SDK가 부여하는 보상을 유지관리하고 나중에 검색할 수 있습니다. PollableRewardListenerPollReward(RewardItem* reward) 메서드는 대기열에서 가장 오래된 보상을 찾고 관련 데이터를 제공된 RewardItem 구조체에 복사합니다.

다음은 rewarded_video::PollableRewardListener 클래스를 사용하여 보상을 조사하는 구현 예시입니다.

// After calling Initialize and waiting for the Initialize future to complete
// successfully, instantiate a PollableRewardListener object and set the listener.
firebase::admob::rewarded_video::PollableRewardListener* listener =
    new firebase::admob::rewarded_video::PollableRewardListener();

// Pass the PollableRewardListener object to the SetListener method.
firebase::admob::rewarded_video::SetListener(listener);

...
// Display the rewarded videos to users so they can earn rewards.
...

// Declare a RewardItem struct. Pass this RewardItem struct by reference to
// the PollReward method.
firebase::admob::rewarded_video::RewardItem reward;
// Call the PollReward method to see if a reward is available.
while (listener->PollReward(&reward)) {
  // A reward is available. Do something with the reward.
  printf("Reward user with %f %s.", reward.amount, reward.reward_type);
}

간단한 게임 루프 예시

다음은 상태 머신을 사용하여 rewarded_video 네임스페이스에 대한 메서드 호출을 추적하는 간단한 게임 루프입니다.

namespace rewarded_video = firebase::admob::rewarded_video;

enum State {
  kNextStepInitialize,
  kNextStepLoadAd,
  kNextStepShowAd,
  kNextStepRewardUser,
  kNextStepRestartGame
}

// Instantiate a PollableRewardListener object.
firebase::admob::rewarded_video::PollableRewardListener* listener =
    new firebase::admob::rewarded_video::PollableRewardListener();

State state = kNextStepInitialize;
for ( ; ; ) /* game loop */ {
  switch (state) {
    case kNextStepInitialize:
      rewarded_video::Initialize();
      state = kNextStepLoadAd;
      break;
    case kNextStepLoadAd:
      if (rewarded_video::InitializeLastResult().status() ==
          firebase::kFutureStatusComplete &&
          rewarded_video::InitializeLastResult().error() ==
          firebase::admob::kAdMobErrorNone) {
        // Pass the PollableRewardListener object to the SetListener method.
        firebase::admob::rewarded_video::SetListener(listener);
        rewarded_video::LoadAd("YOUR_REWARDED_AD_UNIT_ID",
                               my_ad_request);
      }
      state = kNextStepShowAd;
      break;
    case kNextStepShowAd:
      if (rewarded_video::LoadAdLastResult().status() ==
          firebase::kFutureStatusComplete &&
          rewarded_video::LoadAdLastResult().error() ==
          firebase::admob::kAdMobErrorNone) {
        rewarded_video::Show(my_ad_parent);
      }

      if (rewarded_video::ShowLastResult().status() ==
          firebase::kFutureStatusComplete &&
          rewarded_video::ShowLastResult().error() ==
          firebase::admob::kAdMobErrorNone &&
          rewarded_video::presentation_state() ==
          rewarded_video::kPresentationStateHidden) {
        // If the rewarded video has been displayed to the user and
        // the user closed the ad, then reward the user.
        state = kNextStepRewardUser;
      }
      break;
    case kNextStepRewardUser:
      firebase::admob::rewarded_video::RewardItem reward;
      // Call the PollReward method to see if a reward is available.
      while (listener->PollReward(&reward)) {
        // A reward is available. Do something with the reward.
        printf("Reward user with %f %s.", reward.amount, reward.reward_type);
      }
      state = kNextStepRestartGame;
      break;
    case kNextStepRestartGame:
      // restart game
      break;
  }

  // render game
}

다음 단계

보상형 동영상 광고에 대한 자세한 내용은 iOS 보상형 동영상Android 보상형 동영상 시작 가이드를 참조하세요.