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

الإعلانات التي تضم مكافأة هي إعلانات يتوفّر للمستخدمين خيار التفاعل معها في مقابل الحصول على مكافآت داخل التطبيق. يوضّح لك هذا الدليل كيفية دمج الإعلانات التي تضم مكافآت من AdMob في تطبيق Unity.

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

يوضّح هذا الدليل كيفية دمج الإعلانات التي تضم مكافأة في تطبيق Unity.

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

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

يتضمن نموذج الرمز التالي رقم تعريف وحدة إعلانية يمكنك استخدامه لطلب إعلانات اختبارية. لقد تم إعدادها خصيصًا لعرض الإعلانات الاختبارية بدلاً من الإعلانات النهائية لكل طلب، ما يجعلها آمنة للاستخدام.

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

Android

ca-app-pub-3940256099942544/5224354917

iOS

ca-app-pub-3940256099942544/1712485313

إعداد حزمة تطوير البرامج (SDK) لعرض الإعلانات للأجهزة الجوّالة

قبل تحميل الإعلانات، اطلب من تطبيقك إعداد حزمة تطوير البرامج (SDK) لعرض الإعلانات للأجهزة الجوّالة من خلال استدعاء MobileAds.Initialize(). يجب إجراء ذلك مرة واحدة فقط، ومن المفضّل إجراء ذلك عند إطلاق التطبيق.

using GoogleMobileAds;
using GoogleMobileAds.Api;

public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    public void Start()
    {
        // Initialize the Google Mobile Ads SDK.
        MobileAds.Initialize((InitializationStatus initStatus) =>
        {
            // This callback is called once the MobileAds SDK is initialized.
        });
    }
}

وإذا كنت تستخدِم التوسّط، انتظِر حتى يحدث معاودة الاتصال قبل تحميل الإعلانات، لأنّ ذلك سيضمن إعداد جميع محوِّلات التوسّط.

التنفيذ

تتمثل الخطوات الرئيسية لدمج الإعلانات التي تضم مكافأة في ما يلي:

  1. تحميل الإعلان الذي يضم مكافأة
  2. [اختياري] التحقّق من صحة عمليات معاودة الاتصال لإثبات الملكية من جهة الخادم (SSV)
  3. عرض الإعلان الذي يضم مكافأة مع معاودة الاتصال بالمكافأة
  4. الاستماع إلى أحداث الإعلانات التي تضم مكافأة
  5. تنظيف الإعلان الذي يضم مكافأة
  6. تحميل الإعلان التالي الذي يضمّ مكافأة مُسبقًا

تحميل الإعلان الذي يضم مكافأة

يتم تحميل إعلان يضمّ مكافأة باستخدام طريقة Load() الثابتة للفئة RewardedAd. يتم توفير كائن RewardedAd الذي تم تحميله كمعلَمة في معالج الإكمال. يوضح المثال أدناه كيفية تحميل RewardedAd.


  // These ad units are configured to always serve test ads.
#if UNITY_ANDROID
  private string _adUnitId = "ca-app-pub-3940256099942544/5224354917";
#elif UNITY_IPHONE
  private string _adUnitId = "ca-app-pub-3940256099942544/1712485313";
#else
  private string _adUnitId = "unused";
#endif

  private RewardedAd _rewardedAd;

  /// <summary>
  /// Loads the rewarded ad.
  /// </summary>
  public void LoadRewardedAd()
  {
      // Clean up the old ad before loading a new one.
      if (_rewardedAd != null)
      {
            _rewardedAd.Destroy();
            _rewardedAd = null;
      }

      Debug.Log("Loading the rewarded ad.");

      // create our request used to load the ad.
      var adRequest = new AdRequest();

      // send the request to load the ad.
      RewardedAd.Load(_adUnitId, adRequest,
          (RewardedAd ad, LoadAdError error) =>
          {
              // if error is not null, the load request failed.
              if (error != null || ad == null)
              {
                  Debug.LogError("Rewarded ad failed to load an ad " +
                                 "with error : " + error);
                  return;
              }

              Debug.Log("Rewarded ad loaded with response : "
                        + ad.GetResponseInfo());

              _rewardedAd = ad;
          });
  }

[اختياري] التحقّق من صحة عمليات معاودة الاتصال لإثبات الملكية من جهة الخادم (SSV)

على التطبيقات التي تتطلب بيانات إضافية في عمليات معاودة الاتصال لإثبات الملكية من جهة الخادم استخدام ميزة البيانات المخصّصة للإعلانات التي تضم مكافآت. ويتم نقل أي قيمة سلسلة يتم ضبطها في عنصر إعلان يضم مكافأة إلى معلَمة طلب البحث custom_data الخاصة بمعاودة الاتصال بميزة SSV. إذا لم يتم ضبط أي قيمة بيانات مخصّصة، لن تتوفّر قيمة معلَمة طلب البحث custom_data في عملية استدعاء SSV.

يوضح نموذج الرمز البرمجي التالي كيفية ضبط خيارات SSV بعد تحميل الإعلان بمكافأة.

// send the request to load the ad.
RewardedAd.Load(_adUnitId, adRequest, (RewardedAd ad, LoadAdError error) =>
{
    // If the operation failed, an error is returned.
    if (error != null || ad == null)
    {
        Debug.LogError("Rewarded ad failed to load an ad with error : " + error);
        return;
    }

    // If the operation completed successfully, no error is returned.
    Debug.Log("Rewarded ad loaded with response : " + ad.GetResponseInfo());

    // Create and pass the SSV options to the rewarded ad.
    var options = new ServerSideVerificationOptions
                          .Builder()
                          .SetCustomData("SAMPLE_CUSTOM_DATA_STRING")
                          .Build()
    ad.SetServerSideVerificationOptions(options);

});

إذا كنت تريد ضبط سلسلة المكافأة المخصّصة، عليك إجراء ذلك قبل عرض الإعلان.

عرض الإعلان الذي يضم مكافأة مع معاودة الاتصال بالمكافأة

عند عرض إعلانك، يجب تقديم معاودة الاتصال لمعالجة المكافأة المُقدّمة للمستخدم. يمكن عرض الإعلانات مرة واحدة فقط لكل تحميل. استخدِم طريقة CanShowAd() للتأكّد من أنّ الإعلان جاهز للعرض

ويعرض الرمز التالي أفضل طريقة لعرض الإعلان الذي يضم مكافأة.

public void ShowRewardedAd()
{
    const string rewardMsg =
        "Rewarded ad rewarded the user. Type: {0}, amount: {1}.";

    if (rewardedAd != null && rewardedAd.CanShowAd())
    {
        rewardedAd.Show((Reward reward) =>
        {
            // TODO: Reward the user.
            Debug.Log(String.Format(rewardMsg, reward.Type, reward.Amount));
        });
    }
}

الاستماع إلى أحداث الإعلانات التي تضم مكافأة

لتخصيص سلوك إعلانك بصورةٍ أكبر، يمكنك جذب عدد من الأحداث في مراحل نشاط الإعلان، مثل الفتح والإغلاق وما إلى ذلك. الاستماع إلى هذه الأحداث من خلال تسجيل مفوّض كما هو موضح أدناه.

private void RegisterEventHandlers(RewardedAd ad)
{
    // Raised when the ad is estimated to have earned money.
    ad.OnAdPaid += (AdValue adValue) =>
    {
        Debug.Log(String.Format("Rewarded ad paid {0} {1}.",
            adValue.Value,
            adValue.CurrencyCode));
    };
    // Raised when an impression is recorded for an ad.
    ad.OnAdImpressionRecorded += () =>
    {
        Debug.Log("Rewarded ad recorded an impression.");
    };
    // Raised when a click is recorded for an ad.
    ad.OnAdClicked += () =>
    {
        Debug.Log("Rewarded ad was clicked.");
    };
    // Raised when an ad opened full screen content.
    ad.OnAdFullScreenContentOpened += () =>
    {
        Debug.Log("Rewarded ad full screen content opened.");
    };
    // Raised when the ad closed full screen content.
    ad.OnAdFullScreenContentClosed += () =>
    {
        Debug.Log("Rewarded ad full screen content closed.");
    };
    // Raised when the ad failed to open full screen content.
    ad.OnAdFullScreenContentFailed += (AdError error) =>
    {
        Debug.LogError("Rewarded ad failed to open full screen content " +
                       "with error : " + error);
    };
}

تنظيف الإعلان الذي يضم مكافأة

عند الانتهاء من استخدام RewardedAd، احرص على استدعاء الطريقة Destroy() قبل إضافة المرجع إليها:

_rewardedAd.Destroy();

بهذه الطريقة، يتم إشعار المكوّن الإضافي بأنّ العنصر لم يعُد مستخدمًا وأنّه يمكن استعادة الذاكرة التي يشغلها. يؤدي عدم استدعاء هذه الطريقة إلى تسرّب الذاكرة.

تحميل الإعلان التالي الذي يضمّ مكافأة مُسبقًا

RewardedAd هو عنصر يُستخدم لمرة واحدة. وهذا يعني أنّه بعد عرض الإعلان الذي يضم مكافأة، لا يمكن استخدام الكائن مرة أخرى. لطلب إعلان آخر يضم مكافأة، عليك إنشاء عنصر RewardedAd جديد.

لإعداد إعلان يضم مكافأة لفرصة الظهور التالية، عليك تحميل الإعلان الذي يضم مكافأة مسبقًا عند زيادة حدث الإعلان OnAdFullScreenContentClosed أو OnAdFullScreenContentFailed.

private void RegisterReloadHandler(RewardedAd ad)
{
    // Raised when the ad closed full screen content.
    ad.OnAdFullScreenContentClosed += () =>
    {
        Debug.Log("Rewarded Ad full screen content closed.");

        // Reload the ad so that we can show another as soon as possible.
        LoadRewardedAd();
    };
    // Raised when the ad failed to open full screen content.
    ad.OnAdFullScreenContentFailed += (AdError error) =>
    {
        Debug.LogError("Rewarded ad failed to open full screen content " +
                       "with error : " + error);

        // Reload the ad so that we can show another as soon as possible.
        LoadRewardedAd();
    };
}

مراجع إضافية