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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Kotlin

private fun startPreloading(adUnitId: String) {
  // 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)
  InterstitialAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void startPreloading(String adUnitId) {
  // 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);
  InterstitialAdPreloader.start(adUnitId, preloadConfig);
}

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

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

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

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

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

Kotlin

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

  // Interact with the ad object as needed.
  Log.d(TAG, "Interstitial ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : InterstitialAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Interstitial ad recorded an impression.")
      }
    }
  ad.show(activity)
}

Java

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

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

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

  // Show the ad.
  ad.show(activity);
}

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

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

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

Kotlin

// Listen for ad events.
val ad = interstitialAd
if (ad == null) {
  Log.e(TAG, "Interstitial ad is not ready yet.")
  return
}

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

    override fun onAdDismissedFullScreenContent() {
      // Interstitial ad did dismiss.
      interstitialAd = null
    }

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

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

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

Java

// Listen for ad events.
if (interstitialAd == null) {
  Log.e(TAG, "Interstitial ad is not ready yet.");
  return;
}

interstitialAd.setAdEventCallback(
    new InterstitialAdEventCallback() {
      @Override
      public void onAdShowedFullScreenContent() {
        // Interstitial ad did show.
      }

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

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

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

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

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

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

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

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,
        ("Interstitial preload ad $preloadId failed to load with error: ${adError.message}"),
      )
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "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, "Interstitial preload ad $preloadId is available")
    }
  }
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
InterstitialAdPreloader.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(
                "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, "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, "Interstitial preload ad " + preloadId + " is available");
      }
    };

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

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

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

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

Kotlin

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

Java

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

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

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

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

Kotlin

private fun setBufferSize(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  // Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
  val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
  InterstitialAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void setBufferSize(String adUnitId) {
  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);
  InterstitialAdPreloader.start(adUnitId, preloadConfig);
}

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

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

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

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

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

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

Kotlin

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

Java

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

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

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

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

Kotlin

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

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