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

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

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

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

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

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

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

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

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

אפשר לקרוא מידע נוסף על אופן הפעולה של מודעות בדיקה ב-Mobile Ads SDK במאמר מודעות בדיקה.

הטמעה

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

  1. טוענים מודעה.
  2. הרשמה לקריאה חוזרת (callback).
  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 ל-Activity Android או מצביע אל 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 זמין במאמר שימוש בחוזים עתידיים למעקב אחר סטטוס ההשלמה של קריאות לשיטה.

טעינת מודעה

טעינת מודעה מתבצעת באמצעות השיטה 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);

הרשמה לקריאה חוזרת (callback)

עליכם להאריך את הכיתה FullScreenContentListener כדי לקבל התראות על הצגת מודעות מתגמלות ועל אירועים במחזור החיים. ניתן לרשום את מחלקת המשנה המותאמת אישית FullScreenContentListener באמצעות שיטת 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 שניות, מערכת Google Mobile Ads C++ SDK משלימה את פעולת ה-firebase::Future שמוחזרת על ידי Initialize(), גם אם האתחול של רשת בתהליך בחירת הרשת עדיין לא השלימה.
מה קורה אם רשתות מסוימות בתהליך בחירת הרשת לא מוכנות אחרי שאקבל את הקריאה החוזרת מהאתחול?

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

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

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

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

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

דוגמאות ב-GitHub