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


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

  • يمكنك الاطّلاع على رمز المصدر لتطبيق البدء السريع النموذجي في GitHub.