Reklamy z nagrodą


Reklamy z nagrodą umożliwiają użytkownikom interakcję z reklamą w zamian za nagrody w aplikacji. Z tego przewodnika dowiesz się, jak zintegrować reklamy z nagrodą z aplikacjami na Androida i iOS za pomocą pakietu SDK do reklam mobilnych Google w języku C++.

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

Wymagania wstępne

Zawsze testuj reklamy za pomocą reklam testowych

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

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

  • 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

Oto główne kroki, które należy wykonać, aby zintegrować reklamy z nagrodą:

  1. Wczytaj reklamę.
  2. Rejestrowanie wywołań zwrotnych.
  3. Wyświetlanie reklamy i obsługa zdarzenia związanego z nagrodą.

Konfigurowanie RewardedAd

Reklamy z nagrodą są wyświetlane w obiektach RewardedAd, więc pierwszym krokiem do zintegrowania reklam z nagrodą z Twoją aplikacją jest utworzenie i inicjalizacja 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 wystąpienie RewardedAd, używając widoku nadrzędnego przekazanego do typu AdParent. Widok nadrzędny to odwołanie JNI jobject do obiektu Androida Activity lub wskaźnik do obiektu 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 inicjalizacji, wywołując funkcję InitializeLastResult() obiektu RewardedAd. Może to być przydatne do śledzenia procesu inicjalizacji 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 używaniu funkcji firebase::Future znajdziesz w artykule Używanie funkcji Futures do monitorowania stanu wykonania wywołań metod.

Wczytywanie reklamy

Wczytywanie reklamy odbywa się za pomocą metody LoadAd() obiektu RewardedAd. Metoda load wymaga zainicjowania obiektu RewardedAd, a także identyfikatora jednostki reklamowej i obiektu AdRequest. Zwracana jest wartość firebase::Future, za pomocą której można monitorować stan i wynik operacji wczytywania.

Poniższy kod pokazuje, jak załadować reklamę po pomyślnym zainicjowaniu obiektu 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, a także 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 to obiekt jednorazowego użytku. Oznacza to, że po wyświetleniu reklamy z nagrodą nie można jej wyświetlić ponownie. Najlepiej wczytywać kolejną reklamę z nagrodą za pomocą metody OnAdDismissedFullScreenContent() w Twoim FullScreenContentListener, aby następna reklama z nagrodą zaczęła się wczytywać, gdy tylko zamkniesz poprzednią.

Wyświetlanie reklamy i obsługa zdarzenia nagrody

Zanim zaczniesz wyświetlać użytkownikom reklamę z nagrodą, musisz umożliwić im wyraźny wybór treści reklamy z nagrodą w zamian za nagrodę. Reklamy z nagrodą muszą być zawsze opcjonalne.

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 w przypadku wywołania inicjującego występuje limit czasu?
Po 10 sekundach pakiet SDK do reklam mobilnych Google w języku C++ wykonuje funkcję firebase::Future zwracaną przez Initialize(), nawet jeśli sieć zapośredniczenia nie ukończyła jeszcze inicjalizacji.
Co się stanie, jeśli niektóre sieci pośredniczące nie będą gotowe, gdy otrzymam wywołanie zwrotne inicjalizowania?

Zalecamy wczytywanie reklam po zakończeniu inicjalizacji pakietu SDK. Nawet jeśli sieć zapośredniczenia nie jest gotowa, pakiet SDK do reklam mobilnych Google w języku C++ będzie nadal wysyłać do niej żądania reklamy. Jeśli sieć zapośredniczenia zakończy inicjowanie po upływie limitu czasu, nadal może obsługiwać kolejne żądania reklam w ramach tej sesji.

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

Jak sprawdzić, dlaczego dana sieć pośrednicząca nie jest gotowa?

AdapterStatus.description() wyjaśnia, dlaczego adapter nie jest gotowy do obsługi żądań reklam. Aby zobaczyć przykładowy kod źródłowy aplikacji krótkiego wprowadzenia na GitHubie, zapoznaj się z przykładem rejestrowania stanu pośrednika dostosowania reklam.

Dodatkowe materiały

Przykład w GitHubie