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

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

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

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

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

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

مراجع إضافية

مثال في GitHub