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

‫Next-Gen SDK.

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

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

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

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

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

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

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

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

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

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

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

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

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

Kotlin

// Call start() once after SDK initialization.
// Preload only one ad unit per format to optimize performance.
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)

Java

// Call start() once after SDK initialization.
// Preload only one ad unit per format to optimize performance.
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedInterstitialAdPreloader.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 = RewardedInterstitialAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Rewarded interstitial ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : RewardedInterstitialAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Rewarded interstitial 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 RewardedInterstitialAd ad = RewardedInterstitialAdPreloader.pollAd(adUnitId);

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

  Log.d(TAG, "Rewarded interstitial ad response info: " + ad.getResponseInfo());
  ad.setAdEventCallback(
      new RewardedInterstitialAdEventCallback() {
        @Override
        public void onAdImpression() {
          Log.d(TAG, "Rewarded interstitial 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 = rewardedInterstitialAd
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not ready yet.")
    return
  }

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

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

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

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

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

Java

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

  rewardedInterstitialAd.setAdEventCallback(
      new RewardedInterstitialAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded interstitial ad did show.
        }

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

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

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

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

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

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

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

Kotlin

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

Java

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

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

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

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

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

Kotlin

val preloadCallback =
  // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(
        TAG,
        "Rewarded interstitial preload ad $preloadId failed to load with error: ${adError.message}",
      )
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Rewarded interstitial preload ad $preloadId is not available")
      // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
    }

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

Java

PreloadCallback preloadCallback =
    // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(@NonNull String preloadId, @NonNull LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Rewarded interstitial preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
        // [Optional] Get the error response info for additional details.
        // ResponseInfo responseInfo = adError.getResponseInfo();
      }

      @Override
      public void onAdsExhausted(@NonNull String preloadId) {
        Log.i(TAG, "Rewarded interstitial preload ad " + preloadId + " is not available");
        // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
      }

      @Override
      public void onAdPreloaded(@NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
        Log.i(TAG, "Rewarded interstitial preload ad " + preloadId + " is available");
      }
    };
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

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

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

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

Kotlin

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

Java

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

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

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

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

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
// Maintain small or default buffer size unless rapid transitions are expected.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 4)
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)

Java

// Maintain small or default buffer size unless rapid transitions are expected.
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 4);
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig);

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

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

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

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

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

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

Kotlin

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

Java

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

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

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

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

Kotlin

val responseInfo = RewardedInterstitialAdPreloader.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 = RewardedInterstitialAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

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