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


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

يمكنك الاطّلاع على بعض قصص نجاح العملاء: دراسة الحالة 1 ودراسة الحالة 2.

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

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

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

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

  • نظام تشغيل 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 إلى Activity Android أو مؤشر إلى 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، يُرجى الاطّلاع على استخدام Futures لتتبُّع حالة اكتمال طلبات الطرق.

تحميل إعلان

يتم تحميل الإعلان باستخدام الطريقة 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) الخاصة بتطبيقات C++‎ من "إعلانات Google على الأجهزة الجوّالة" عملية firebase::Future التي تعرضها Initialize() حتى إذا لم تكمل إحدى شبكات التوسّط عملية الإعداد بعد.
ماذا لو لم تكن بعض شبكات التوسّط جاهزة عند تلقّي معاودة الاتصال الخاصة ببدء التشغيل؟

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

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

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

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

مراجع إضافية

مثال في GitHub