إعلانات البانر

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

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

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

• أكمِل دليل البدء.

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

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

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

/21775744923/example/adaptive-banner

إعداد حزمة تطوير البرامج (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.
        });
    }
}

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

مثال على BannerView

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

إنشاء عرض بانر

الخطوة الأولى في استخدام عرض البانر هي إنشاء مثيل لعرض البانر في نص برمجي C# مرفق بعنصر GameObject.

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

  AdManagerBannerView _bannerView;

  /// <summary>
  /// Creates a 320x50 banner view at top of the screen.
  /// </summary>
  public void CreateBannerView()
  {
      Debug.Log("Creating banner view");

      // If we already have a banner, destroy the old one.
      if (_bannerView != null)
      {
          DestroyAd();
      }

      // Create a 320x50 banner at top of the screen
      _bannerView = new AdManagerBannerView(_adUnitId, AdSize.Banner, AdPosition.Top);
  }

يحتوي مُنشئ AdManagerBannerView على المَعلمات التالية:

• adUnitId: رقم تعريف الوحدة الإعلانية التي يجب أن تحمّل منها AdManagerBannerView الإعلانات.
• AdSize: حجم الإعلان الذي تريد استخدامه. اطّلِع على مقاسات إعلانات البانر للحصول على التفاصيل.
• AdPosition: موضع عرض إعلانات البانر يسرد التعداد AdPosition قيم مواضع الإعلانات الصالحة.

لاحِظ كيفية استخدام الوحدات الإعلانية المختلفة، استنادًا إلى المنصة. عليك استخدام وحدة إعلانية على iOS لتقديم طلبات الإعلانات على iOS ووحدة إعلانية على Android لتقديم الطلبات على Android.

(اختياري) إنشاء عرض بانر باستخدام موضع مخصّص

للحصول على مزيد من التحكّم في موضع وضع AdManagerBannerView على الشاشة مقارنةً بما تقدّمه قيم AdPosition، استخدِم أسلوب الإنشاء الذي يتضمّن إحداثيات x وy كمَعلمات:

// Create a 320x50 banner views at coordinate (0,50) on screen.
_bannerView = new AdManagerBannerView(_adUnitId, AdSize.Banner, 0, 50);

يتم تحديد موضع أعلى يمين AdManagerBannerView حسب قيم x وy التي يتم تمريرها إلى المنشئ، حيث يكون المنشأ أعلى يمين الشاشة.

(اختياري) إنشاء عرض بانر بحجم مخصّص

بالإضافة إلى استخدام ثابت AdSize، يمكنك أيضًا تحديد حجم مخصّص لإعلانك:

// Use the AdSize argument to set a custom size for the ad.
AdSize adSize = new AdSize(250, 250);
_bannerView = new AdManagerBannerView(_adUnitId, adSize, AdPosition.Bottom);

(اختياري) أحجام إعلانات متعددة

يتيح لك "مدير إعلانات Google" تحديد أحجام إعلانات متعدّدة قد تكون مؤهّلة للعرض في AdManagerBannerView. قبل تنفيذ هذه الميزة في حزمة تطوير البرامج (SDK)، أنشئ بندًا يستهدِف الوحدات الإعلانية نفسها المرتبطة بتصاميم إعلانات مختلفة الأحجام.

في تطبيقك، يمكنك تمرير مَعلمات AdSize متعددة إلى ValidAdSizes:

var adView = new AdManagerBannerView(_adUnitId, AdSize.Banner, AdPosition.Top);
adView.ValidAdSizes = new List<AdSize>
{
    AdSize.Banner, new AdSize(120, 20), new AdSize(250, 250),
};

إذا تغيّر حجم AdManagerAdView في وقت التحديث، من المفترض أن يتمكّن التنسيق من التكيّف تلقائيًا مع الحجم الجديد. يتم ضبط AdManagerAdView تلقائيًا على الحجم المُرسَل في المَعلمة الأولى إلى أن يظهر الإعلان التالي.

تحميل إعلان بانر

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

/// <summary>
/// Creates the banner view and loads a banner ad.
/// </summary>
public void LoadAd()
{
    // create an instance of a banner view first.
    if(_bannerView == null)
    {
        CreateAdManagerBannerView();
    }

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

    // send the request to load the ad.
    Debug.Log("Loading banner ad.");
    _bannerView.LoadAd(adRequest);
}

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

الاستماع إلى أحداث عرض البانر

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

/// <summary>
/// listen to events the banner view may raise.
/// </summary>
private void ListenToAdEvents()
{
    // Raised when an ad is loaded into the banner view.
    _bannerView.OnBannerAdLoaded += () =>
    {
        Debug.Log("Banner view loaded an ad with response : "
            + _bannerView.GetResponseInfo());
    };
    // Raised when an ad fails to load into the banner view.
    _bannerView.OnBannerAdLoadFailed += (LoadAdError error) =>
    {
        Debug.LogError("Banner view failed to load an ad with error : "
            + error);
    };
    // Raised when the ad is estimated to have earned money.
    _bannerView.OnAdPaid += (AdValue adValue) =>
    {
        Debug.Log(String.Format("Banner view paid {0} {1}.",
            adValue.Value,
            adValue.CurrencyCode));
    };
    // Raised when an impression is recorded for an ad.
    _bannerView.OnAdImpressionRecorded += () =>
    {
        Debug.Log("Banner view recorded an impression.");
    };
    // Raised when a click is recorded for an ad.
    _bannerView.OnAdClicked += () =>
    {
        Debug.Log("Banner view was clicked.");
    };
    // Raised when an ad opened full screen content.
    _bannerView.OnAdFullScreenContentOpened += () =>
    {
        Debug.Log("Banner view full screen content opened.");
    };
    // Raised when the ad closed full screen content.
    _bannerView.OnAdFullScreenContentClosed += () =>
    {
        Debug.Log("Banner view full screen content closed.");
    };
}

إغلاق عرض البانر

عند الانتهاء من استخدام عرض البانر، احرص على الاتصال برقم Destroy() لتحرير موارد الإعلان.

/// <summary>
/// Destroys the banner view.
/// </summary>
public void DestroyAd()
{
    if (_bannerView != null)
    {
        Debug.Log("Destroying banner view.");
        _bannerView.Destroy();
        _bannerView = null;
    }
}

هذا كل شيء! أصبح تطبيقك جاهزًا الآن لعرض إعلانات البانر.

إعادة تحميل إعلان

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

ملاحظة: عند ضبط معدّل إعادة تحميل في واجهة مستخدِم "مدير إعلانات Google"، لا تحدث عملية إعادة التحميل التلقائية إلا إذا كان البانر مرئيًا على الشاشة.

أحجام البانر

يسرد الجدول أدناه أحجام البانر العادية.

الحجم بالنقاط (العرض × الارتفاع)	الوصف	مدى التوفّر	ثابت AdSize
320×50	بانر عادي	الهواتف والأجهزة اللوحية	BANNER
100x320	بانر كبير	الهواتف والأجهزة اللوحية	LARGE_BANNER
300×250	مستطيل متوسط وفقًا لمعايير IAB	الهواتف والأجهزة اللوحية	MEDIUM_RECTANGLE
468×60	بانر كامل الحجم وفقًا لمعيار IAB	الأجهزة اللوحية	FULL_BANNER
728×90	لوحة الصدارة في Interactive Advertising Bureau	الأجهزة اللوحية	LEADERBOARD
العرض المقدَّم × الارتفاع التكيُّفي	إعلان البانر التكيُّفي	الهواتف والأجهزة اللوحية	لا ينطبق
عرض الشاشة x ‏32|50|90	الإعلانات البانر الذكية	الهواتف والأجهزة اللوحية	SMART_BANNER
اطّلِع على مزيد من المعلومات عن إعلانات البانر التكيّفية، التي تمّ تصميمها لاستبدال إعلانات البانر الذكية.

ملاحظة: إذا حاول تطبيق Android تحميل بانر كبير جدًا بالنسبة إلى تنسيقه، لن يعرضه حِزمة تطوير البرامج (SDK)، وسيتم تسجيل رسالة خطأ بدلاً من ذلك.

أحداث التطبيقات

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

يمكنك الاستماع إلى أحداث التطبيقات المتعلّقة بخدمة "مدير إعلانات Google" باستخدام AppEvent. يمكن أن تحدث هذه الأحداث في أي وقت خلال دورة حياة الإعلان، حتى قبل طلب التحميل.

namespace GoogleMobileAds.Api.AdManager;

/// The App event message sent from the ad.
public class AppEvent
{
    // Name of the app event.
    string Name;
    // Argument passed from the app event.
    string Value;
}

يتمّ رفع OnAppEventReceived عند وقوع حدث تطبيق في إعلان. في ما يلي مثال على كيفية معالجة هذا الحدث في الرمز البرمجي:

_bannerview.OnAppEventReceived += (AppEvent args) =>
{
    Debug.Log($"Received app event from the ad: {args.Name}, {args.Value}.");
};

في ما يلي مثال يوضّح كيفية تغيير لون خلفية تطبيقك استنادًا إلى حدث تطبيق يحمل اسم color:

_bannerview.OnAppEventReceived += (AppEvent args) =>
{
  if (args.Name == "color")
  {
    Color color;
    if (ColorUtility.TryParseColor(arg.Value, out color))
    {
      gameObject.GetComponent<Renderer>().material.color = color;
    }
  }
};

في ما يلي تصميم الإعلان المقابل الذي يُرسِل حدث تطبيق التلوين:

<html>
<head>
  <script src="//www.gstatic.com/afma/api/v1/google_mobile_app_ads.js"></script>
  <script>
    document.addEventListener("DOMContentLoaded", function() {
      // Send a color=green event when ad loads.
      admob.events.dispatchAppEvent("color", "green");

      document.getElementById("ad").addEventListener("click", function() {
        // Send a color=blue event when ad is clicked.
        admob.events.dispatchAppEvent("color", "blue");
      });
    });
  </script>
  <style>
    #ad {
      width: 320px;
      height: 50px;
      top: 0px;
      left: 0px;
      font-size: 24pt;
      font-weight: bold;
      position: absolute;
      background: black;
      color: white;
      text-align: center;
    }
  </style>
</head>
<body>
  <div id="ad">Carpe diem!</div>
</body>
</html>

مراجع إضافية

• مثال HelloWorld: يعرض الحد الأدنى من تنفيذ جميع أشكال الإعلانات.