مواضع الإعلانات

يوضِّح لك هذا الدليل كيفية استخدام ميزة "مواضع الإعلانات" في المكوّن الإضافي لبرنامج Google Mobile Ads Unity من أجل إنشاء إعلانات لتطبيقك وعرضها.

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

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

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

using GoogleMobileAds.Api;
using System.Collections.Generic;
...
public class GoogleMobileAdsDemoScript : MonoBehaviour
{
    ...
    public void Start()
    {
        // Initialize the Mobile Ads SDK.
        MobileAds.Initialize((initStatus) =>
        {
            // SDK initialization is complete
        });
        ...
    }
}

إنشاء مواضع الإعلانات

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

لإضافة موضع إعلان جديد، انقر على الزر إضافة موضع إعلان جديد في نهاية القائمة. يمكنك ضبط موضع الإعلان من طريقة عرض "أداة الفحص".

ضبط موضع الإعلان

ولكل موضع إعلان الخصائص التالية:

اسم الموضع
اسم موضع الإعلان تُستخدَم لتحديد مواضع الإعلان عند إعداد الإعلانات في مشهد معيّن.
شكل الإعلان
إعلان بانر، إعلان بمكافأة، إعلان بيني نوع الإعلان.
رقم تعريف الوحدة الإعلانية
قدِّم رقم تعريف وحدة إعلانات البانر لنظامَي التشغيل Android وiOS. يجب تقديم رقم تعريف واحد على الأقل للوحدة الإعلانية.
مستمر في كل المشاهد
عند وضع علامة في مربّع الاختيار، سيبقى إعلان البانر ظاهرًا على الشاشة بغضّ النظر عن تغيّر المشهد (سلوك DontDestroyOnLoad نفسه).
تم تفعيل التحميل التلقائي
عند وضع علامة في هذا المربّع، سيتم تحميل الإعلان تلقائيًا عند تحميل مشهد مرتبط بموضع الإعلان.

تعرض لقطة الشاشة التالية مثالاً على موضع إعلان باسم بانر رائع.

إضافة AdGameObject إلى المشهد

يمكنك إضافة عنصر AdGameObject لأشكال إعلانات البانر أو الإعلانات البينية أو إعلانات الإعلانات بمكافأة إلى مشهدك باستخدام GameObject > إعلانات Google للأجهزة الجوّالة في Unity Editor. حدد التنسيق لإضافة موضع إلى المشهد النشط.

بعد إضافة AdGameObject إلى المشهد، سيظهر لك عنصر GameObject يمثل الإعلان في عرض "التدرّج الهرمي" لأداة تعديل الوحدة.

يمكنك تغيير اسم موضع الإعلان من خلال تغيير اسم GameObject بنفسه. تعرض لقطة الشاشة التالية مثالاً على AdGameObject باسم إعلان البانر.

إعدادات AdGameObject

يمكنك ضبط AdGameObject في المشهد من طريقة عرض "أداة الفحص" في إعدادات مكوّن Ad Game Object (النص البرمجي).

موضع الإعلان

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

إعدادات BannerAdGameObject (إعلان البانر فقط)

  • الحجم - اختَر حجم إعلان البانر الذي تريد استخدامه.
    • يوفّر إعلان البانر التكيُّفي الثابت بضعة خيارات إضافية:
      • الاتجاه - اختر اتجاه الجهاز المستخدَم لحساب ارتفاع الإعلان.
      • استخدام عرض ملء الشاشة - عند تحديد هذا الخيار، سيشغل البانر عرض ملء الشاشة. يمكنك ضبط النسبة المئوية لعرض الشاشة (من 50 % إلى 99%) إذا ألغيت تحديد الخيار استخدام عرض ملء الشاشة.
    • مخصّص: يسمح لك هذا الخيار بتوفير عرض البانر وارتفاعه.
  • موضع الإعلان - اختَر الموضع الذي يجب وضع إعلان البانر فيه.

عمليات معاودة الاتصال

يمكنك تنفيذ الدوال التي تتوافق مع عمليات استدعاء الإعلانات. على سبيل المثال، إذا كنت تريد التعامل مع تعذُّر تحميل إعلان بانر:

  1. أنشئ دالة متوافقة مع استدعاء الإعلان.

    public void OnBannerAdFailedToLoad(string reason) {
        Debug.Log("Banner ad failed to load: " + reason);
    }
    
  2. أرفِق النص البرمجي الذي يحتوي على الوظيفة أعلاه بأي عنصر من عناصر GameObject في المشهد.

  3. انقر على الزر +، ثم اسحب عنصر GameObject الذي أرفقت النص البرمجي إليه وأفلِته.

  4. اختر الدالة التي تريد ربطها باستدعاء الإعلان. بالنسبة إلى استدعاءات الإعلان التي تتضمن معلَمات، اختر الدالة لقبول المتغير الديناميكي حتى تتمكن من الحصول على قيمة المعلمة من حزمة تطوير البرامج (SDK).

استخدام AdGameObject من النص البرمجي

الحصول على مثيل AdGameObject من النص البرمجي

جميع كائنات AdGameObject لديها الطريقة المناسبة LoadAd(). سيؤدي ذلك إلى تحميل إعلان يحتوي على AdRequest عادي غير مستهدَف. لتطبيق الاستهداف، عليك استخدام LoadAd(AdRequest adRequest) باستخدام طلب الإعلان الذي تم إعداده.

للحصول على مثيل لـ AdGameObject، استخدم الطريقة التالية لكل شكل:

MobileAds.Instance.GetAd<BannerAdGameObject>("AD_GAMEOBJECT_NAME");

يتضمن الكائن BannerAdGameObject المعروض أيضًا الطريقتين الملائمتين Hide() وShow().

إعلان بيني

MobileAds.Instance.GetAd<InterstitialAdGameObject>("AD_GAMEOBJECT_NAME");

يتضمن الكائن InterstitialAdGameObject المعروض طريقة ملائمة ShowIfLoaded().

تم منح المكافأة

MobileAds.Instance.GetAd<RewardedAdGameObject>("AD_GAMEOBJECT_NAME");

يتضمن الكائن RewardedAdGameObject المعروض طريقة ملائمة ShowIfLoaded().

على سبيل المثال، يمكنك الحصول على مثيل لـ BannerAdGameObject وتحميله على النحو التالي:

using UnityEngine;

using GoogleMobileAds.Api;
using GoogleMobileAds.Placement;

public class BannerTestScript : MonoBehaviour
{
    BannerAdGameObject bannerAd;

    void Start()
    {
        bannerAd = MobileAds.Instance
            .GetAd<BannerAdGameObject>("AD_GAMEOBJECT_NAME");

        bannerAd.LoadAd();
        ...
    }
    ...
}

إذا كان هناك BannerAdGameObject باسم BannerAd، يمكنك الحصول على مثيل له على النحو التالي:

MobileAds.Instance.GetAd<BannerAdGameObject>("BannerAd");

الوصول إلى كائن الإعلان الأساسي في AdGameObject

توضّح هذه المقتطفات كيفية الوصول إلى كائن الإعلان الأساسي المرتبط بكائن AdGameObject.

BannerAdGameObject bannerAd = MobileAds.Instance
    .GetAd<BannerAdGameObject>("AD_GAMEOBJECT_NAME");

// Access BannerView object
BannerView bannerView = bannerAd.BannerView;

إعلان بيني

InterstitialAdGameObject interstitialAdGameObject = MobileAds.Instance
    .GetAd<InterstitialAdGameObject>("AD_GAMEOBJECT_NAME");

// Access InterstitialAd object
InterstitialAd interstitialAd = interstitialAdGameObject.InterstitialAd;

تم منح المكافأة

RewardedAdGameObject rewardedAdGameObject = MobileAds.Instance
    .Get<RewardedAdGameObject>("AD_GAMEOBJECT_NAME");

// Access RewardedAd object
RewardedAd rewardedAd = rewardedAdGameObject.RewardedAd;

أمثلة

عرض إعلان بيني

في ما يلي مثال على كيفية إعداد لعبة لتحميل إعلان بيني وعرضه باستخدام AdGameObject.

أضف InterstitialAdGameObject إلى المشهد وشغِّل ميزة تم تفعيل التحميل التلقائي، بحيث يتم تحميل الإعلان تلقائيًا عند تحميل المشهد.

بعد ذلك، تأكد من إعداد SDK باستخدام ما يلي. تجدر الإشارة إلى أنّ ميزة التحميل التلقائي في AdGameObject لن تعمل إذا نسيت إعداد حزمة تطوير البرامج (SDK).

ثم اعرض إعلانًا بينيًا بين انتقال الشاشة من خلال استدعاء دالة InterstitialAdGameObject.ShowIfLoaded(). تُظهر التعليمة البرمجية التالية مثالاً لعرض إعلان بيني بين انتقال المشهد.

using UnityEngine;
using UnityEngine.SceneManagement;

using GoogleMobileAds.Api;
using GoogleMobileAds.Placement;

public class MainScene : MonoBehaviour
{
    InterstitialAdGameObject interstitialAd;

    void Start()
    {
        interstitialAd = MobileAds.Instance
            .GetAd<InterstitialAdGameObject>("interstitial");

        MobileAds.Initialize((initStatus) => {
            Debug.Log("Initialized MobileAds");
        });
    }

    public void OnClickShowGameSceneButton()
    {
        // Display an interstitial ad
        interstitialAd.ShowIfLoaded();

        // Load a scene named "GameScene"
        SceneManager.LoadScene("GameScene");
    }
}

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

إذا كنت تريد طلب إعلان يدويًا، أوقِف ميزة التحميل التلقائي من "أداة فحص مواضع الإعلانات" واستدعِ الدالة InterstitialAdGameObject.LoadAd() بدلاً من ذلك. يعرض مقتطف الرمز التالي كيفية طلب إعلان يدويًا.

public class MainScene : MonoBehaviour
{
    InterstitialAdGameObject interstitialAd;

    void Start()
    {
        interstitialAd = MobileAds.Instance
            .GetAdGameObject<InterstitialAdGameObject>("interstitial");

        MobileAds.Initialize((initStatus) => {
            Debug.Log("MobileAds initialized");

            // Load an interstitial ad after the SDK initialization is complete
            interstitialAd.LoadAd();
        });
    }
    ...
}

حالة الزر "مشاهدة إعلان يضم مكافأة"

في ما يلي مثال على كيفية تفعيل زر "مشاهدة إعلان يضم مكافأة" باستخدام مواضع الإعلانات.

أضِف Button GameObject (يحمل اسم Button في هذا المثال) إلى المشهد، ليتم استخدامه لعرض إعلان يضم مكافأة. سنجعل هذا الزر متاحًا فقط عندما يكون الإعلان الذي يضم مكافأة متاحًا.

في طريقة Start()، يمكنك تغيير الحالة النشطة للزر إلى false. سيختفي هذا الزر من المشهد.

public class MainScene : MonoBehaviour
{
    ...
    void Start()
    {
        GameObject.Find("Button").SetActive(false);
        ...
    }
}

أضِف RewardedAdGameObject إلى المشهد واختَر إعلان عرض توضيحي بمكافأة لـ AdMob من القائمة المنسدلة.

ضمن قسم "طلبات معاودة الاتصال" في أداة فحص RewardedAdGameObject، انقر على الزر + من On Ad Loaded() لتفعيل طلب الدالة عند تحميل إعلان يضم مكافأة.

اسحب Button GameObject الذي أضفته في الخطوة السابقة وأفلِته في الحقل None (Object). حدد دالة ليتم طلبها من القائمة المنسدلة. انقر على No Function > GameObject > SetActive(bool)، ثم انقر على مربّع الاختيار لإرسال true كمَعلمة (استدعاء SetActive(true)).

في قسم "عمليات معاودة الاتصال" هذا، يمكنك أيضًا ربط حدث سيتم استدعاؤه عند تنشيط حدث RewardedAd.OnUserEarnedReward. لمزيد من التفاصيل، راجِع هذا القسم.

الخطوة التالية هي إنشاء الزر لعرض إعلان بمكافأة عند النقر عليه. من قسم استدعاءات On Click() في عارض الأزرار، انقر على الزر + واسحب عنصر GameObject لموضع الإعلان بمكافأة (المسمى الإعلان بمكافأة) في هذا المثال) وأفلته في الحقل None (Object) (بدون كائن).

بعد ذلك، أرفِق الدالة RewardedAdGameObject.ShowIfLoaded() بمعاودة الاتصال بالزر عند Click().

وأخيرًا، لا تنسَ إعداد حزمة تطوير البرامج (SDK). مقتطف التعليمة البرمجية التالي هو التعليمة البرمجية الكاملة للمشهد المستخدم في هذا المثال:

using UnityEngine;

using GoogleMobileAds.Api;

public class MainScene : MonoBehaviour
{
    void Start()
    {
        GameObject.Find("Button").SetActive(false);

        MobileAds.Initialize((initStatus) => {
            Debug.Log("Initialized MobileAds");
        });
    }
}

بمجرد تشغيل المشروع، سترى الزر معروضًا على المشهد عندما يتم تحميل إعلان بمكافأة ويكون جاهزًا للعرض.

ضبط معاودة الاتصال بمكافأة لـ RewardedAdGameObject

في ما يلي مثال على كيفية إعداد معاودة الاتصال بمكافأة في موضع إعلان بمكافأة حتى تتمكّن من منح مكافأة لمستخدم عند استدعاء دالة استدعاء.

أنشئ نصًا برمجيًا جديدًا وحدِّد دالة تقبل Reward كمَعلمة على النحو التالي.

using UnityEngine;
using GoogleMobileAds.Api;

class RewardedTestScript : MonoBehaviour {
    ...
    public void OnUserEarnedReward(Reward reward) {
        Debug.Log("OnUserEarnedReward: reward=" +
            reward.Type + ", amount=" + reward.Amount);
    }
    ...
}

أرفِق النص البرمجي RewardedTestScript بأي عنصر في GameObject (باستثناء موضع الإعلان GameObject) في المشهد. في هذا المثال، يتم إرفاقه بعنصر GameObject للكاميرا الرئيسية.

إضافة RewardedAdGameObject إلى المشهد. بعد ذلك، ضمن قسم "طلبات معاودة الاتصال" في فاحص RewardedAdGameObject، انقر على الزر + في المكافأة المكتسَبة من المستخدم لتفعيل طلب الوظيفة عند منح مكافأة لمستخدم.

اسحب "كائن GameObject" للكاميرا الرئيسية الذي أضفته في الخطوة السابقة وأفلِته في الحقل None (Object) (كائن). حدد دالة ليتم طلبها من القائمة المنسدلة. انقر على No Function (عدم استخدام دالة) > RewardedTestScript > OnUserBuyedReward.

بعد إدارة المشروع ومشاهدة إعلان يضم مكافأة، سيتم استدعاء RewardedTestScript.OnUserEarnedReward() عندما تحصل على مكافأة مقابل التفاعل مع الإعلان.