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

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

דרישות מוקדמות

הגדרה של GMA Next-Gen SDK

תמיד כדאי לבצע בדיקות באמצעות מודעות בדיקה

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

הדרך הכי קלה לטעון מודעות בדיקה היא להשתמש במזהה יחידת המודעות הייעודי לבדיקה של מודעות מתגמלות ל-Android:

ca-app-pub-3940256099942544/5224354917

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

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

טעינת מודעה

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

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

Kotlin

// Load ads after you initialize MobileAds.
RewardedAd.load(
  AdRequest.Builder(adUnitId).build(),
  object : AdLoadCallback<RewardedAd> {
    override fun onAdLoaded(ad: RewardedAd) {
      // Rewarded ad loaded.
      rewardedAd = ad
    }

    override fun onAdFailedToLoad(adError: LoadAdError) {
      // Rewarded ad failed to load.
      Log.e(TAG, "Rewarded ad failed to load: ${adError.message}")
      rewardedAd = null
    }
  },
)

Java

// Load ads after you initialize MobileAds.
RewardedAd.load(
    new AdRequest.Builder(adUnitId).build(),
    new AdLoadCallback<RewardedAd>() {
      @Override
      public void onAdLoaded(@NonNull RewardedAd ad) {
        // Rewarded ad loaded.
        rewardedAd = ad;
      }

      @Override
      public void onAdFailedToLoad(@NonNull LoadAdError adError) {
        // Rewarded ad failed to load.
        Log.e(TAG, "Rewarded ad failed to load: " + adError.getMessage());
        rewardedAd = null;
      }
    });

במהלך הבדיקה, צריך להשתמש במזהה יחידת מודעות ייעודית לבדיקה: ca-app-pub-3940256099942544/5224354917.

הצגת המודעה

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

Kotlin

private fun showAd(rewardedAd: RewardedAd, activity: Activity) {
  // Show the ad.
  rewardedAd.show(
    activity,
    object : OnUserEarnedRewardListener {
      override fun onUserEarnedReward(rewardItem: RewardItem) {
        // User earned the reward.
        val rewardAmount = rewardItem.amount
        val rewardType = rewardItem.type
      }
    },
  )
}

Java

private void showAd(RewardedAd rewardedAd, Activity activity) {
  // Show the ad.
  rewardedAd.show(
      activity,
      new OnUserEarnedRewardListener() {
        @Override
        public void onUserEarnedReward(@NonNull RewardItem rewardItem) {
          // User earned the reward.
          int rewardAmount = rewardItem.getAmount();
          String rewardType = rewardItem.getType();
        }
      });
}

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

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

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

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

נקודה חשובה: מחרוזת התגמול בהתאמה אישית כוללת תו בריחה (escape) באחוזים. יכול להיות שתצטרכו לפענח את מחרוזת התגמול בהתאמה אישית כדי לחלץ אותה מהקריאה החוזרת של SSV.