מודעות מתגמלות

מודעות מתגמלות מאפשרות למשתמשים ליצור איתן אינטראקציה בתמורה לפרסים מתוך האפליקציה. המדריך הזה מסביר איך לשלב מודעות מתגמלות באפליקציות ל-Android ול-iOS באמצעות SDK C++ של מודעות Google לנייד.

קראו כמה סיפורי הצלחה של לקוחות: מקרה לדוגמה 1, מקרה לדוגמה 2.

דרישות מוקדמות

ביצוע בדיקות תמיד באמצעות מודעות בדיקה

כשאתם יוצרים ובודקים את האפליקציות, הקפידו להשתמש במודעות בדיקה ולא במודעות פעילות בשלב ההפקה. אחרת, ייתכן שהחשבון יושעה.

הדרך הקלה ביותר לטעון מודעות בדיקה היא באמצעות מזהה יחידת מודעות לבדיקה הייעודי שלנו למודעות מתגמלות. המזהה משתנה בהתאם לפלטפורמת מכשיר:

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

הן הוגדרו במיוחד להצגת מודעות בדיקה לכל בקשה, ואפשר להשתמש בהן באפליקציות שלכם בזמן תכנות, בדיקה וניפוי באגים. הקפידו להחליף אותה במזהה יחידת המודעות שלכם לפני פרסום האפליקציה.

רוצים לדעת איך פועלות מודעות הבדיקה של Mobile Ads SDK? קראו את המאמר מודעות בדיקה.

הטמעה

השלבים העיקריים לשילוב מודעות מתגמלות הם:

  1. לטעון מודעה.
  2. הרשמה לשיחות חוזרות.
  3. הצגת המודעה וטיפול באירוע התגמול.

הגדרת RewardedAd

מודעות מתגמלות מוצגות באובייקטים של RewardedAd, כך שהשלב הראשון לקראת שילוב מודעות מתגמלות באפליקציה הוא ליצור ולהפעיל מכונה של RewardedAd.

  1. מוסיפים את הכותרת הבאה לקוד C++ של האפליקציה: 

     #include "firebase/gma/rewarded_ad.h"

  2. מצהירים ויוצרים אובייקט RewardedAd: 

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

  3. מפעילים את המכונה RewardedAd באמצעות ההעברה של תצוגת ההורה לסוג AdParent. תצוגת ההורה היא הפניה של JNI jobject אל Android Activity או מצביע אל 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. במקום לשמור את העתיד כמשתנה, אפשר לבדוק מדי פעם את הסטטוס של פעולת האתחול על ידי הפעלת InitializeLastResult() באובייקט RewardedAd. המידע הזה יכול לעזור לכם לעקוב אחרי תהליך האתחול ב-game loop הגלובלי.

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

מידע נוסף על עבודה עם firebase::Future זמין במאמר Use Futures כדי לעקוב אחר סטטוס ההשלמה של קריאות method.

טעינת מודעה

טעינת מודעה מתבצעת באמצעות השיטה LoadAd() באובייקט RewardedAd. לפי שיטת הטעינה, צריך להפעיל את האובייקט RewardedAd ולציין את מזהה יחידת המודעות ואובייקט AdRequest. מוחזר firebase::Future, וניתן להשתמש בו כדי לעקוב אחרי המצב והתוצאות של פעולת העומס.

הקוד הבא מראה איך לטעון מודעה אחרי ההפעלה של 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);

הרשמה לשיחות חוזרות

צריך להאריך את הכיתה FullScreenContentListener כדי לקבל התראות על הצגת מודעות מתגמלות ואירועים במחזור החיים. אפשר לרשום את מחלקה משנית (FullScreenContentListener) בהתאמה אישית באמצעות method RewardedAd::SetFullScreenContentListener(). כשהמודעה מוצגת בהצלחה או נכשלת, גם כשהיא נסגרת, היא מקבלת קריאות חוזרות (callback).

הקוד הבא מראה איך להרחיב את הכיתה ולהקצות אותה למודעה:

  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 הוא אובייקט חד-פעמי. המשמעות היא שברגע שמודעה מתגמלת מוצגת, אי אפשר להציג אותה שוב. השיטה המומלצת היא לטעון מודעה מתגמלת אחרת בשיטה OnAdDismissedFullScreenContent() של FullScreenContentListener, כדי שהמודעה המתגמלת הבאה תתחיל להיטען ברגע שהמודעה המתגמלת הבאה תיסגר.

הצגת המודעה וטיפול באירוע הפרס

לפני ההצגה של מודעה מתגמלת למשתמשים, עליכם להציג להם בחירה מפורשת לצפות בתוכן של מודעה מתגמלת בתמורה לתגמול. מודעות מתגמלות צריכות תמיד להביע הסכמה.

כשמציגים את המודעה, צריך לספק אובייקט UserEarnedReward שיטפל בתגמול של המשתמש.

הקוד הבא מראה איך להציג 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);

שאלות נפוצות

האם יש זמן קצוב לתפוגה של קריאת האתחול?
אחרי 10 שניות, ערכת C++ SDK של Google Mobile Ads משלימה את firebase::Future שהוחזר על ידי Initialize(), גם אם הרשת שבה נערך תהליך בחירת הרשת עדיין לא השלימה את האתחול.
מה קורה אם רשתות מסוימות בתהליך בחירת הרשת לא מוכנות לאחר קבלת הקריאה החוזרת לאתחול?

מומלץ לטעון מודעות לאחר השלמת אתחול ה-SDK. גם אם רשת בתהליך בחירת הרשת אינה מוכנה, ערכת C++ SDK של Google Mobile Ads עדיין תבקש מהרשת הזו להציג מודעה. כך, אם רשת בתהליך בחירת הרשת מסיימת לפעול לאחר הזמן הקצוב לתפוגה, היא עדיין יכולה לטפל בבקשות עתידיות להצגת מודעות באותו סשן.

כדי לדגום את סטטוס האתחול של כל המתאמים במהלך הפעלת האפליקציה, ניתן להתקשר אל GetInitializationStatus().

איך אפשר לברר למה רשת מסוימת שבה נערך תהליך בחירת הרשת לא מוכנה?

בAdapterStatus.description() מוסבר למה מתאם לא מוכן לטפל בבקשות למודעות. עיינו בקוד המקור של האפליקציה לדוגמה למתחילים ב-GitHub כדי לראות דוגמה לרישום הסטטוס של המתאם בתהליך בחירת הרשת.

מקורות מידע נוספים

דוגמה ב-GitHub