إضافة إعلان على شاشة فتح تطبيق AdMob إلى تطبيق Unity

1. مقدمة

في هذا الدرس العملي، ستنفّذ "إعلانًا على شاشة فتح التطبيق" من AdMob في تطبيق Unity.

ما ستنشئه

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

6338548c3f73e7cf.gif

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

ما ستتعلمه

  • كيفية إعداد إضافة "إعلانات Google على الأجهزة الجوّالة" في Unity
  • كيفية تنفيذ "إعلان على شاشة فتح التطبيق" في تطبيق Unity

المتطلبات

  • ‫Unity 2018.4 أو إصدار أحدث
  • ‫Xcode 12 أو إصدار أحدث وCocoaPods (للنشر على iOS)

ما هو تقييمك لمستوى خبرتك في AdMob؟

مبتدئ متوسط متقدّم

2. إعداد بيئة التطوير

تنزيل الرمز

بعد تنزيل ملف ZIP، استخرِج محتواه. سيكون لديك مجلد باسم admob-appopen-unity-main.

بدلاً من ذلك، يمكنك استنساخ مستودع GitHub من سطر الأوامر:

$ git clone https://github.com/googlecodelabs/admob-appopen-unity

يحتوي المستودع على مجلدَين:

  • android_studio_folder.png الرمز الأوّلي: الرمز الأوّلي الذي ستنشئه في هذا الدرس التطبيقي حول الترميز.
  • android_studio_folder.png complete: الرمز البرمجي المكتمل لهذا الدرس التطبيقي حول الترميز.

3- إعداد تطبيق يستخدم AdMob ووحدات إعلانية

بما أنّ Unity هي حزمة تطوير برامج (SDK) متعددة الأنظمة الأساسية، عليك إضافة تطبيق ووحدات إعلانية لكلّ من Android وiOS في AdMob.

الإعداد على أجهزة Android

لإعداد تطبيق Android، عليك إضافة تطبيق Android وإنشاء وحدات إعلانية.

إضافة تطبيق Android

  1. في وحدة تحكّم AdMob، انقر على إضافة تطبيق من قائمة التطبيقات.
  2. اختَر Android كنظام أساسي. عندما يُطلب منك الإجابة عن السؤال هل التطبيق مُدرَج في متجر تطبيقات معتمَد؟، انقر على لا.
  3. أدخِل AdMob app open ad في حقل اسم التطبيق.
  4. ليس من الضروري تفعيل مقاييس المستخدم لإكمال هذا الدرس العملي. ومع ذلك، ننصحك بإجراء ذلك لأنّه يتيح لك فهم سلوك المستخدمين بتفصيل أكبر. انقر على إضافة لإكمال العملية.

إنشاء وحدة إعلانية

  1. اختَر تطبيق يستخدم AdMob الإعلان على شاشة فتح التطبيق (Android) من قائمة التطبيقات في وحدة تحكّم AdMob.
  2. انقر على قائمة الوحدات الإعلانية.

  1. انقر على إضافة وحدة إعلانية.
  2. اختَر إعلان على شاشة فتح التطبيق كتنسيق.
  3. أدخِل android-appopen في حقل اسم الوحدة الإعلانية.
  4. انقر على إنشاء وحدة إعلانية لإكمال العملية.

عادةً ما يستغرق بدء عرض الإعلانات في وحدة إعلانية جديدة بضع ساعات.

إذا كنت تريد اختبار سلوك الإعلان على الفور، استخدِم رقم تعريف التطبيق الاختباري وأرقام تعريف الوحدات الإعلانية المُدرَجة في جداول رقم تعريف تطبيق Android/رقم تعريف الوحدة الإعلانية ورقم تعريف تطبيق iOS/رقم تعريف الوحدة الإعلانية.

إعداد تطبيق "خرائط Google" على أجهزة iOS

لإعداد نظام التشغيل iOS، عليك إضافة تطبيق iOS وإنشاء وحدات إعلانية.

إضافة تطبيق iOS

  1. في وحدة تحكّم AdMob، انقر على إضافة تطبيق من قائمة التطبيقات.
  2. اختَر iOS كنظام أساسي. عندما يُطلب منك الإجابة عن السؤال هل التطبيق مُدرَج في متجر تطبيقات معتمَد؟، انقر على لا.
  3. أدخِل AdMob app open ad في حقل اسم التطبيق.
  4. ليس من الضروري تفعيل مقاييس المستخدم لإكمال هذا الدرس العملي. ومع ذلك، ننصحك بإجراء ذلك لأنّه يتيح لك فهم سلوك المستخدمين بتفصيل أكبر. انقر على إضافة لإكمال العملية.

إنشاء وحدة إعلانية

  1. اختَر تطبيق الإعلانات المضمّنة في AdMob (iOS) من قائمة التطبيقات في وحدة تحكّم AdMob.
  2. انقر على قائمة الوحدات الإعلانية.

  1. انقر على إضافة وحدة إعلانية.
  2. اختَر إعلان على شاشة فتح التطبيق كتنسيق.
  3. أدخِل ios-appopen في حقل اسم الوحدة الإعلانية.
  4. انقر على إنشاء وحدة إعلانية لإكمال العملية.

عادةً ما يستغرق بدء عرض الإعلانات في وحدة إعلانية جديدة بضع ساعات.

إذا أردت اختبار سلوك الإعلان على الفور، استخدِم رقم تعريف التطبيق الاختباري وأرقام تعريف الوحدات الإعلانية المُدرَجة في الجدول التالي.

اختياري: استخدام تطبيق يستخدم AdMob ووحدات إعلانية تجريبية

إذا كنت تريد اتّباع الخطوات الواردة في درس تطبيقي حول الترميز بدلاً من إنشاء تطبيق يستخدم AdMob ووحدات إعلانية جديدة بنفسك، يمكنك استخدام معرّف تطبيق يستخدم AdMob الاختباري ومعرّفات الوحدات الإعلانية المُدرَجة في الجداول التالية.

معرّف تطبيق Android/معرّف الوحدة الإعلانية

السلعة

معرّف التطبيق/معرّف الوحدة الإعلانية

رقم تعريف التطبيق الذي يحقّق الربح عبر AdMob

ca-app-pub-3940256099942544~3347511713

رقم تعريف الوحدة الإعلانية

ca-app-pub-3940256099942544/3419835294

معرّف تطبيق iOS أو معرّف الوحدة الإعلانية

السلعة

معرّف التطبيق/معرّف الوحدة الإعلانية

رقم تعريف التطبيق الذي يحقّق الربح عبر AdMob

ca-app-pub-3940256099942544~1458002511

رقم تعريف الوحدة الإعلانية

ca-app-pub-3940256099942544/5662855259

لمزيد من المعلومات عن الإعلانات الاختبارية، يُرجى الاطّلاع على مستندات المطوّرين الخاصة بالإعلانات الاختبارية على Android والإعلانات الاختبارية على iOS.

4. إضافة المكوّن الإضافي "إعلانات Google على الأجهزة الجوّالة" في Unity

يُعدّ دمج إضافة "إعلانات Google على الأجهزة الجوّالة" في Unity الخطوة الأولى نحو عرض إعلانات AdMob وتحقيق الإيرادات.

تنزيل مكوّن Mobile Ads Unity الإضافي

تتيح إضافة "إعلانات Google على الأجهزة الجوّالة" في Unity للمطوّرين عرض "إعلانات Google على الأجهزة الجوّالة" بسهولة على تطبيقات Android وiOS. توفّر الإضافة واجهة C# ‎ لطلب الإعلانات تستخدمها نصوص C# ‎ البرمجية في مشروع Unity.

استخدِم الرابط أدناه لتنزيل حزمة Unity الخاصة بالمكوّن الإضافي.

فتح مشروع البداية

  1. افتح Unity Hub.
  2. في علامة التبويب المشاريع، انقر على الزر إضافة.
  3. انتقِل إلى المجلد الذي استخرجت فيه الرمز الذي تم تنزيله في خطوة إعداد بيئة التطوير.
  4. افتح مجلد starter.
  5. سيظهر مشروع البدء في قائمة المشاريع. انقر على المشروع لفتحه في Unity Editor.

استيراد مكوّن Mobile Ads Unity الإضافي

  1. في "محرّر Unity"، اختَر مواد العرض > استيراد حزمة > حزمة مخصّصة من القائمة.
  2. اختَر GoogleMobileAds-{VERSION}.unitypackage الذي نزّلته في الخطوة السابقة.
  3. تأكَّد من اختيار جميع الملفات وانقر على استيراد.

ضبط رقم تعريف تطبيقك الذي يستخدم AdMob

  1. في Unity Editor، اختَر مواد العرض (Assets) > "إعلانات Google على الأجهزة الجوّالة" (Google Mobile Ads) > الإعدادات (Settings) من القائمة.
  2. أدخِل رقم تعريف تطبيق يستخدم AdMob على Android وiOS في كل حقل. إذا كنت تريد اتّباع الخطوات الواردة في دليل التدريب العملي بدلاً من إنشاء تطبيق يستخدم AdMob ووحدات إعلانية جديدة بنفسك، أدخِل رقم تعريف تطبيق الاختبار على AdMob على النحو التالي.

8890521e199b1090.png

5- إنشاء فئة أدوات

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

AppOpenAdManager.cs

using System;
using GoogleMobileAds.Api;
using UnityEngine;

public class AppOpenAdManager
{
#if UNITY_ANDROID
    // Test ad unit ID: ca-app-pub-3940256099942544/3419835294
    private const string AD_UNIT_ID = "<YOUR_ANDROID_APPOPEN_AD_UNIT_ID>";
#elif UNITY_IOS
    // Test ad unit ID: ca-app-pub-3940256099942544/5662855259
    private const string AD_UNIT_ID = "<YOUR_IOS_APPOPEN_AD_UNIT_ID>";
#else
    private const string AD_UNIT_ID = "unexpected_platform";
#endif

    private static AppOpenAdManager instance;

    private AppOpenAd ad;

    private bool isShowingAd = false;

    public static AppOpenAdManager Instance
    {
        get
        {
            if (instance == null)
            {
                instance = new AppOpenAdManager();
            }

            return instance;
        }
    }

    private bool IsAdAvailable
    {
        get
        {
            return ad != null;
        }
    }

    public void LoadAd()
    {
        // TODO: Load an app open ad.
    }
}

تحميل إعلان

يتم تحميل الإعلان باستخدام الطريقة الثابتة AppOpenAd.LoadAd(). تتطلّب طريقة التحميل رقم تعريف وحدة إعلانية ووضع ScreenOrientation وعنصر AdRequest ومعالج إكمال يتم استدعاؤه عند نجاح تحميل الإعلان أو تعذّره.

يتم توفير عنصر AppOpenAd الذي تم تحميله كمَعلمة في معالج الإكمال. نفِّذ الطريقة LoadAd() على النحو التالي.

AppOpenAdManager.cs

public class AppOpenAdManager
{
    ...

    public void LoadAd()
    {
        AdRequest request = new AdRequest.Builder().Build();

        // Load an app open ad for portrait orientation
        AppOpenAd.LoadAd(AD_UNIT_ID, ScreenOrientation.Portrait, request, ((appOpenAd, error) =>
        {
            if (error != null)
            {
                // Handle the error.
                Debug.LogFormat("Failed to load the ad. (reason: {0})", error.LoadAdError.GetMessage());
                return;
            }

            // App open ad is loaded.
            ad = appOpenAd;
        }));
    }
}

عرض الإعلان

قبل عرض الإعلان، عليك التسجيل في كل معالج أحداث للاستماع إلى كل حدث إعلان.

AppOpenAdManager.cs

public class AppOpenAdManager
{
    ...

    public void ShowAdIfAvailable()
    {
        if (!IsAdAvailable || isShowingAd)
        {
            return;
        }

        ad.OnAdDidDismissFullScreenContent += HandleAdDidDismissFullScreenContent;
        ad.OnAdFailedToPresentFullScreenContent += HandleAdFailedToPresentFullScreenContent;
        ad.OnAdDidPresentFullScreenContent += HandleAdDidPresentFullScreenContent;
        ad.OnAdDidRecordImpression += HandleAdDidRecordImpression;
        ad.OnPaidEvent += HandlePaidEvent;

        ad.Show();
    }

    private void HandleAdDidDismissFullScreenContent(object sender, EventArgs args)
    {
        Debug.Log("Closed app open ad");
        // Set the ad to null to indicate that AppOpenAdManager no longer has another ad to show.
        ad = null;
        isShowingAd = false;
        LoadAd();
    }

    private void HandleAdFailedToPresentFullScreenContent(object sender, AdErrorEventArgs args)
    {
        Debug.LogFormat("Failed to present the ad (reason: {0})", args.AdError.GetMessage());
        // Set the ad to null to indicate that AppOpenAdManager no longer has another ad to show.
        ad = null;
        LoadAd();
    }

    private void HandleAdDidPresentFullScreenContent(object sender, EventArgs args)
    {
        Debug.Log("Displayed app open ad");
        isShowingAd = true;
    }

    private void HandleAdDidRecordImpression(object sender, EventArgs args)
    {
        Debug.Log("Recorded ad impression");
    }

    private void HandlePaidEvent(object sender, AdValueEventArgs args)
    {
        Debug.LogFormat("Received paid event. (currency: {0}, value: {1}",
                args.AdValue.CurrencyCode, args.AdValue.Value);
    }
}

تحديد تاريخ انتهاء صلاحية الإعلان

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

لضمان عدم عرض إعلان منتهي الصلاحية، عدِّل السمة IsAdAvailable إلى AppOpenAdManager التي تتحقّق من المدة المنقضية منذ تحميل إعلانك. بعد ذلك، استخدِم هذه الطريقة للتحقّق ممّا إذا كان الإعلان لا يزال صالحًا.

AppOpenAdManager.cs

public class AppOpenAdManager
{
    ...

    // TODO: Add loadTime field
    private DateTime loadTime;

    private bool IsAdAvailable
    {
        get
        {
            // TODO: Consider ad expiration
            return ad != null && (System.DateTime.UtcNow - loadTime).TotalHours < 4;
        }
    }

    public void LoadAd()
    {
        if (IsAdAvailable)
        {
            return;
        }

        AdRequest request = new AdRequest.Builder().Build();
        AppOpenAd.LoadAd(AD_UNIT_ID, ScreenOrientation.Portrait, request, ((appOpenAd, error) =>
        {
            if (error != null)
            {
                Debug.LogFormat("Failed to load the ad. (reason: {0})", error.LoadAdError.GetMessage());
                return;
            }

            ad = appOpenAd;
            Debug.Log("App open ad loaded");

            // TODO: Keep track of time when the ad is loaded.
            loadTime = DateTime.UtcNow;
        }));
    }
}

6. تعديل المشهد لتحميل الإعلان أو عرضه

عدِّل طريقة Start() في فئة MainScene لتحميل إعلان على شاشة فتح التطبيق عند بدء المشهد.

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

MainScene.cs

using GoogleMobileAds.Api;
using GoogleMobileAds.Common;
using UnityEngine;

public class MainScene : MonoBehaviour
{
    public void Start()
    {
        // TODO: Request an app open ad.
        MobileAds.Initialize((initStatus) =>
        {
            AppOpenAdManager.Instance.LoadAd();
            AppStateEventNotifier.AppStateChanged += OnAppStateChanged;
        });
    }

    public void OnAppStateChanged(AppState state)
    {
        if (state == AppState.Foreground)
        {
            // TODO: Show an app open ad if available.
            AppOpenAdManager.Instance.ShowAdIfAvailable();
        }
    }
}

هذا كل شيء! إنشاء المشروع وتشغيله على جهاز أو محاكي بعد تشغيل التطبيق، انتظِر بضع ثوانٍ للسماح بتحميل الإعلان بالكامل.

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

6338548c3f73e7cf.gif

7. أكملت الخطوات بنجاح

لقد أكملت تجربة البرمجة. يمكنك العثور على الرمز البرمجي المكتمل لهذا الدرس التطبيقي حول الترميز في المجلد android_studio_folder.pngcomplete.