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

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

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

• Google Mobile Ads SDK מגרסה 19.7.0 ואילך.
• קוראים את המדריך לתחילת העבודה.

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

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

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

ca-app-pub-3940256099942544/5224354917

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

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

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

הערה: צריך לבצע את כל הקריאות ל-Mobile Ads SDK בשרשור הראשי.

כדי לטעון מודעות מתגמלות, צריך להפעיל את השיטה הסטטית load() בכיתה RewardedAd ולהעביר RewardedAdLoadCallback. בדרך כלל עושים זאת בשיטה onCreate() של Activity. שימו לב שכמו פונקציות קריאה חוזרת אחרות של טעינת פורמט, 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
       }
    })
  }
}

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

הגדרת FullScreenContentCallback

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

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.")
}

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

באפליקציות שדורשות נתונים נוספים בקריאות חזרה של אימות בצד השרת, צריך להשתמש בתכונה 'נתונים מותאמים אישית' של מודעות מתגמלות. כל ערך מחרוזת שמוגדר באובייקט של מודעה עם פרס מועבר לפרמטר השאילתה custom_data של קריאה חוזרת (callback) של SSV. אם לא מגדירים ערך נתונים מותאם אישית, ערך פרמטר השאילתה custom_data לא יופיע בקריאה החוזרת של 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
  }
})

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

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

שאלות נפוצות

האם יש זמן קצוב לתפוגה של קריאת האתחול?

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

מה קורה אם חלק מרשתות בחירת הרשת לא מוכנות כשמקבלים את הקריאה החוזרת (callback) להפעלה?

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

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

איך אפשר לבדוק למה רשת ספציפית לבחירת רשת לא מוכנה?

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

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

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

דוגמאות ב-GitHub

• דוגמה למודעות מתגמלות: Java | Kotlin

השלבים הבאים

כדאי לעיין בנושאים הבאים:

• פרטיות המשתמשים
• הפעלה אופטימלית של ה-SDK וטעינה של מודעות (בטא)