Создавайте собственные события

Пользовательские события позволяют издателям, использующим медиацию AdMob, добавлять каскадную медиацию для сторонней рекламной сети, которая не входит в число поддерживаемых . В этом руководстве объясняется, как использовать существующее пользовательское событие, созданное для Android и iOS, в проекте Unity.

Предпосылки

• Завершите начало работы . В вашем приложении Unity уже должен быть импортирован плагин Google Mobile Ads для Unity.

• Адаптеры событий уже созданы для Android и iOS. Чтобы создать адаптеры событий, обратитесь к нашим руководствам по созданию пользовательских событий для Android и iOS .

Определить пользовательское событие

Чтобы пользовательское событие участвовало в медиации, его необходимо определить в веб-интерфейсе AdMob. Добавьте пользовательское событие в группы медиации как для Android, так и для iOS.

На этом снимке экрана показаны некоторые примеры пользовательских настроек событий:

Как заполнить параметры
Имя класса (iOS)	Для iOS введите имя класса, реализующего пользовательское событие. Если ваш класс реализован на Swift, вам необходимо добавить к имени класса префикс в виде имени его модуля приложения/фреймворка (например, appName.className ). Имя цели обязательно, если в вашем проекте несколько целей или если имя проекта отличается от имени цели. С именем цели оно будет выглядеть так: appName_targetName.className . Кроме того, не забудьте заменить все символы, не являющиеся буквами и цифрами, например, дефисы, на подчёркивания.
Имя класса (Android)	Для Android убедитесь, что значение, которое вы указываете для Class Name является полным именем класса для Android (например, com.google.ads.mediation.sample.customevent.SampleCustomEvent ).
Этикетка	Введите уникальное название события.
Параметр	Если вы хотите передать строковый аргумент вашему пользовательскому событию, например идентификатор рекламного блока.

Импорт пользовательских библиотек событий

Для корректной работы пользовательских событий может потребоваться включение дополнительных библиотек. Например, вам может потребоваться включить следующие библиотеки:

• Android SDK сторонних разработчиков
• Пользовательское событие сторонних разработчиков Android
• iOS сторонний рекламный SDK
• Стороннее пользовательское событие iOS

Типы библиотек

Существует несколько способов импортировать код Android или iOS в проект Unity, включая:

• Импорт готовых артефактов Android или iOS с помощью внешнего менеджера зависимостей для Unity
• Импорт плагинов AAR и библиотек Android
• Импорт исходных файлов Java и Kotlin
• Импорт исходных файлов iOS и статических библиотек

В зависимости от того, как упакованы используемые вами библиотеки, вам может потребоваться разная стратегия импорта для каждой библиотеки. Каждый вариант будет подробно рассмотрен далее.

(Рекомендуется) Импортируйте готовые артефакты Android или iOS

Импортируйте готовые артефакты из Maven или CocoaPods с помощью диспетчера внешних зависимостей для Unity . Этот плагин входит в состав плагина GoogleMobileAds.

Чтобы импортировать существующие артефакты, создайте файл конфигурации, определяющий импорт. Имя файла и путь к нему должны соответствовать следующим требованиям:

• Файл должен находиться в папке /Editor/ .
• Имя файла должно заканчиваться на Dependencies.xml .

Например, чтобы импортировать адаптеры пользовательских событий для гипотетической рекламной сети с именем AdPub , создайте файл:

Assets/AdPub/Editor/AdPubDependencies.xml

Затем определите зависимости в файле AdPubDependencies.xml . Правила настройки импорта можно найти в статье «External Dependency Manager for Unity Getting Started» . Следующий фрагмент кода включает SDK для Android и iOS, а также библиотеки пользовательских событий для гипотетической рекламной сети AdPub.

Assets/AdPub/Editor/AdPubDependencies.xml

<dependencies>
  <androidPackages>
    <androidPackage spec="com.adpub.android:adpub-sdk:1.0.0" />
    <androidPackage spec="com.adpub.android:adpub-custom-event:1.0.0">
      <repositories>
        <repository>https://repo.maven.apache.org/maven2/</repository>
        <repository>https://dl.google.com/dl/android/maven2/</repository>
      </repositories>
    </androidPackage>
  </androidPackages>
  <iosPods>
    <iosPod name="AdPubSDK" version="1.0" />
    <iosPod name="AdPubCustomEvent" version="1.0">
      <sources>
        <source>https://github.com/CocoaPods/Specs</source>
      </sources>
    </iosPod>
  </iosPods>
</dependencies>

Если ваш артефакт пользовательского события уже имеет зависимость от требуемого SDK рекламной сети, вам не нужно явно определять зависимость SDK: Пример

Менеджер внешних зависимостей автоматически отслеживает изменения конфигурации и разрешает зависимости. Вы также можете выполнить разрешение вручную с помощью следующей команды меню:

Assets > External Dependency Manager > Android Resolver > Force Resolve

Импорт плагинов AAR и библиотек Android

Unity поддерживает импорт файлов *.aar , а также проектов библиотек Android. Если ваше пользовательское событие Android упаковано таким образом, см . раздел «Плагины AAR и библиотеки Android» для получения инструкций по включению этих файлов в проект Unity.

Импорт исходных файлов Java и Kotlin

Начиная с Unity 2018.2 или более поздней версии, если ваш код пользовательского события Android состоит из нескомпилированных файлов *.java или *.kt , вы можете использовать исходные файлы Java или Kotlin в качестве подключаемых модулей .

Импорт исходных файлов iOS и статических библиотек

Unity поддерживает артефакты *.framework , а также исходные файлы *.h и *.m . Импорт артефактов и исходных файлов iOS описан в руководстве Unity по нативным плагинам .

Тестируйте пользовательские события с помощью инспектора рекламы

Инспектор рекламы можно использовать для проверки корректности импорта пользовательских событий в приложение. Инспектор рекламы можно открыть с помощью жестов или программно, с минимальным количеством кода.

(Необязательно) Вызов собственных методов стороннего SDK из скриптов C#

У SDK сторонних рекламных сетей могут быть особые требования, требующие прямого вызова методов Android или iOS. Процесс прямого вызова этих методов выглядит следующим образом:

1. Определить общий интерфейс для клиентов платформы
2. Реализовать клиент по умолчанию для неподдерживаемых платформ
3. Реализовать Android-клиент для вызова методов Android
4. Реализовать клиент iOS для вызова методов iOS
5. Реализовать клиентскую фабрику для условного переключения между клиентами iOS и Android.
6. Определить API для доступа ко всем функциям SDK сторонних рекламных сетей.

В следующем разделе показано, как эти шаги реализуются для гипотетической рекламной сети под названием «AdPub» в API C#, который может вызывать методы на Android и iOS:

Андроид

package com.adpub.android;

public class AdPubSdk
{
    public static void setHasUserConsent(boolean hasUserConsent);
}

iOS

@interface AdPubSdk : NSObject
+ (void)setHasUserConsent:(BOOL)hasUserConsent;
@end

Определить общий интерфейс для клиентов платформы

Создайте интерфейс IAdPubClient с методом, представляющим базовый API Android и iOS.

Assets/AdPub/Common/IAdPubClient.cs

namespace AdPub.Common
{
    public interface IAdPubClient
    {
        ///<summary>
        /// Sets a flag indicating if the app has user consent for advertisement.
        ///</summary>
        void SetHasUserConsent(bool hasUserConsent);
    }
}

Определить клиент по умолчанию для неподдерживаемых платформ

Создайте класс DefaultClient , реализующий интерфейс IAdPubClient , который просто регистрирует имя метода. Используйте эту реализацию для редактора Unity и всех платформ, кроме Android и iOS.

Assets/AdPub/Common/DefaultClient.cs

namespace AdPub.Common
{
    public class DefaultClient : IAdPubClient
    {
        public void SetHasUserConsent(bool hasUserConsent)
        {
            Debug.Log("SetHasUserConsent was called.");
        }
    }
}

Реализовать клиент для платформы iOS

Создайте класс iOSAdPubClient , реализующий интерфейс IAdPubClient в iOS. Эта реализация использует InteropServices для вызова метода setHasUserConsent() в классе iOS AdPubSdk .

Assets/AdPub/Platforms/iOS/iOSAdPubClient.cs

// Wrap this class in a conditional operator to make sure it only runs on iOS.
#if UNITY_IOS

// Reference InteropServices to include the DLLImportAttribute type.
using System.Runtime.InteropServices;

using AdPub.Common;

namespace AdPub.Platforms.Android
{
    public class iOSAdPubClient : IAdPubClient
    {
        public void SetHasUserConsent(bool hasUserConsent)
        {
            GADUAdPubSetHasUserConsent(hasUserConsent);
        }

        [DllImport("__Internal")]
        internal static extern void GADUAdPubSetHasUserConsent(bool hasUserConsent);
    }
}
#endif

Затем реализуйте метод GADUAdPubSetHasUserConsent() определённый выше. Создайте AdPubClientBridge.m с C методом GADUAdPubSetHasUserConsent() для обработки вызова метода из Unity и вызовите AdPubSDK .

AdPubClientBridge — это исходный файл iOS, который необходимо поместить в папку Plugins/iOS как описано в руководстве Unity по собственным подключаемым модулям .

Assets/AdPub/Plugins/iOS/AdPubClientBridge.m

#import <AdPubSDK/AdPubSDK.h>

void GADUAdPubSetHasUserConsent(BOOL hasUserConsent) {
  [AdPubSDK setHasUserConsent:hasUserConsent];
}

Реализовать клиент для платформы Android

Создайте класс AndroidAdPubCient , реализующий интерфейс IAdPubClient на Android. Эта реализация использует вспомогательные классы Java для вызова статического метода Android setHasUserConsent() .

Поскольку вспомогательные классы Java для Android доступны только во время выполнения Android, вы можете предотвратить ошибки компиляции, используя директиву компилятора UNITY_ANDROID для обертывания класса, как показано во фрагменте кода. Кроме того, для решения этой проблемы можно использовать определения Assembly в Unity 2017.4 и более поздних версиях.

Assets/AdPub/Platforms/Android/AndroidAdPubClient.cs

// Wrap this class in a conditional operator to make sure it only runs on Android.
#if UNITY_ANDROID

// Reference the UnityEngine namespace which contains the JNI Helper classes.
using UnityEngine;

using AdPub.Common;

namespace AdPub.Platforms.Android
{
    public class AndroidAdPubClient : IAdPubClient
    {
        public void SetHasUserConsent(bool hasUserConsent)
        {
             // Make a reference to the com.adpub.AdPubSDK.
            AndroidJavaClass adPubSdk = new AndroidJavaClass("com.adpub.AdPubSdk");

            // Call the native setHasUserConsent method of com.adpub.AdPubSDK.
            adPubSdk.CallStatic("setHasUserConsent", hasUserConsent);
        }
    }
}
#endif

Создайте фабричный метод для возврата корректной реализации клиента.

Теперь, когда у вас есть реализации клиента для каждой платформы, создайте класс AdPubClientFactory , который будет возвращать корректную реализацию интерфейса IAdPubClient в зависимости от платформы выполнения. Этот класс использует директивы компилятора для возврата корректного клиента IAdPubClient .

Assets/AdPub/Common/AdPubClientFactory.cs

namespace AdPub.Common
{
    public class AdPubClientFactory
    {
        // Return the correct platform client.
        public static IAdPubClient GetClient()
        {
#if   !UNITY_EDITOR && UNITY_ANDROID
            return new AdPub.Platforms.Android.AndroidAdPubClient();
#elif !UNITY_EDITOR && UNITY_IOS
            return new AdPub.Platforms.iOS.iOSAdPubClient();
#else
            // Returned for the Unity Editor and unsupported platforms.
            return new DefaultClient();
#endif
        }
    }
}

Определить общедоступный API для каждого метода интерфейса.

Создайте класс AdPubApi , содержащий вызовы методов для каждого клиентского метода в интерфейсе IAdPubClient . Этот класс использует AdPubClientFactory для получения экземпляра IAdPubClient и вызывает этот клиент для использования базовых функций SDK.

Assets/AdPub/AdPubApi.cs

using AdPub.Common;

namespace AdPub
{
    public class AdPubApi
    {
        private static readonly IAdPubClient client = GetAdPubClient();

        // Returns the correct client for the current runtime platform.
        private static IAdPubClient GetAdPubClient()
        {
            return AdPubClientFactory.GetClient();
        }

        // Sets the user consent using the underlying SDK functionality.
        public static void SetHasUserConsent(bool hasUserConsent)
        {
            client.SetHasUserConsent(hasUserConsent);
        }
    }
}

Вызовите ваш новый API

Вот как можно вызвать API, определенный выше:

Assets/Scripts/AdPubController.cs

using UnityEngine;
using AdPub;

public class AdPubController : MonoBehaviour
{
    // TODO: Get consent from the user and update this userConsent field.
    public bool userConsent;

    // Called on startup of the GameObject it's assigned to.
    public void Start()
    {
        // Pass the user consent to AdPub.
        AdPubApi.SetHasUserConsent(userConsent);
    }
}

Дополнительные примеры сторонних сетевых адаптеров рекламы

Посетите репозиторий Github плагина Google Mobile Ads Unity для дополнительных примеров сторонних адаптеров-посредников, реализующих API C# для обертывания вызовов методов iOS и Android.