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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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