البدء

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

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

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

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

• الإصدار 7.0.0 أو إصدار أحدث من إضافة Google Mobile Ads Unity
• أكمِل دليل البدء.
• نزِّل إضافة "الإعلانات المدمجة مع المحتوى" وثبِّتها.

تحميل أشكال الإعلانات المدمجة مع المحتوى

يتم تحميل الإعلانات المدمجة مع المحتوى من خلال الفئة AdLoader، التي تتضمّن فئة AdLoader.Builder خاصة بها لتخصيصها أثناء الإنشاء. تضبط طريقة ForNativeAd() AdLoader للتعامل مع الإعلانات المدمجة مع المحتوى.

private void RequestNativeAd() {
    AdLoader adLoader = new AdLoader.Builder(INSERT_AD_UNIT_HERE)
        .ForNativeAd()
        .Build();
}

تسجيل أحداث الإعلانات في AdLoader

لتلقّي إشعار عند تحميل إعلان مدمج مع المحتوى بنجاح أو تعذُّر تحميله، أضِف عناصر تفويض إلى الفئة AdLoader للأحداث المدرَجة أدناه.

OnNativeAdLoaded

يتم استدعاؤه عند تحميل إعلان أصلي بنجاح. يجب توفُّر معالج لهذا الحدث للوصول إلى الإعلان الذي تم تحميله.

OnAdFailedToLoad

يتم استدعاء هذه الطريقة عندما يتعذّر تحميل إعلان مدمج مع المحتوى.

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

بعد الانتهاء من إنشاء AdLoader، استدعِ الدالة LoadAd() الخاصة به لطلب إعلان:

adLoader.LoadAd(new AdRequest.Builder().Build());

تجميع طلب الإعلان

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

private void RequestNativeAd() {
    AdLoader adLoader = new AdLoader.Builder(INSERT_AD_UNIT_HERE)
        .ForNativeAd()
        .Build();
    adLoader.OnNativeAdLoaded += this.HandleNativeAdLoaded;
    adLoader.OnAdFailedToLoad += this.HandleAdFailedToLoad;
    adLoader.LoadAd(new AdRequest.Builder().Build());
}

التعامل مع حالات تعذُّر تحميل الإعلانات

الحدث OnAdFailedToLoad هو من النوع EventHandle<AdFailedToLoadEventArgs>. في ما يلي طريقة تحليل سبب تعذُّر تحميل الإعلان من هذا الحدث.

private void RequestNativeAd() {
    ...
    adLoader.OnAdFailedToLoad += this.HandleNativeAdFailedToLoad;
}

private void HandleNativeAdFailedToLoad(object sender, AdFailedToLoadEventArgs args) {
    Debug.Log("Native ad failed to load: " + args.Message);
}

عرض إعلان مدمج مع المحتوى

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

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

الحدث OnNativeAdLoaded هو من النوع EventHandler<NativeAdEventArgs>. يمكن استرداد الإعلان، المضمّن في عنصر NativeAd، من NativeAdEventArgs كما هو موضّح أدناه:

private NativeAd nativeAd;
...
private void HandleNativeAdLoaded(object sender, NativeAdEventArgs args) {
    Debug.Log("Native ad loaded.");
    this.nativeAd = args.nativeAd;
}

استرداد مواد عرض الإعلانات المُدمَجة مع المحتوى

بعد تحميل الإعلانات، يمكن الوصول إلى مواد عرضها كما هو موضّح أدناه. يتم عرض مواد عرض الرسومات كعناصر Texture2D، ويتم عرض مواد عرض النصوص كعناصر string.

private bool nativeAdLoaded;
private NativeAd nativeAd;

void Update() {
    ...

    if (this.nativeAdLoaded) {
        this.nativeAdLoaded = false;
        // Get Texture2D for the icon asset of native ad.
        Texture2D iconTexture = this.nativeAd.GetIconTexture();

        // Get string for headline asset of native ad.
        string headline = this.nativeAd.GetHeadlineText();
    }
}

private void HandleNativeAdLoaded(object sender, NativeAdEventArgs args) {
    Debug.Log("Native ad loaded.");
    this.nativeAd = args.nativeAd;
    this.nativeAdLoaded = true;
}

يُرجى العِلم أنّه لا يمكن الوصول إلى مواد عرض الإعلانات إلا من سلسلة التعليمات الرئيسية، مثلاً، من الطريقة Update() لبرنامج نصي في Unity. يُرجى أيضًا ملاحظة أنّ مواد العرض التالية لا نضمن توفّرها دائمًا، ويجب التحقّق منها قبل عرضها:

• GetStarRating()
• GetStore()
• GetPrice()
• GetAdvertiser()
• GetIconTexture()

مادة عرض "خيارات الإعلان"

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

تسجيل GameObjects لمادة عرض الإعلان

يجب تسجيل GameObject لعرض مادة عرض الإعلان في تطبيق Unity. وفي حال نجاح التسجيل، تعرض الطريقة المستخدَمة لتسجيل GameObject القيمة bool. بالنسبة إلى List<GameObject>، تعرض الطريقة int يشير إلى عدد GameObject الذي تم تسجيله بنجاح.

في حال عدم نجاح تسجيل مادة عرض إعلان، لن يتم التعرّف على مرّات الظهور والنقرات على الإعلان الأصلي ذي الصلة.

if (!this.nativeAd.RegisterIconImageGameObject(icon))
{
    // Handle failure to register the icon ad asset.
}

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

في مقتطف الرمز البرمجي أدناه، تتم إضافة BoxCollider إلى GameObject التي تستخدم TextMesh لعرض مادة عرض عنوان الإعلان المُدمج مع المحتوى. بعد ربط BoxCollider بـ GameObject، سيتم تغيير حجمه تلقائيًا ليناسب نص العنصر TextMesh.

// Create GameObject that will display the headline ad asset.
GameObject headline = new GameObject();
headline.AddComponent<TextMesh>();
headline.GetComponent<TextMesh>().characterSize = 0.5 f;
headline.GetComponent<TextMesh>().anchor = TextAnchor.MiddleCenter;
headline.GetComponent<TextMesh>().color = Color.black;

// Get string of the headline asset.
string headlineText = this.nativeAd.GetHeadlineText();
headline.GetComponent<TextMesh>().text = headlineText;

// Add box collider to the GameObject which will automatically scale.
headline.AddComponent<BoxCollider>();

عرض توضيحي

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

private GameObject icon;
private bool nativeAdLoaded;
private NativeAd nativeAd;
...
void Update() {
    ...

    if (this.nativeAdLoaded) {
        this.nativeAdLoaded = false;
        // Get Texture2D for icon asset of native ad.
        Texture2D iconTexture = this.nativeAd.GetIconTexture();

        icon = GameObject.CreatePrimitive(PrimitiveType.Quad);
        icon.transform.position = new Vector3(1, 1, 1);
        icon.transform.localScale = new Vector3(1, 1, 1);
        icon.GetComponent<Renderer>().material.mainTexture = iconTexture;

        // Register GameObject that will display icon asset of native ad.
        if (!this.nativeAd.RegisterIconImageGameObject(icon))
        {
            // Handle failure to register ad asset.
        }
    }
}
...

private void HandleNativeAdLoaded(object sender, NativeAdEventArgs args) {
    Debug.Log("Native ad loaded.");
    this.nativeAd = args.nativeAd;
    this.nativeAdLoaded = true;
}