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

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

الإعلان البيني بمكافأة هو نوع من أشكال الإعلانات المحفَّزة التي تتيح لك تقديم مكافآت مقابل الإعلانات التي تظهر تلقائيًا أثناء عمليات النقل العادية للتطبيقات. وعلى عكس الإعلانات مقابل مكافأة، لا يُطلب من المستخدمين الموافقة على عرض إعلان بيني مقابل مكافأة. يوضّح هذا الدليل كيفية دمج "الإعلانات البينية بمكافأة" من Ad Manager في تطبيق Flutter.

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

قبل المتابعة، يُرجى اتّخاذ الإجراءات التالية:

  • تثبيت الإصدار 1.1.0 أو إصدار أحدث من مكوّن Flutter الإضافي
  • إعداد Google Mobile Ads Flutter Plugin. يجب استيراد Google Mobile Ads Flutter Plugin إلى تطبيق Flutter.

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

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

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

  • /21775744923/example/rewarded-interstitial

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

تحميل إعلان

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

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

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

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

باستخدام FullScreenContentCallback، يمكنك الاستماع إلى أحداث مراحل نشاط الإعلان، مثل وقت ظهور الإعلان أو إغلاقه. اضبط RewardedInterstitialAd.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.');
  },
);

عرض إعلان

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

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

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

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

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

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

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

RewardedInterstitialAd.load(
  adUnitId: "_adUnitId",
  request: AdManagerAdRequest(),
  rewardedInterstitialAdLoadCallback: RewardedInterstitialAdLoadCallback(
    onAdLoaded: (ad) {
      ServerSideVerificationOptions _options =
          ServerSideVerificationOptions(
            customData: 'SAMPLE_CUSTOM_DATA_STRING',
          );
      ad.setServerSideOptions(_options);
      _rewardedInterstitialAd = ad;
    },
    onAdFailedToLoad: (error) {},
  ),
);

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