الإعلانات بمكافأة

اختيار النظام الأساسي: Android iOS Unity Flutter Android (قديم)

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

قبل البدء

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

• إعداد Google Mobile Ads SDK (Legacy)
• استخدِم معرّف وحدة الإعلانات مقابل مكافأة الاختبارية /21775744923/example/rewarded.
  • عند إنشاء تطبيقاتك واختبارها، تأكَّد من استخدام الإعلانات الاختبارية بدلاً من الإعلانات المباشرة والنهائية. إذا لم تستخدم معرّف الوحدة الإعلانية الاختبارية، يمكن أن تعلّق Google حسابك.
  • قبل نشر تطبيقك، استبدِل هذا المعرّف بمعرّف الوحدة الإعلانية.
  • لمعرفة تفاصيل عن الإعلانات الاختبارية في Google Mobile Ads SDK (Legacy)، يُرجى الاطّلاع على مقالة تفعيل الإعلانات الاختبارية.

تحميل عنصر "إعلان مقابل مكافأة"

ملاحظة: يجب إجراء جميع المكالمات إلى Google Mobile Ads SDK (Legacy) في سلسلة المحادثات الرئيسية.

يتم تحميل "الإعلانات مقابل مكافأة" من خلال استدعاء طريقة load الثابتة في فئة RewardedAd وتمرير RewardedAdLoadCallback. ويتم ذلك عادةً في طريقة onCreate لـ Activity. يُرجى العِلم أنّه مثل عمليات معاودة الاتصال الأخرى لتحميل التنسيقات، يستخدم RewardedAdLoadCallback LoadAdError لتقديم تفاصيل أخطاء بدقة أعلى.

جافا

RewardedAd.load(
    this,
    "AD_UNIT_ID",
    new AdManagerAdRequest.Builder().build(),
    new RewardedAdLoadCallback() {
      @Override
      public void onAdLoaded(@NonNull RewardedAd rewardedAd) {
        Log.d(TAG, "Ad was loaded.");
        MainActivity.this.rewardedAd = rewardedAd;
      }

      @Override
      public void onAdFailedToLoad(@NonNull LoadAdError loadAdError) {
        Log.d(TAG, loadAdError.getMessage());
        rewardedAd = null;
      }
    });
MainActivity.java

Kotlin

RewardedAd.load(
  this,
  "AD_UNIT_ID",
  AdManagerAdRequest.Builder().build(),
  object : RewardedAdLoadCallback() {
    override fun onAdLoaded(ad: RewardedAd) {
      Log.d(TAG, "Ad was loaded.")
      rewardedAd = ad
    }

    override fun onAdFailedToLoad(adError: LoadAdError) {
      Log.d(TAG, adError.message)
      rewardedAd = null
    }
  },
)
MainActivity.kt

استبدِل AD_UNIT_ID برقم تعريف وحدتك الإعلانية.

ملاحظة: يمكنك استخدام طلبات تحميل الإعلانات لإنشاء ذاكرة تخزين مؤقت للإعلانات المحمَّلة مسبقًا قبل عرضها، لكي تظهر الإعلانات بدون أي وقت استجابة عند الحاجة. بما أنّ صلاحية الإعلانات تنتهي بعد ساعة، عليك محو ذاكرة التخزين المؤقت هذه وإعادة تحميلها بإعلانات جديدة كل ساعة.

ضبط FullScreenContentCallback

يعالج FullScreenContentCallback الأحداث المتعلقة بعرض RewardedAd. قبل عرض "RewardedAd"، تأكَّد من ضبط دالة الاستدعاء على النحو التالي:

جافا

rewardedAd.setFullScreenContentCallback(
    new FullScreenContentCallback() {
      @Override
      public void onAdDismissedFullScreenContent() {
        // Called when fullscreen content is dismissed.
        Log.d(TAG, "Ad was dismissed.");
        // Don't forget to set the ad reference to null so you
        // don't show the ad a second time.
        rewardedAd = null;
      }

      @Override
      public void onAdFailedToShowFullScreenContent(AdError adError) {
        // Called when fullscreen content failed to show.
        Log.d(TAG, "Ad failed to show.");
        // Don't forget to set the ad reference to null so you
        // don't show the ad a second time.
        rewardedAd = null;
      }

      @Override
      public void onAdShowedFullScreenContent() {
        // Called when fullscreen content is shown.
        Log.d(TAG, "Ad showed fullscreen content.");
      }

      @Override
      public void onAdImpression() {
        // Called when an impression is recorded for an ad.
        Log.d(TAG, "Ad recorded an impression.");
      }

      @Override
      public void onAdClicked() {
        // Called when an ad is clicked.
        Log.d(TAG, "Ad was clicked.");
      }
    });
MainActivity.java

Kotlin

rewardedAd?.fullScreenContentCallback =
  object : FullScreenContentCallback() {
    override fun onAdDismissedFullScreenContent() {
      // Called when fullscreen content is dismissed.
      Log.d(TAG, "Ad was dismissed.")
      // Don't forget to set the ad reference to null so you
      // don't show the ad a second time.
      rewardedAd = null
    }

    override fun onAdFailedToShowFullScreenContent(adError: AdError) {
      // Called when fullscreen content failed to show.
      Log.d(TAG, "Ad failed to show.")
      // Don't forget to set the ad reference to null so you
      // don't show the ad a second time.
      rewardedAd = null
    }

    override fun onAdShowedFullScreenContent() {
      // Called when fullscreen content is shown.
      Log.d(TAG, "Ad showed fullscreen content.")
    }

    override fun onAdImpression() {
      // Called when an impression is recorded for an ad.
      Log.d(TAG, "Ad recorded an impression.")
    }

    override fun onAdClicked() {
      // Called when an ad is clicked.
      Log.d(TAG, "Ad was clicked.")
    }
  }
MainActivity.kt

عرض الإعلان

عند عرض "إعلان مقابل مكافأة"، استخدِم عنصر OnUserEarnedRewardListener للتعامل مع أحداث المكافآت.

جافا

rewardedAd.show(
    MainActivity.this,
    new OnUserEarnedRewardListener() {
      @Override
      public void onUserEarnedReward(@NonNull RewardItem rewardItem) {
        Log.d(TAG, "User earned the reward.");
        // Handle the reward.
      }
    });
MainActivity.java

Kotlin

rewardedAd?.show(
  this,
  OnUserEarnedRewardListener { rewardItem ->
    Log.d(TAG, "User earned the reward.")
    // Handle the reward.
    val rewardAmount = rewardItem.amount
    val rewardType = rewardItem.type
  },
)
MainActivity.kt

بالنسبة إلى الإعلانات التي تعرضها Google، يستدعي Google Mobile Ads SDK (Legacy) طريقة onUserEarnedReward قبل طريقة onAdDismissedFullScreenContent. بالنسبة إلى الإعلانات التي يتم عرضها من خلال التوسّط، يحدّد مصدر الإعلان التابع لجهة خارجية ترتيب عمليات معاودة الاتصال. بالنسبة إلى مصادر الإعلانات التي توفّر دالة ردّ نداء واحدة للإغلاق مع معلومات المكافأة، يستدعي محوّل التوسّط طريقة onUserEarnedReward قبل طريقة onAdDismissedFullScreenContent. لمعرفة التفاصيل، يُرجى الاطّلاع على مقالة إعداد التوسّط.

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

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

يوضّح نموذج الرمز البرمجي التالي كيفية ضبط البيانات المخصّصة في عنصر "إعلان مقابل مكافأة" قبل طلب إعلان.

جافا

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

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)
    }
  },
)
RewardedAdSnippets.kt

استبدِل SAMPLE_CUSTOM_DATA_STRING ببياناتك المخصّصة.

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

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

أمثلة على GitHub

• مثال على "الإعلانات مقابل مكافأة": Java | Kotlin

الخطوات التالية

استكشِف المواضيع التالية:

• خصوصية المستخدم
• تحسين عملية إعداد حزمة تطوير البرامج (SDK) وتحميل الإعلانات (إصدار تجريبي)