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 iOS przy użyciu pakietu SDK do reklam mobilnych Google w C++.

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

Wymagania wstępne

Zawsze testuj za pomocą reklam testowych

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

Najłatwiejszym sposobem wczytywania reklam testowych jest użycie specjalnego identyfikatora jednostki reklamowej testowej w przypadku 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ć w swoich aplikacjach podczas kodowania, testowania i debugowania. Pamiętaj tylko, aby przed opublikowaniem aplikacji zastąpić go własnym identyfikatorem jednostki reklamowej.

Więcej informacji o działaniu reklam testowych w pakiecie SDK do reklam mobilnych znajdziesz w artykule Reklamy testowe.

Implementacja

Główne etapy integracji reklam z nagrodą to:

  1. Wczytaj reklamę.
  2. Zarejestruj wywołania zwrotne.
  3. Wyświetl reklamę i obsłuż zdarzenie nagrody.

Konfigurowanie RewardedAd

Reklamy z nagrodą są wyświetlane w obiektach RewardedAd, więc pierwszym krokiem do zintegrowania ich 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 za pomocą widoku nadrzędnego przekształconego w typ AdParent. Widok nadrzędny to odwołanie JNI jobject do elementu Android Activity lub wskaźnik do elementu 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. Zamiast przechowywać przyszłość jako zmienną, możesz okresowo sprawdzać stan operacji inicjowania, wywołując 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 pracy z firebase::Future znajdziesz w artykule Monitorowanie stanu zakończenia wywołań metod za pomocą obiektów Futures.

Wczytywanie reklamy

Wczytywanie reklamy odbywa się za pomocą metody LoadAd() w obiekcie RewardedAd. Metoda load wymaga zainicjowania obiektu RewardedAd oraz podania identyfikatora jednostki reklamowej i obiektu AdRequest. Zwracana jest wartość A firebase::Future, której możesz użyć do monitorowania stanu i wyniku operacji wczytywania.

Poniższy kod pokazuje, jak wczytać reklamę po prawidłowym 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 (z powodzeniem lub bez powodzenia) 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 ponownie wyświetlić. Zalecamy wczytywanie kolejnej reklamy z nagrodą w metodzie OnAdDismissedFullScreenContent()FullScreenContentListener, aby następna reklama z nagrodą zaczęła się wczytywać od razu po zamknięciu poprzedniej.

Wyświetlanie reklamy i obsługa zdarzenia związanego z nagrodą

Zanim zaczniesz wyświetlać użytkownikom reklamę z nagrodą, musisz dać im możliwość wyrażenia zgody na obejrzenie treści reklamy z nagrodą w zamian za nagrodę. Reklamy z nagrodą zawsze muszą być wyświetlane po wyrażeniu zgody przez użytkownika.

Podczas wyświetlania reklamy musisz podać obiekt UserEarnedReward, który będzie obsługiwać nagrodę dla użytkownika.

Poniższy kod pokazuje, jak wyświetlić element 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 połączenie inicjujące ma limit czasu?
Po 10 sekundach pakiet SDK do reklam mobilnych Google w C++ kończy działanie funkcji firebase::Future zwróconej przez Initialize(), nawet jeśli sieć zapośredniczenia nie zakończyła jeszcze inicjowania.
Co się stanie, jeśli niektóre sieci mediacji nie będą gotowe, gdy otrzymam wywołanie zwrotne inicjowania?

Zalecamy 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++ nadal będzie wysyłać do niej żądanie reklamy. Jeśli więc sieć zapośredniczenia zakończy inicjowanie po upływie limitu czasu, nadal może obsługiwać przyszłe żądania reklam w tej sesji.

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

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

AdapterStatus.description() wyjaśnia, dlaczego adapter nie jest gotowy do obsługi żądań reklam. Przykład logowania stanu adaptera do mediacji znajdziesz w kodzie źródłowym naszej przykładowej aplikacji do szybkiego rozpoczęcia w GitHubie.

Dodatkowe materiały

Przykład w GitHubie