تحميل إعلان واحد مقابل مكافأة

تسمح لك الإعلانات مقابل مكافأة بمنح مكافآت للمستخدمين باستخدام منتجات داخل التطبيق مقابل التفاعل مع إعلانات الفيديو، و"إعلانات تشغيل إصدار بسيط من اللعبة"، والاستطلاعات.

المتطلبات الأساسية

إعداد 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
    }
  },
)

جافا

// 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
      }
    },
  )
}

جافا

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

جافا

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

اختياري: التحقّق من صحة عمليات رد الاتصال في عملية تحقّق من جهة الخادم

إذا كان تطبيقك يتطلّب بيانات إضافية في عمليات معاودة الاتصال للتحقّق من جهة الخادم، استخدِم ميزة البيانات المخصّصة في "الإعلانات مقابل مكافأة". يتم تمرير أي قيمة سلسلة تم ضبطها على عنصر إعلان مقابل مكافأة إلى مَعلمة طلب البحث custom_data في معاودة الاتصال من جهة الخادم إلى الخادم. في حال عدم ضبط أي قيمة بيانات مخصّصة، لن تظهر قيمة مَعلمة طلب البحث custom_data في معاودة الاتصال من جهة الخادم.

تعرض عينة التعليمات البرمجية التالية كيفية ضبط بيانات مخصّصة على عنصر "إعلان مقابل مكافأة" قبل طلب عرض إعلان:

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)
    }
  },
)

جافا

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 ببياناتك المخصّصة.

إذا أردت ضبط سلسلة المكافآت المخصّصة، عليك إجراء ذلك قبل عرض الإعلان.

نقطة أساسية: سلسلة المكافآت المخصّصة يجب أن تكون متوافقة مع معيار الترميز URL. قد تحتاج إلى فك ترميز سلسلة المكافآت المخصّصة عند تحليلها من معاودة الاتصال من جهة الخادم.