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

בחירת פלטפורמה: Android iOS Unity Flutter Android (גרסה קודמת)

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

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

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

לפני שממשיכים, צריך לבצע את הפעולות הבאות:

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

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

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

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

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

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

כדי להתחיל לטעון מראש מודעות, צריך להפעיל את השיטה start פעם אחת כשמאתחלים את GMA Next-Gen SDK. אחרי שמפעילים את השיטה 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)
  RewardedInterstitialAdPreloader.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);
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig);
}

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

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

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

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

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

כשיש אובייקט מודעה זמין, קוראים ל-method‏ 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());
      });
}

כשהאפליקציה מגיעה למיקום מודעה ויכולה להפעיל את ה-method‏ show, מפעילים את ה-method‏ pollAd. אל תפעילו את ה-method‏ pollAd בקריאות חוזרות (callbacks) של טעינה מראש או אחרי בדיקה של ה-method‏ isAdAvailable כדי להשהות מודעה. אם אתם צריכים לבדוק את המטא-נתונים של המודעה לפני שהיא מוצגת, קראו את פרטי התגובה בלי להסיר את המודעה מהמטמון.

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

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

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

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

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

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

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

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 בנתונים בהתאמה אישית.

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

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

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

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

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 טוען מראש מודעות באופן אוטומטי ומנסה שוב לשלוח בקשות שנכשלו להגדרות שנטענו מראש. אל תפעילו בקשות טעינה ידניות בקריאות חוזרות (callback) של כשלים. בשיטות קריאה חוזרת של אירועי טעינה מראש, אל תקראו לשיטות pollAd,‏ destroy או start. קריאה לשיטות האלה בקריאות חוזרות (callbacks) יכולה להפעיל לולאות טעינה רקורסיביות.

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

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

Kotlin

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

Java

private boolean isAdAvailable(String adUnitId) {
  return RewardedInterstitialAdPreloader.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)
  RewardedInterstitialAdPreloader.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);
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig);
}

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

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

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

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

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

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

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

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

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());