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


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

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

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

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

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

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

  • نظام تشغيل 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. عرض الصفحة الرئيسية هو jobject JNI يشير إلى 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). حتى إذا لم تكن شبكة التوسّط جاهزة، ستظلّ حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" مكتوبة بلغة C++ تطلب من تلك الشبكة عرض إعلان. وبالتالي، إذا انتهت شبكة التوسّط من بدء التشغيل بعد انتهاء مهلة الانتظار، سيظل بإمكانها عرض طلبات الإعلانات المستقبلية في تلك الجلسة.

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

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

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

مراجع إضافية

مثال في GitHub