הגדרת מודעות מתגמלות

בחירת פלטפורמה: Android iOS Unity Flutter Android (Legacy)

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

במדריך הזה מוסבר איך לשלב מודעות מתגמלות באפליקציית Android.

לפני שמתחילים

לפני שממשיכים, צריך:

  • הגדרה של GMA Next-Gen SDK
  • משתמשים במזהה יחידת המודעות המתגמלות לבדיקה ca-app-pub-3940256099942544/5224354917.
    • כשמפתחים את האפליקציה ובודקים אותה, חשוב להשתמש במודעות בדיקה ולא במודעות פעילות לפרסום מוצרים. אם לא תשתמשו במזהה יחידת המודעות לבדיקה, Google עשויה להשעות את החשבון שלכם.
    • לפני שמפרסמים את האפליקציה, מחליפים את המזהה הזה במזהה של יחידת המודעות.
    • פרטים על GMA Next-Gen SDK מודעות בדיקה זמינים במאמר הפעלת מודעות בדיקה.

הסבר על טעינת מודעות מראש (בטא)

טעינה מראש של מודעות (בטא) ב-GMA Next-Gen SDK מאפשרת לטעון מודעות ולשמור אותן במטמון באופן אוטומטי.

טעינה מראש של מודעות מספקת את היתרונות הבאים:

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

התחלת טעינת מודעה מראש

כדי להתחיל בטעינה מראש של מודעות, קוראים לשיטה startPreload() פעם אחת בתחילת האפליקציה. אחרי שמפעילים את השיטה startPreload(), המודעות נטענות מראש באופן אוטומטי, ומערכת GMA Next-Gen SDK מנסה שוב בקשות שנכשלו להגדרות שנטענו מראש.

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

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedAdPreloader.start(adUnitId, preloadConfig)

Java

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedAdPreloader.start(adUnitId, preloadConfig);

מחליפים את AD_UNIT_ID במזהה יחידת המודעות.

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

אחזור והצגה של המודעה שנטענה מראש

כשרוצים להציג מודעה, מפעילים את method‏ pollAd(). ‫GMA Next-Gen SDK מאחזרת מודעה זמינה וטוענת מראש באופן אוטומטי את המודעה הבאה ברקע. אם אין מודעות זמינות, הפונקציה GMA Next-Gen SDK לא מחזירה מודעות.

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

Kotlin

private fun pollAndShowAd(activity: Activity, adUnitId: String) {
  // Polling returns the next available ad and loads another ad in the background.
  val ad = RewardedAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Rewarded ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Rewarded ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : RewardedAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Rewarded ad recorded an impression.")
      }
    }
  ad.show(activity) { rewardItem -> Log.d(TAG, "User earned reward: ${rewardItem.amount}") }
}

Java

private void pollAndShowAd(Activity activity, String adUnitId) {
  // Polling returns the next available ad and loads another ad in the background.
  final RewardedAd ad = RewardedAdPreloader.pollAd(adUnitId);

  // Interact with the ad object as needed.
  if (ad == null) {
    Log.e(TAG, "Rewarded ad is not available.");
    return;
  }

  Log.d(TAG, "Rewarded ad response info: " + ad.getResponseInfo());
  ad.setAdEventCallback(
      new RewardedAdEventCallback() {
        @Override
        public void onAdImpression() {
          Log.d(TAG, "Rewarded ad recorded an impression.");
        }
      });

  // Show the ad.
  ad.show(
      activity,
      rewardItem -> {
        Log.d(TAG, "User earned reward: " + rewardItem.getAmount());
      });
}

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

האזנה לאירועים של מודעות

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

Kotlin

private fun listenToAdEvents() {
  // Listen for ad events.
  val ad = rewardedAd
  if (ad == null) {
    Log.e(TAG, "Rewarded ad is not ready yet.")
    return
  }

  ad.adEventCallback =
    object : RewardedAdEventCallback {
      override fun onAdShowedFullScreenContent() {
        // Rewarded ad did show.
      }

      override fun onAdDismissedFullScreenContent() {
        // Rewarded ad did dismiss.
        rewardedAd = null
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError
      ) {
        // Rewarded ad failed to show.
        Log.e(TAG, "Rewarded ad failed to show: ${fullScreenContentError.message}")
      }

      override fun onAdImpression() {
        // Rewarded ad did record an impression.
      }

      override fun onAdClicked() {
        // Rewarded ad did record a click.
      }
    }
}

Java

private void listenToAdEvents() {
  // Listen for ad events.
  if (rewardedAd == null) {
    Log.e(TAG, "Rewarded ad is not ready yet.");
    return;
  }

  rewardedAd.setAdEventCallback(
      new RewardedAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded ad did show.
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          // Rewarded ad did dismiss.
          rewardedAd = null;
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            FullScreenContentError fullScreenContentError) {
          // Rewarded ad failed to show.
          Log.e(TAG, "Rewarded ad failed to show: " + fullScreenContentError.getMessage());
        }

        @Override
        public void onAdImpression() {
          // Rewarded ad did record an impression.
        }

        @Override
        public void onAdClicked() {
          // Rewarded ad did record a click.
        }
      });
}

אופציונלי: אימות קריאות חוזרות של אימות בצד השרת (SSV)

אם האפליקציה דורשת נתונים נוספים בקריאות חוזרות (callback) של אימות בצד השרת (SSV), צריך להשתמש בתכונה 'נתונים מותאמים אישית' של מודעות מתגמלות. כל ערך מחרוזת שמוגדר באובייקט של מודעה מתגמלת מועבר לפרמטר השאילתה custom_data של הקריאה החוזרת ל-SSV. אם לא מוגדר ערך של נתונים מותאמים אישית, ערך פרמטר השאילתה custom_data לא ייכלל בקריאה החוזרת ל-SSV.

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

Kotlin

RewardedAd.load(
  context,
  AD_UNIT_ID,
  AdRequest.Builder().build(),
  object : RewardedAdLoadCallback() {
    override fun onAdLoaded(ad: RewardedAd) {
      rewardedAd = ad
      val options =
        ServerSideVerificationOptions.Builder().setCustomData("SAMPLE_CUSTOM_DATA_STRING").build()
      rewardedAd?.setServerSideVerificationOptions(options)
    }
  },
)

Java

RewardedAd.load(
    context,
    AD_UNIT_ID,
    new AdRequest.Builder().build(),
    new RewardedAdLoadCallback() {
      @Override
      public void onAdLoaded(RewardedAd ad) {
        rewardedAd = ad;
        ServerSideVerificationOptions options =
            new ServerSideVerificationOptions.Builder()
                .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
                .build();
        rewardedAd.setServerSideVerificationOptions(options);
      }
    });

מחליפים את SAMPLE_CUSTOM_DATA_STRING בנתונים המותאמים אישית.

אופציונלי: המתנה לאירועים של טעינה מראש

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

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

Kotlin

val preloadCallback =
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(TAG, "Rewarded preload ad $preloadId failed to load with error: ${adError.message}")
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Rewarded preload ad $preloadId is not available")
    }

    override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo) {
      Log.i(TAG, "Rewarded preload ad $preloadId is available")
    }
  }
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedAdPreloader.start(adUnitId, preloadConfig, preloadCallback)

Java

PreloadCallback preloadCallback =
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(String preloadId, LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Rewarded preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
      }

      @Override
      public void onAdsExhausted(String preloadId) {
        Log.i(TAG, "Rewarded preload ad " + preloadId + " is not available");
      }

      @Override
      public void onAdPreloaded(String preloadId, ResponseInfo responseInfo) {
        Log.i(TAG, "Rewarded preload ad " + preloadId + " is available");
      }
    };

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

כשמודעה לא נטענת, GMA Next-Gen SDK טוען מראש מודעות באופן אוטומטי ומנסה שוב בקשות שנכשלו להגדרות שנטענו מראש.

אופציונלי: בדיקה אם יש מודעות זמינות

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

Kotlin

private fun isAdAvailable(adUnitId: String): Boolean {
  return RewardedAdPreloader.isAdAvailable(adUnitId)
}

Java

private boolean isAdAvailable(String adUnitId) {
  return RewardedAdPreloader.isAdAvailable(adUnitId);
}

אופציונלי: הגדרת גודל מאגר הנתונים הזמני

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

בדוגמה הבאה אפשר לראות איך מגדירים גודל מאגר של שתי מודעות שנטענו מראש:

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
RewardedAdPreloader.start(adUnitId, preloadConfig)

Java

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 2);
RewardedAdPreloader.start(adUnitId, preloadConfig);

מגבלות על טעינה מראש של מטמון

‫GMA Next-Gen SDK אוכף מגבלה ברמת האפליקציה על המספר הכולל של מודעות שנטענו מראש בכל יחידות המודעות ובכל מזהי הטעינה מראש:

  • מגבלת ברירת מחדל: Google שומרת בזיכרון עד שש מודעות שנטענו מראש. המגבלה הזו משותפת לכל הפורמטים ולכל מזהי הטעינה מראש.
  • מומלץ להגדיר שטח אחסון זמני של שניים לכל מזהה טעינה מראש.

אופציונלי: הפסקת הטעינה מראש של מודעות

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

בדוגמה הבאה אפשר לראות איך מפסיקים את הטעינה מראש של מודעות:

Kotlin

private fun stopPreloading(adUnitId: String) {
  // Stops the preloading and destroy preloaded ads.
  RewardedAdPreloader.destroy(adUnitId)
}

Java

private void stopPreloading(String adUnitId) {
  // Stops the preloading and destroy preloaded ads.
  RewardedAdPreloader.destroy(adUnitId);
}

אופציונלי: קוראים את פרטי התשובה

קריאת פרטי התגובה של המודעה הבאה שנטענה מראש בלי להסיר את המודעה מהמטמון.

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

Kotlin

val responseInfo = RewardedAdPreloader.peekAdResponseInfo(preloadId)
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.")
  return
}

Log.d(TAG, "Peeked ad response ID: ${responseInfo.responseId}")

Java

ResponseInfo responseInfo = RewardedAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

Log.d(TAG, "Peeked ad response ID: " + responseInfo.getResponseId());