Reklamy z nagrodą

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

Zapoznaj się z historiami sukcesu klientów: studium przypadku 1, studium przypadku 2.

Wymagania wstępne

Zawsze korzystaj z reklam testowych

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

Najprostszy sposób wczytywania reklam testowych to użycie dedykowanego testowego identyfikatora jednostki reklamowej na potrzeby 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 specjalnie skonfigurowane tak, by zwracały reklamy testowe w przypadku każdego żądania. Możesz ich używać we własnych 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 etapy integracji z reklamami z nagrodą:

  1. Wczytaj reklamę.
  2. Zarejestruj się na wywołania zwrotne.
  3. Wyświetl reklamę i obsługuje zdarzenie nagrody.

Skonfiguruj: RewardedAd

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

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

     #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ą rzutowania widoku nadrzędnego na typ AdParent. Widok nadrzędny to odniesienie jobject JNI do Activity lub wskaźnik do UIView 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 zachowania przyszłości jako zmiennej możesz okresowo sprawdzać stan operacji inicjowania, wywołując funkcję InitializeLastResult() w obiekcie RewardedAd. Może to pomóc w śledzeniu 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 o używaniu przyszłości do monitorowania stanu zakończenia wywołań metod.

Wczytywanie reklamy

Reklamę można wczytać za pomocą metody LoadAd() w obiekcie RewardedAd. Metoda wczytywania wymaga zainicjowania obiektu RewardedAd oraz posiadania identyfikatora jednostki reklamowej i obiektu AdRequest. Zwrócony zostanie firebase::Future, którego możesz używać do monitorowania stanu i wyniku operacji wczytywania.

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

Zarejestruj się na wywołania zwrotne

Aby otrzymywać powiadomienia o wyświetlaniu reklam z nagrodą i zdarzeniach cyklu życia, musisz rozszerzyć klasę FullScreenContentListener. Swoją niestandardową podklasę FullScreenContentListener możesz zarejestrować za pomocą metody RewardedAd::SetFullScreenContentListener() i będzie ona otrzymywać wywołania zwrotne, gdy reklama wyświetli się z powodzeniem lub niepowodzeniem, a także po jej odrzuceniu.

Ten kod pokazuje, jak rozszerzyć zajęcia i przypisać je 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 jednorazowy. Oznacza to, że po wyświetleniu reklamy z nagrodą nie można jej wyświetlić ponownie. Zalecamy wczytanie kolejnej reklamy z nagrodą za pomocą metody OnAdDismissedFullScreenContent() na koncie FullScreenContentListener, tak aby następna reklama z nagrodą zaczęła się wczytywać zaraz po odrzuceniu poprzedniej.

Wyświetl reklamę i obsługuj zdarzenie nagrody.

Przed wyświetleniem użytkownikom reklamy z nagrodą musisz dać im wyraźną zgodę na obejrzenie jej treści w zamian za nagrodę. Reklamy z nagrodą muszą być zawsze opcjonalne.

Gdy wyświetlasz reklamę, musisz podać obiekt UserEarnedReward do obsługi nagrody dla użytkownika.

Ten 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 istnieje limit czasu oczekiwania na wywołanie inicjujące?
Po 10 sekundach pakiet SDK do reklam mobilnych Google w C++ wykonuje zadanie firebase::Future zwrócone przez Initialize(), nawet jeśli sieć zapośredniczenia nie zakończyła jeszcze inicjalizacji.
Co zrobić, jeśli niektóre sieci zapośredniczenia nie są gotowe, gdy otrzymam wywołanie zwrotne inicjujące?

Sprawdzoną metodą jest wczytywanie reklam po zainicjowaniu pakietu SDK. Nawet jeśli sieć zapośredniczeń nie jest gotowa, pakiet SDK C++ do reklam mobilnych Google będzie nadal wysyłać do tej sieci żądanie reklamy. Jeśli więc sieć zapośredniczenia zakończy inicjowanie po upływie czasu oczekiwania, może nadal obsługiwać przyszłe żądania reklamy w tej sesji.

Możesz nadal przeprowadzać sondowanie stanu inicjowania wszystkich adapterów w trakcie sesji aplikacji, wywołując funkcję GetInitializationStatus().

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

Kolumna AdapterStatus.description() wyjaśnia, dlaczego adapter nie jest gotowy do obsługi żądań reklamy. Przykład logowania stanu adaptera zapośredniczenia znajdziesz w kodzie źródłowym przykładowej aplikacji z krótkim wprowadzeniem w GitHubie.

Dodatkowe materiały

Przykład w GitHubie