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

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

يشرح هذا الدليل كيفية دمج الإعلانات التي تضم مكافآت في تطبيق Unity.

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

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

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

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

/21775744923/example/rewarded

إعداد حزمة تطوير البرامج (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. [اختياري] التحقّق من صحة عمليات معاودة الاتصال في عملية إثبات الملكية من جهة الخادم
  3. عرض الإعلان الذي يضم مكافأة مع معاودة الاتصال بالمكافأة
  4. الاستماع إلى أحداث الإعلانات التي تضم مكافأة
  5. تنظيف الإعلان الذي يضم مكافأة
  6. التحميل المسبق للإعلان التالي الذي يضم مكافأة

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

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


  // This ad unit is configured to always serve test ads.
  private string _adUnitId = "/21775744923/example/rewarded";

  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 AdManagerAdRequest();

      // 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;
          });
  }

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

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

مراجع إضافية