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

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

الإعلانات مقابل مكافأة هي إعلانات يمكن للمستخدمين اختيار التفاعل معها في مقابل الحصول على مكافآت داخل التطبيق. يعرض هذا الدليل كيفية دمج "الإعلانات مقابل مكافأة" من AdMob في تطبيق Flutter.

اختبار الإعلانات دائمًا باستخدام الإعلانات الاختبارية

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

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

Android

ca-app-pub-3940256099942544/5224354917

iOS

ca-app-pub-3940256099942544/1712485313

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

تحميل إعلان

يحمّل المثال التالي إعلانًا مقابل مكافأة:

RewardedAd.load(
  adUnitId: "_adUnitId",
  request: const AdRequest(),
  rewardedAdLoadCallback: RewardedAdLoadCallback(
    onAdLoaded: (RewardedAd ad) {
      // Called when an ad is successfully received.
      debugPrint('Ad was loaded.');
      // Keep a reference to the ad so you can show it later.
      _rewardedAd = ad;
    },
    onAdFailedToLoad: (LoadAdError error) {
      // Called when an ad request failed.
      debugPrint('Ad failed to load with error: $error');
    },
  ),
);

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

أحداث "الإعلان مقابل مكافأة"

باستخدام FullScreenContentCallback، يمكنك الاستماع إلى أحداث مراحل نشاط الإعلان، مثل وقت ظهور الإعلان أو إغلاقه. اضبط RewardedAd.fullScreenContentCallback قبل عرض الإعلان لتلقّي إشعارات بشأن هذه الأحداث. ينفّذ هذا المثال كل طريقة ويسجِّل رسالة في وحدة التحكّم:

ad.fullScreenContentCallback = FullScreenContentCallback(
  onAdShowedFullScreenContent: (ad) {
    // Called when the ad showed the full screen content.
    debugPrint('Ad showed full screen content.');
  },
  onAdFailedToShowFullScreenContent: (ad, err) {
    // Called when the ad failed to show full screen content.
    debugPrint('Ad failed to show full screen content with error: $err');
    // Dispose the ad here to free resources.
    ad.dispose();
  },
  onAdDismissedFullScreenContent: (ad) {
    // Called when the ad dismissed full screen content.
    debugPrint('Ad was dismissed.');
    // Dispose the ad here to free resources.
    ad.dispose();
  },
  onAdImpression: (ad) {
    // Called when an impression occurs on the ad.
    debugPrint('Ad recorded an impression.');
  },
  onAdClicked: (ad) {
    // Called when a click is recorded for an ad.
    debugPrint('Ad was clicked.');
  },
);

عرض إعلان

يتم عرض RewardedAd كتراكب فوق كل محتوى التطبيق ويتم وضعه بشكل ثابت، لذا لا يمكن إضافته إلى شجرة عناصر واجهة مستخدم Flutter. يمكنك اختيار وقت عرض الإعلان من خلال استدعاء show(). تأخذ الدالة RewardedAd.show() دالة معاودة الاتصال OnUserEarnedRewardCallback، التي يتم استدعاؤها عندما يحصل المستخدم على مكافأة. احرص على تنفيذ هذه الدالة ومكافأة المستخدم على مشاهدة إعلان.

_rewardedAd?.show(
  onUserEarnedReward: (AdWithoutView ad, RewardItem rewardItem) {
    debugPrint('Reward amount: ${rewardItem.amount}');
  },
);

بعد استدعاء show()، لا يمكن إزالة Ad المعروض بهذه الطريقة آليًا ويتطلّب بيانات أدخلها المستخدم. لا يمكن عرض RewardedAd إلا مرة واحدة. ستؤدي عمليات الاستدعاء اللاحقة للدالة show إلى استدعاء onAdFailedToShowFullScreenContent.

يجب إيقاف الإعلان عندما لا يعود هناك حاجة إلى الوصول إليه. أفضل ممارسة لتحديد وقت استدعاء dispose() هي في دوال معاودة الاتصال FullScreenContentCallback.onAdDismissedFullScreenContent وFullScreenContentCallback.onAdFailedToShowFullScreenContent.

[اختياري] التحقّق من دوال معاودة الاتصال لعملية التحقّق من جهة الخادم (SSV)

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

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

RewardedAd.load(
  adUnitId: "_adUnitId",
  request: AdRequest(),
  rewardedAdLoadCallback: RewardedAdLoadCallback(
    onAdLoaded: (ad) {
      ServerSideVerificationOptions _options =
          ServerSideVerificationOptions(
            customData: 'SAMPLE_CUSTOM_DATA_STRING',
          );
      ad.setServerSideOptions(_options);
      _rewardedAd = ad;
    },
    onAdFailedToLoad: (error) {},
  ),
);

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

مثال كامل على GitHub

لعرض المثال الكامل، اطّلِع على العرض التوضيحي لواجهة برمجة التطبيقات.