الإعلان البيني بمكافأة (إصدار تجريبي)

الإعلانات البينية بمكافأة هي نوع من أشكال الإعلانات المحفَّزة التي تتيح لك تقديم مكافآت للإعلانات التي تظهر تلقائيًا أثناء عمليات الانتقال الطبيعية بين التطبيقات. على عكس الإعلانات التي تضم مكافأة، لا يُطلب من المستخدمين الموافقة على عرض الإعلانات البينية التي تضم مكافأة.

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

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

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

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

Android

iOS

إعداد حزمة تطوير البرامج (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() الثابتة في الفئة RewardedInterstitialAd. تتطلب طريقة التحميل رقم تعريف وحدة إعلانية وعنصر AdRequest ومعالج الإكمال الذي يتم استدعاءه عند نجاح تحميل الإعلان أو تعذُّر تحميله. يتم توفير الكائن RewardedInterstitialAd الذي تم تحميله كمَعلمة في معالج الإكمال. يوضّح المثال أدناه كيفية تحميل RewardedInterstitialAd.


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

  private RewardedInterstitialAd _rewardedInterstitialAd;

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

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

      // create our request used to load the ad.
      var adRequest = new AdRequest();
      adRequest.Keywords.Add("unity-admob-sample");

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

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

              _rewardedInterstitialAd = ad;
          });
  }

[اختياري] التحقق من صحة عمليات استدعاء التحقّق من جهة الخادم (SSV)

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

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

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

        // If the operation completed successfully, no error is returned.
        Debug.Log("Rewarded interstitial 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 ShowRewardedInterstitialAd()
{
    const string rewardMsg =
        "Rewarded interstitial ad rewarded the user. Type: {0}, amount: {1}.";

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

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

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

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

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

عند الانتهاء من RewardedInterstitialAd، احرص على استدعاء طريقة Destroy() قبل إسقاط الإشارة إليها:

_rewardedInterstitialAd.Destroy();

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

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

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

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

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

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

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

مصادر إضافية