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


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

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

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

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

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

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

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

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

דוגמה ב-GitHub