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

الإعلانات التي تضم مكافأة هي إعلانات يتوفّر للمستخدمين خيار التفاعل معها مقابل مكافآت داخل التطبيق. يوضّح لك هذا الدليل كيفية دمج الإعلانات التي تضم مكافأة من 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);

});

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

نقطة رئيسية: سلسلة المكافأة المخصّصة هي نسبة مئوية تم إلغاؤها وقد تتطلب فك ترميز عند تحليلها من معاودة اتصال SSV.

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

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

مصادر إضافية

• مثال على HelloWorld: تنفيذ مبسَّط لجميع أشكال الإعلانات.