Reklamy z nagrodą


Reklamy z nagrodą dają użytkownikom możliwość interakcji w zamian za nagrody w aplikacji. Z tego przewodnika dowiesz się, jak zintegrować reklamy z nagrodą z aplikacjami na Androida i aplikacjami na iOS za pomocą pakietu SDK do reklam mobilnych Google w C++.

Przeczytaj historie sukcesu klientów: studium przypadku 1, studium przypadku 2.

Wymagania wstępne

Zawsze przeprowadzaj testy z użyciem reklam testowych

Podczas tworzenia i testowania aplikacji używaj reklam testowych, a nie aktywnych reklam produkcyjnych. Jeśli tego nie zrobisz, Twoje konto może zostać zawieszone.

Najłatwiejszym sposobem wczytywania reklam testowych jest użycie naszego specjalnego identyfikatora testowej jednostki reklamowej dla reklam z nagrodą, który różni się w zależności od platformy urządzenia:

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

Zostały one specjalnie skonfigurowane tak, aby zwracać reklamy testowe w przypadku każdego żądania. Możesz ich używać we własnych aplikacjach podczas kodowania, testowania i debugowania. Pamiętaj, aby przed opublikowaniem aplikacji zastąpić go własnym identyfikatorem jednostki reklamowej.

Więcej informacji o tym, jak działają reklamy testowe w pakiecie SDK do wyświetlania reklam mobilnych, znajdziesz w artykule na ten temat.

Implementacja

Główne kroki integracji reklam z nagrodą:

  1. Wczytaj reklamę.
  2. Zarejestruj się, aby otrzymywać połączenia zwrotne.
  3. Wyświetl reklamę i obsłuż zdarzenie po otrzymaniu nagrody.

Konfigurowanie RewardedAd

Reklamy z nagrodą są wyświetlane w obiektach RewardedAd, więc pierwszym krokiem do zintegrowania reklam z nagrodą z aplikacją jest utworzenie i zainicjowanie instancji RewardedAd.

  1. Dodaj do kodu C++ aplikacji ten nagłówek: 

     #include "firebase/gma/rewarded_ad.h"

  2. Zadeklaruj i utwórz instancję obiektu RewardedAd: 

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

  3. Zainicjuj instancję RewardedAd, używając widoku nadrzędnego rzutowanego na typ AdParent. Widok nadrzędny to odwołanie JNI jobject do obiektu Activity na Androidzie lub wskaźnik do obiektu UIView na iOS.

    // 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. Zamiast zachowywać obiekt Future jako zmienną, możesz okresowo sprawdzać stan operacji inicjowania, wywołując metodę InitializeLastResult() na obiekcie RewardedAd. Może to być przydatne do śledzenia procesu inicjowania w globalnej pętli gry.

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

Więcej informacji o korzystaniu z firebase::Future znajdziesz w artykule Używanie obiektów Futures do monitorowania stanu ukończenia wywołań metod.

Wczytywanie reklamy

Reklamę wczytuje się za pomocą metody LoadAd() w obiekcie RewardedAd. Metoda wczytywania wymaga zainicjowania obiektu RewardedAd oraz podania identyfikatora jednostki reklamowej i obiektu AdRequest. Zwracany jest obiekt firebase::Future, którego możesz użyć do monitorowania stanu i wyniku operacji wczytywania.

Poniższy kod pokazuje, jak wczytać reklamę po zainicjowaniu 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);

Rejestrowanie wywołań zwrotnych

Aby otrzymywać powiadomienia o wyświetlaniu reklam z nagrodą i zdarzeniach cyklu życia, musisz rozszerzyć klasę FullScreenContentListener. Niestandardową podklasę FullScreenContentListener można zarejestrować za pomocą metody RewardedAd::SetFullScreenContentListener(). Będzie ona otrzymywać wywołania zwrotne, gdy reklama zostanie wyświetlona (lub nie) oraz gdy zostanie zamknięta.

Poniższy kod pokazuje, jak rozszerzyć klasę i przypisać ją do reklamy:

  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 jest obiektem jednorazowego użytku. Oznacza to, że po wyświetleniu reklamy z nagrodą nie można jej wyświetlić ponownie. Zgodnie ze sprawdzoną metodą warto wczytać kolejną reklamę z nagrodą w metodzie OnAdDismissedFullScreenContent() obiektu FullScreenContentListener, aby następna reklama z nagrodą zaczęła się wczytywać, gdy tylko poprzednia zostanie zamknięta.

Wyświetlanie reklamy i obsługa zdarzenia po otrzymaniu nagrody

Zanim zaczniesz wyświetlać użytkownikom reklamę z nagrodą, musisz im dać możliwość wyraźnego wyboru, czy chcą obejrzeć treść reklamy z nagrodą w zamian za nagrodę. Reklamy z nagrodą muszą zawsze być wyświetlane za zgodą użytkownika.

Podczas wyświetlania reklamy musisz podać obiekt UserEarnedReward, aby obsłużyć nagrodę dla użytkownika.

Poniższy kod pokazuje, jak wyświetlić 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);

Najczęstsze pytania

Czy wywołanie inicjujące ma limit czasu?
Po 10 sekundach pakiet SDK do reklam mobilnych Google w C++ kończy działanie firebase::Future zwracanego przez Initialize(), nawet jeśli sieć zapośredniczenia nie zakończyła jeszcze inicjowania.
Co się stanie, jeśli niektóre sieci zapośredniczenia nie będą gotowe, gdy otrzymam wywołanie zwrotne inicjowania?

Sprawdzoną metodą jest wczytywanie reklam po zakończeniu inicjowania pakietu SDK. Nawet jeśli sieć zapośredniczenia nie jest gotowa, pakiet SDK do reklam mobilnych Google w C++ i tak poprosi ją o reklamę. Jeśli więc sieć zapośredniczenia zakończy inicjowanie po upływie limitu czasu, nadal może obsługiwać przyszłe żądania reklamy w tej sesji.

Możesz nadal sprawdzać stan inicjowania wszystkich adapterów podczas sesji aplikacji, wywołując metodę GetInitializationStatus().

Jak sprawdzić, dlaczego dana sieć zapośredniczenia nie jest gotowa?

AdapterStatus.description() opisuje, dlaczego adapter nie jest gotowy do obsługi żądań reklamy. Przykład rejestrowania stanu adaptera zapośredniczenia znajdziesz w kodzie źródłowym naszej przykładowej aplikacji z krótkiego wprowadzenia na GitHubie.

Dodatkowe materiały

Przykład na GitHubie