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


מודעות מתגמלות מאפשרות למשתמשים לבחור אם ליצור איתן אינטראקציה בתמורה לתגמולים בתוך האפליקציה. במדריך הזה מוסבר איך לשלב מודעות מתגמלות באפליקציות ל-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. התצוגה של ההורה היא הפניה ל-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. האפשרות הזו יכולה לעזור לכם לעקוב אחרי תהליך האתחול בלולאת המשחק הגלובלית.

    // 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 כדי לעקוב אחרי סטטוס השלמת הקריאות לשיטות.

טעינת מודעה

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

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

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

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

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

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

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

דוגמה ב-GitHub