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


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

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

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

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

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

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

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

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

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

لمزيد من المعلومات عن طريقة عمل الإعلانات الاختبارية في حزمة "SDK لإعلانات Google على الأجهزة الجوّالة"، يُرجى الاطّلاع على الإعلانات الاختبارية.

التنفيذ

في ما يلي الخطوات الرئيسية لدمج "الإعلانات مقابل مكافأة":

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

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

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

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

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

مراجع إضافية

مثال في GitHub