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


تتيح الإعلانات التي تضم مكافآت للمستخدمين إمكانية التفاعل معهم مقابل الحصول على مكافآت داخل التطبيق. يوضّح لك هذا الدليل كيفية دمج الإعلانات التي تضم مكافآت في تطبيقات 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 لـ 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، اطّلِع على مقالة استخدام عقود 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 على الأجهزة الجوّالة تطلب عرض إعلان من تلك الشبكة. وبالتالي، إذا انتهت شبكة التوسّط من بدء التشغيل بعد انتهاء مهلة الانتظار، سيظل بإمكانها عرض طلبات الإعلانات المستقبلية في تلك الجلسة.

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

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

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

مراجع إضافية

مثال في GitHub