מודעות מתגמלות

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

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

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

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

ca-app-pub-3940256099942544/5224354917

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

מידע נוסף על אופן הפעולה של מודעות הבדיקה של Mobile Ads SDK זמין במאמר מודעות בדיקה.

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

טעינת המודעות המתגמלות מתבצעת באמצעות השיטה load() הסטטית בכיתה RewardedAd ומעבירה את התיבה RewardedAdLoadCallback. הפעולה הזו מתבצעת בדרך כלל בשיטה onCreate() של Activity. שימו לב: בדומה לקריאות חוזרות (callback) בפורמט אחר, RewardedAdLoadCallback משתמשת ב-LoadAdError כדי להציג פרטי שגיאות באיכות גבוהה יותר.

Java

import com.google.android.gms.ads.rewarded.RewardedAd;

public class MainActivity extends Activity {
  private RewardedAd rewardedAd;
  private final String TAG = "MainActivity";

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    AdRequest adRequest = new AdRequest.Builder().build();
    RewardedAd.load(this, "ca-app-pub-3940256099942544/5224354917",
      adRequest, new RewardedAdLoadCallback() {
        @Override
        public void onAdFailedToLoad(@NonNull LoadAdError loadAdError) {
          // Handle the error.
          Log.d(TAG, loadAdError.toString());
          rewardedAd = null;
        }

        @Override
        public void onAdLoaded(@NonNull RewardedAd ad) {
          rewardedAd = ad;
          Log.d(TAG, "Ad was loaded.");
        }
    });
  }
}

Kotlin

class MainActivity : AppCompatActivity() {

  private var rewardedAd: RewardedAd? = null
  private final var TAG = "MainActivity"

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)
    var adRequest = AdRequest.Builder().build()
    RewardedAd.load(this,"ca-app-pub-3940256099942544/5224354917", adRequest, object : RewardedAdLoadCallback() {
      override fun onAdFailedToLoad(adError: LoadAdError) {
        Log.d(TAG, adError?.toString())
        rewardedAd = null
      }

      override fun onAdLoaded(ad: RewardedAd) {
        Log.d(TAG, "Ad was loaded.")
        rewardedAd = ad
       }
    })
  }
}

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

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

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

Java

RewardedAd.load(MainActivity.this, "ca-app-pub-3940256099942544/5354046379",
    new AdRequest.Builder().build(),  new RewardedAdLoadCallback() {
  @Override
  public void onAdLoaded(RewardedAd ad) {
    Log.d(TAG, "Ad was loaded.");
    rewardedAd = ad;
    ServerSideVerificationOptions options = new ServerSideVerificationOptions
        .Builder()
        .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
        .build();
    rewardedAd.setServerSideVerificationOptions(options);
  }
  @Override
  public void onAdFailedToLoad(LoadAdError loadAdError) {
      Log.d(TAG, loadAdError.toString());
      rewardedAd = null;
  }
});

Kotlin

RewardedAd.load(this, "ca-app-pub-3940256099942544/5354046379",
    AdRequest.Builder().build(), object : RewardedAdLoadCallback() {
  override fun onAdLoaded(ad: RewardedAd) {
    Log.d(TAG, "Ad was loaded.")
    rewardedInterstitialAd = ad
    val options = ServerSideVerificationOptions.Builder()
        .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
        .build()
    rewardedAd.setServerSideVerificationOptions(options)
  }

  override fun onAdFailedToLoad(adError: LoadAdError) {
      Log.d(TAG, adError?.toString())
      rewardedAd = null
  }
})

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

הגדרת הקריאה המלאה למסך התוכן

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

Java

rewardedAd.setFullScreenContentCallback(new FullScreenContentCallback() {
  @Override
  public void onAdClicked() {
    // Called when a click is recorded for an ad.
    Log.d(TAG, "Ad was clicked.");
  }

   @Override
  public void onAdDismissedFullScreenContent() {
    // Called when ad is dismissed.
    // Set the ad reference to null so you don't show the ad a second time.
    Log.d(TAG, "Ad dismissed fullscreen content.");
    rewardedAd = null;
  }

  @Override
  public void onAdFailedToShowFullScreenContent(AdError adError) {
    // Called when ad fails to show.
    Log.e(TAG, "Ad failed to show fullscreen content.");
    rewardedAd = null;
  }

  @Override
  public void onAdImpression() {
    // Called when an impression is recorded for an ad.
    Log.d(TAG, "Ad recorded an impression.");
  }

  @Override
  public void onAdShowedFullScreenContent() {
    // Called when ad is shown.
    Log.d(TAG, "Ad showed fullscreen content.");
  }
});

Kotlin

rewardedAd?.fullScreenContentCallback = object: FullScreenContentCallback() {
  override fun onAdClicked() {
    // Called when a click is recorded for an ad.
    Log.d(TAG, "Ad was clicked.")
  }

  override fun onAdDismissedFullScreenContent() {
    // Called when ad is dismissed.
    // Set the ad reference to null so you don't show the ad a second time.
    Log.d(TAG, "Ad dismissed fullscreen content.")
    rewardedAd = null
  }

  override fun onAdFailedToShowFullScreenContent(adError: AdError?) {
    // Called when ad fails to show.
    Log.e(TAG, "Ad failed to show fullscreen content.")
    rewardedAd = null
  }

  override fun onAdImpression() {
    // Called when an impression is recorded for an ad.
    Log.d(TAG, "Ad recorded an impression.")
  }

  override fun onAdShowedFullScreenContent() {
    // Called when ad is shown.
    Log.d(TAG, "Ad showed fullscreen content.")
  }
}

הצגת המודעה

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

Java

if (rewardedAd != null) {
  Activity activityContext = MainActivity.this;
  rewardedAd.show(activityContext, new OnUserEarnedRewardListener() {
    @Override
    public void onUserEarnedReward(@NonNull RewardItem rewardItem) {
      // Handle the reward.
      Log.d(TAG, "The user earned the reward.");
      int rewardAmount = rewardItem.getAmount();
      String rewardType = rewardItem.getType();
    }
  });
} else {
  Log.d(TAG, "The rewarded ad wasn't ready yet.");
}

Kotlin

rewardedAd?.let { ad ->
  ad.show(this, OnUserEarnedRewardListener { rewardItem ->
    // Handle the reward.
    val rewardAmount = rewardItem.amount
    val rewardType = rewardItem.type
    Log.d(TAG, "User earned the reward.")
  })
} ?: run {
  Log.d(TAG, "The rewarded ad wasn't ready yet.")
}

שאלות נפוצות

האם יש זמן קצוב לתפוגה עבור שיחת האתחול?
לאחר 10 שניות, Google Mobile Ads SDK מפעיל את OnInitializationCompleteListener, גם אם רשת הגישור עדיין לא סיימה את האתחול.
מה קורה אם חלק מהרשתות בתהליך בחירת הרשת אינן מוכנות כשאני מקבל את הקריאה החוזרת להפעלה?

מומלץ לטעון מודעה בקריאה החוזרת (callback) של השדה OnInitializationCompleteListener. גם אם רשת לבחירת רשת (Mediation) לא מוכנה, Google Mobile Ads SDK עדיין מבקש מודעה מרשת זו. כך שאם רשת תהליך בחירת הרשת מסתיימת בהפעלה אחרי הזמן הקצוב לתפוגה, עדיין אפשר לטפל בבקשות עתידיות להצגת מודעות בסשן הזה.

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

איך אפשר לבדוק מדוע רשת מסוימת לבחירת רשת (Mediation) אינה מוכנה?

AdapterStatus.getDescription() מתאר מדוע מתאם לא מוכן לשרת בקשות להצגת מודעות.

האם הקריאה החוזרת onUserEarnedReward() מבוצעת לפני הקריאה החוזרת onAdDismissedFullScreenContent()?

במודעות Google, כל onUserEarnedReward() השיחות מתרחשות לפני onAdDismissedFullScreenContent(). במודעות שמוגשות דרך תהליך בחירת הרשת, ההטמעה של רשת המודעות של הצד השלישי קובעת את סדר הקריאה החוזרת. בערכות SDK של רשתות מודעות שמספקות קריאה חוזרת יחידה (callback) עם פרטי תגמול, מתאם הגישור מפעיל את onUserEarnedReward() לפני onAdDismissedFullScreenContent().

דוגמאות ל-GitHub

השלבים הבאים

נסו את הנושאים הבאים: