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

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

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

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

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

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

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

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

  • نظام تشغيل 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. العرض الرئيسي هو مرجع JNI jobject إلى 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 ثوانٍ، تكمل حزمة C++ SDK لإعلانات Google على الأجهزة الجوّالة عملية firebase::Future التي يعرضها Initialize() حتى لو لم تكتمل عملية الإعداد الخاصة بشبكة التوسّط.
ماذا لو لم تكن بعض شبكات التوسّط جاهزة عند تلقِّي معاودة الاتصال بالإعداد؟

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

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

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

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

مراجع إضافية

مثال في GitHub