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


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

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

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

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

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

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

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

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

מידע נוסף על אופן הפעולה של מודעות בדיקה ב-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 באמצעות העברה של התצוגה הראשית (parent view) לסוג AdParent. התצוגה הראשית היא הפניה של JNI jobject ל-Activity של Android או מצביע ל-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. במקום לשמור את ה-future כמשתנה, אתם יכולים לבדוק מדי פעם את הסטטוס של פעולת האיניציאליזציה על ידי הפעלת 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, קראו את המאמר שימוש ב-Futures כדי לעקוב אחרי סטטוס ההשלמה של הפעלות method.

טעינת מודעה

כדי לטעון מודעה, משתמשים ב-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 באמצעות השיטה RewardedAd::SetFullScreenContentListener(), והיא תקבל קריאות חוזרות (callbacks) כשהמודעה תוצג בהצלחה או לא תוצג, וגם כשהיא תיסגר.

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

  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 הוא אובייקט לשימוש חד-פעמי. כלומר, אחרי שמציגים מודעה מתגמלת, אי אפשר להציג אותה שוב. מומלץ לטעון מודעה מתגמלת נוספת ב-method‏ 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(), גם אם רשת בתהליך בחירת הרשת עדיין לא השלימה את האתחול.
מה קורה אם חלק מהרשתות שמשתתפות בתהליך בחירת הרשת (Mediation) לא מוכנות כשאני מקבל/ת את הקריאה החוזרת (callback) של האתחול?

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

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

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

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

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

דוגמה ב-GitHub