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

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

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

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

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

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

טעינת מודעה

טיפ: כדי לשפר את זמן הטעינה של כמה מודעות, כדאי להשתמש בטעינת מודעה מראש.

בדוגמה הבאה נטענת מודעה אחת:

Kotlin

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

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

Java

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

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

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

הצגת המודעה

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

בדוגמה הבאה מוצגת המודעה:

Kotlin

private fun showAd(rewardedInterstitialAd: RewardedInterstitialAd, activity: Activity) {
  // Show the ad.
  rewardedInterstitialAd.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(RewardedInterstitialAd rewardedInterstitialAd, Activity activity) {
  // Show the ad.
  rewardedInterstitialAd.show(
      activity,
      new OnUserEarnedRewardListener() {
        @Override
        public void onUserEarnedReward(@NonNull RewardItem rewardItem) {
          // User earned the reward.
          int rewardAmount = rewardItem.getAmount();
          String rewardType = rewardItem.getType();
        }
      });
}

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

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

Kotlin

private fun listenToAdEvents() {
  // Listen for ad events.
  val ad = rewardedInterstitialAd
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not ready yet.")
    return
  }

  ad.adEventCallback =
    object : RewardedInterstitialAdEventCallback {
      override fun onAdShowedFullScreenContent() {
        // Rewarded interstitial ad did show.
      }

      override fun onAdDismissedFullScreenContent() {
        // Rewarded interstitial ad did dismiss.
        rewardedInterstitialAd = null
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError
      ) {
        // Rewarded interstitial ad failed to show.
        Log.e(TAG, "Rewarded interstitial ad failed to show: ${fullScreenContentError.message}")
      }

      override fun onAdImpression() {
        // Rewarded interstitial ad did record an impression.
      }

      override fun onAdClicked() {
        // Rewarded interstitial ad did record a click.
      }
    }
}

Java

private void listenToAdEvents() {
  // Listen for ad events.
  if (rewardedInterstitialAd == null) {
    Log.e(TAG, "Rewarded interstitial ad is not ready yet.");
    return;
  }

  rewardedInterstitialAd.setAdEventCallback(
      new RewardedInterstitialAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded interstitial ad did show.
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          // Rewarded interstitial ad did dismiss.
          rewardedInterstitialAd = null;
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            @NonNull FullScreenContentError fullScreenContentError) {
          // Rewarded interstitial ad failed to show.
          Log.e(
              TAG,
              "Rewarded interstitial ad failed to show: " + fullScreenContentError.getMessage());
        }

        @Override
        public void onAdImpression() {
          // Rewarded interstitial ad did record an impression.
        }

        @Override
        public void onAdClicked() {
          // Rewarded interstitial ad did record a click.
        }
      });
}

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

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

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

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

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

Kotlin

RewardedInterstitialAd.load(
  context,
  AD_UNIT_ID,
  AdRequest.Builder().build(),
  object : RewardedInterstitialAdLoadCallback() {
    override fun onAdLoaded(ad: RewardedInterstitialAd) {
      rewardedInterstitialAd = ad
      val options =
        ServerSideVerificationOptions.Builder().setCustomData("SAMPLE_CUSTOM_DATA_STRING").build()
      rewardedInterstitialAd?.setServerSideVerificationOptions(options)
    }
  },
)

Java

RewardedInterstitialAd.load(
    context,
    AD_UNIT_ID,
    new AdRequest.Builder().build(),
    new RewardedInterstitialAdLoadCallback() {
      @Override
      public void onAdLoaded(RewardedInterstitialAd ad) {
        rewardedInterstitialAd = ad;
        ServerSideVerificationOptions options =
            new ServerSideVerificationOptions.Builder()
                .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
                .build();
        rewardedInterstitialAd.setServerSideVerificationOptions(options);
      }
    });

מחליפים את SAMPLE_CUSTOM_DATA_STRING בנתונים בהתאמה אישית.

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