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

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

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

תמיד לבדוק עם מודעות בדיקה

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

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

ca-app-pub-3940256099942544/5224354917

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

למידע נוסף על אופן הפעולה של מודעות בדיקה של 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 mRewardedAd;
  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());
          mRewardedAd = null;
        }

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

Kotlin

class MainActivity : AppCompatActivity() {

  private var mRewardedAd: 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())
        mRewardedAd = null
      }

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

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

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

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

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

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

Java

mRewardedAd.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.");
    mRewardedAd = null;
  }

  @Override
  public void onAdFailedToShowFullScreenContent(AdError adError) {
    // Called when ad fails to show.
    Log.e(TAG, "Ad failed to show fullscreen content.");
    mRewardedAd = 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

mRewardedAd?.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.")
    mRewardedAd = null
  }

  override fun onAdFailedToShowFullScreenContent(adError: AdError?) {
    // Called when ad fails to show.
    Log.e(TAG, "Ad failed to show fullscreen content.")
    mRewardedAd = 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 (mRewardedAd != null) {
  Activity activityContext = MainActivity.this;
  mRewardedAd.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

if (mRewardedAd != null) {
  mRewardedAd?.show(this, OnUserEarnedRewardListener() {
    fun onUserEarnedReward(rewardItem: RewardItem) {
      var rewardAmount = rewardItem.amount
      var rewardType = rewardItem.type
      Log.d(TAG, "User earned the reward.")
    }
  })
} else {
  Log.d(TAG, "The rewarded ad wasn't ready yet.")
}

שאלות נפוצות

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

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

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

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

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

האם השיחה החוזרת ב-onUserEarnedReward() מופעלת תמיד לפני השיחה מסוג onAdDismissedFullScreenContent()?

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

דוגמאות ב-GitHub

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