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

تتيح الإعلانات التي تضم مكافآت للمستخدمين إمكانية التفاعل معهم مقابل الحصول على مكافآت داخل التطبيق. يوضّح لك هذا الدليل كيفية دمج الإعلانات التي تضم مكافأة في تطبيقات Android وiOS باستخدام حزمة C++ SDK لإعلانات Google على الأجهزة الجوّالة.

قراءة بعض قصص نجاح العملاء: دراسة الحالة 1، دراسة الحالة 2.

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

  • أكمِل البدء.
  • (نظام التشغيل Android فقط) الدراية بالعمل باستخدام مراجع JNI jobject (راجِع نصائح Android JNI)

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

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

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

  • نظام تشغيل Android:‏ ca-app-pub-3940256099942544/5224354917
  • نظام تشغيل iOS:‏ ca-app-pub-3940256099942544/1712485313

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

لمزيد من المعلومات عن آلية عمل الإعلانات الاختبارية لحزمة تطوير البرامج (SDK) لعرض الإعلانات للأجهزة الجوّالة، اطّلِع على اختبار الإعلانات.

التنفيذ

الخطوات الأساسية لدمج الإعلانات التي تضم مكافأة هي:

  1. حمِّل إعلانًا.
  2. التسجيل لتلقّي طلبات معاودة الاتصال
  3. يمكنك عرض الإعلان والتعامل مع حدث المكافأة.

ضبط RewardedAd

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

  1. أضِف العنوان التالي إلى رمز C++ لتطبيقك: 

     #include "firebase/gma/rewarded_ad.h"

  2. تعريف عنصر RewardedAd وإنشاء مثيل له: 

     firebase::gma::RewardedAd* rewarded_ad;
 rewarded_ad = new firebase::gma::RewardedAd();

  3. يمكنك إعداد مثيل RewardedAd باستخدام طريقة العرض الرئيسية، حيث يتم بث المحتوى من نوع AdParent. العرض الرئيسي هو مرجع jobject من JNI لـ Android Activity أو مؤشر إلى UIView iOS.

    // my_ad_parent is a jobject reference to an Android Activity or
// a pointer to an iOS UIView.
firebase::gma::AdParent ad_parent =
  static_cast<firebase::gma::AdParent>(my_ad_parent);
firebase::Future<void> result = rewarded_ad->Initialize(ad_parent);

  4. كبديل للاحتفاظ بالمستقبل كمتغيّر، يمكنك التحقّق بشكل دوري من حالة عملية الإعداد من خلال استدعاء InitializeLastResult() في الكائن RewardedAd. قد يكون هذا مفيدًا لتتبع عملية التهيئة في حلقة الألعاب العالمية.

    // Monitor the status of the future in your game loop:
firebase::Future<void> result = rewarded_ad->InitializeLastResult();
if (result.status() == firebase::kFutureStatusComplete) {
  // Initialization completed.
  if(future.error() == firebase::gma::kAdErrorCodeNone) {
    // Initialization successful.
  } else {
    // An error has occurred.
  }
} else {
  // Initialization on-going.
}

لمزيد من المعلومات عن العمل مع firebase::Future، يمكنك الاطّلاع على استخدام العقود الآجلة لمراقبة حالة اكتمال استدعاءات الطرق.

تحميل إعلان

يتم تحميل الإعلان باستخدام الطريقة LoadAd() في كائن RewardedAd. تتطلب طريقة التحميل إعداد الكائن RewardedAd، وأن يكون لديك رقم تعريف الوحدة الإعلانية وعنصر AdRequest. يتم عرض firebase::Future والذي يمكنك استخدامه لمراقبة حالة عملية التحميل ونتائجها.

يوضّح الرمز التالي كيفية تحميل إعلان بعد إعداد RewardedAd بنجاح:

firebase::gma::AdRequest ad_request;
firebase::Future<firebase::gma::AdResult> load_ad_result;
load_ad_result = rewarded_ad->LoadAd(rewarded_ad_unit_id, ad_request);

التسجيل لتلقّي طلبات معاودة الاتصال

عليك تمديد فترة الصف FullScreenContentListener لتلقّي إشعارات بشأن عرض الإعلانات التي تضم مكافأة وأحداث مراحل النشاط. يمكن تسجيل فئتك الفرعية المخصّصة "FullScreenContentListener" من خلال الطريقة RewardedAd::SetFullScreenContentListener()، وستتلقّى عمليات معاودة الاتصال عند عرض الإعلان بنجاح أو عدم نجاحه وكذلك عند رفضه.

يوضح الرمز التالي كيفية توسيع الفئة وتعيينها إلى الإعلان:

  class ExampleFullScreenContentListener
      : public firebase::gma::FullScreenContentListener {

   public:
    ExampleFullScreenContentListener() {}

    void OnAdClicked() override {
      // This method is invoked when the user clicks the ad.
    }

    void OnAdDismissedFullScreenContent() override {
     // This method is invoked when the ad dismisses full screen content.
    }

    void OnAdFailedToShowFullScreenContent(const AdError& error) override {
      // This method is invoked when the ad failed to show full screen content.
      // Details about the error are contained within the AdError parameter.
    }

    void OnAdImpression() override {
      // This method is invoked when an impression is recorded for an ad.
    }

    void OnAdShowedFullScreenContent() override {
      // This method is invoked when the ad showed its full screen content.
    }
  };

  ExampleFullScreenContentListener* example_full_screen_content_listener =
    new ExampleFullScreenContentListener();
  rewarded_ad->SetFullScreenContentListener(example_full_screen_content_listener);

RewardedAd هو عنصر يُستخدم لمرة واحدة. وهذا يعني أنّه بعد عرض "إعلان يضم مكافأة"، لا يمكن عرضه مرة أخرى ومن أفضل الممارسات تحميل إعلان آخر يضم مكافأة في طريقة OnAdDismissedFullScreenContent() على FullScreenContentListener، وذلك لكي يبدأ تحميل الإعلان التالي الذي يضم مكافأة فور إغلاق الإعلان السابق.

عرض الإعلان والتعامل مع حدث المكافأة

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

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

يوضّح الرمز التالي طريقة عرض RewardedAd:

// A simple listener track UserEarnedReward events.
class ExampleUserEarnedRewardListener :
    public firebase::gma::UserEarnedRewardListener {
 public:
   ExampleUserEarnedRewardListener() { }

  void OnUserEarnedReward(const firebase::gma::AdReward& reward) override {
    // Reward the user!
  }
};

ExampleUserEarnedRewardListener* user_earned_reward_listener =
  new ExampleUserEarnedRewardListener();
firebase::Future<void> result = rewarded_ad->Show(user_earned_reward_listener);

الأسئلة الشائعة

هل هناك مهلة لطلب الإعداد؟
بعد 10 ثوانٍ، تُكمل حزمة "SDK لإعلانات Google على الأجهزة الجوّالة C++ " firebase::Future التي تعرضها Initialize() حتى إذا لم تكتمل شبكة التوسط الإعداد بعد.
ماذا لو لم تكن بعض شبكات التوسّط جاهزة عند تلقّي معاودة الاتصال بالإعداد؟

ومن بين أفضل الممارسات تحميل الإعلانات بعد اكتمال إعداد حزمة تطوير البرامج (SDK). حتى إذا لم تكن شبكة التوسط جاهزة، ستظلّ حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة تطلب عرض إعلان من تلك الشبكة. وبالتالي، إذا انتهت تهيئة شبكة التوسط بعد انتهاء المهلة، يمكنها الاستمرار في معالجة طلبات الإعلان المستقبلية في تلك الجلسة.

يمكنك مواصلة استطلاع حالة إعداد جميع المحوّلات طوال جلسة التطبيق من خلال الاتصال بالرقم GetInitializationStatus().

كيف يمكنني معرفة سبب عدم جهوزية شبكة توسّط معيَّنة؟

يصف AdapterStatus.description() سبب عدم جاهزية المحوّل لخدمة طلبات الإعلانات. اطّلع على رمز مصدر مثال تطبيق Quickstart في GitHub للحصول على مثال على تسجيل حالة محوّل التوسّط.

مصادر إضافية

مثال في GitHub