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

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

يشرح هذا الدليل كيفية دمج "الإعلانات مقابل مكافأة" في تطبيق Android.

قبل البدء

قبل المتابعة، عليك تنفيذ ما يلي:

• إعداد GMA Next-Gen SDK
• استخدِم معرّف الوحدة الإعلانية الاختبارية "للإعلانات مقابل مكافأة" ca-app-pub-3940256099942544/5224354917.
  • عند إنشاء تطبيقك واختباره، تأكَّد من استخدام الإعلانات الاختبارية بدلاً من الإعلانات المباشرة والنهائية. إذا لم تستخدم معرّف الوحدة الإعلانية الاختبارية، يمكن أن تعلّق Google حسابك.
  • قبل نشر تطبيقك، استبدِل هذا المعرّف بمعرّف الوحدة الإعلانية.
  • لمعرفة تفاصيل عن الإعلانات الاختبارية في 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.
        }
      });
}

اختياري: التحقّق من صحة عمليات معاودة الاتصال في ميزة "التحقّق من جهة الخادم" (SSV)

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

• معلمة طلب البحث user_id: تحدّد المستخدم الذي ستتم مكافأته، مثل رقم تعريف حساب داخلي.
• معلمة طلب البحث custom_data: تحمل بيانات التطبيق، مثل موضع المكافأة أو مستوى اللعبة أو رقم خاص يتم إنشاؤه من الخادم.

إذا لم تضبط قيمة، ستحذف Google مَعلمة طلب البحث هذه من طلب معاودة الاتصال للتحقّق من صحة الخادم.

يضبط المثال التالي بيانات مخصّصة على عنصر إعلان قبل عرض الإعلان:

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

ملاحظة أساسية: يتم ترميز custom_data مَعلمة طلب البحث بالنسبة المئوية. قبل تحليل القيمة، عليك فك ترميز عنوان URL للسلسلة على الخادم والتحقّق من توقيع معاودة الاتصال قبل الوثوق بمعلمات طلب البحث user_id أو custom_data.