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


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

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

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

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

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

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

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

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

تحميل إعلان

يتم الانتهاء من تحميل الإعلان باستخدام طريقة 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() سبب عدم جاهزية المحوّل للصيانة. لطلبات الإعلان. اطّلع على رمز المصدر الخاص مثال على تطبيق Quickstart في GitHub للحصول على مثال على تسجيل حالة محوّل التوسّط.

مراجع إضافية

مثال في GitHub