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


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

الاطّلاع على بعض قصص نجاح العملاء: دراسة الحالة 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. عرض الصفحة الرئيسية هو 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، اطّلِع على مقالة استخدام العقود الآجلة لرصد حالة اكتمال طلبات معالجة الطلبات .

تحميل إعلان

يتم تحميل الإعلان باستخدام الطريقة 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