Crea eventos personalizados

Selecciona la plataforma: Android Android iOS Unity

Los eventos personalizados permiten que los publicadores que usan la mediación de Ad Manager agreguen la mediación en cascada para una red de publicidad externa que no sea una de las redes de publicidad admitidas. En esta guía, se explica cómo usar un evento personalizado existente creado para iOS y Android en un proyecto de Unity.

Requisitos previos

Antes de continuar, haz lo siguiente:

• Configura Google Mobile Ads Unity Plugin. Tu app de Unity ya debería tener importado el complemento de Google Mobile Ads para Unity.

• Los adaptadores de eventos personalizados ya están compilados para iOS y Android. Para crear adaptadores de eventos personalizados, consulta nuestras guías de eventos personalizados en iOS y Android.

Define un evento personalizado

Para que un evento personalizado participe en la mediación, debe definirse en la interfaz web de Ad Manager. Agrega un evento personalizado a tus grupos de mediación de iOS y Android.

Importa bibliotecas de eventos personalizados

Es posible que los eventos personalizados requieran que se incluyan bibliotecas adicionales para que funcionen correctamente. Por ejemplo, es posible que debas incluir las siguientes bibliotecas:

• SDK de terceros para Android
• Evento personalizado de terceros para Android
• SDK de anuncios de terceros para iOS
• Evento personalizado de terceros para iOS

Tipos de bibliotecas

Existen varias formas de importar código de iOS o Android a un proyecto de Unity, incluidas las siguientes:

• Importar artefactos precompilados de iOS o Android con External Dependency Manager para Unity
• Importar complementos de AAR y bibliotecas de Android
• Importar archivos fuente de Java y Kotlin
• Importar archivos fuente y bibliotecas estáticas de iOS

Según cómo se empaqueten las bibliotecas que usas, es posible que necesites una estrategia de importación diferente para cada biblioteca. Cada opción se analiza con más detalle más adelante.

(Recomendado) Importa artefactos precompilados de iOS o Android

Importa artefactos precompilados de Maven o CocoaPods con el External Dependency Manager para Unity. Este complemento se incluye con el complemento GoogleMobileAds.

Para importar artefactos existentes, crea un archivo de configuración para definir tus importaciones. El nombre y la ruta de acceso del archivo tienen los siguientes requisitos:

• El archivo debe existir en la carpeta /Editor/.
• El nombre del archivo debe terminar con Dependencies.xml.

Por ejemplo, para importar los adaptadores de eventos personalizados para una red de publicidad hipotética llamada AdPub, crea el archivo:

Assets/AdPub/Editor/AdPubDependencies.xml

A continuación, define tus dependencias dentro del archivo AdPubDependencies.xml. Las reglas para configurar las importaciones se pueden encontrar en External Dependency Manager para Unity: Cómo comenzar. El siguiente fragmento de código incluye el SDK de iOS y Android, y las bibliotecas de eventos personalizados para una red de publicidad hipotética "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>

Si tu artefacto de evento personalizado ya tiene una dependencia en el SDK de la red de publicidad requerida, no necesitas definir la dependencia del SDK de forma explícita: Ejemplo

External Dependency Manager supervisa automáticamente los cambios de configuración y resuelve las dependencias. También puedes ejecutar la resolución manual con el siguiente comando de menú:

Assets > External Dependency Manager > Android Resolver > Force Resolve

Importa complementos de AAR y bibliotecas de Android

Unity admite la importación de archivos *.aar, así como proyectos de bibliotecas de Android. Si tu evento personalizado de Android se empaqueta de esta manera, consulta Complementos de AAR y bibliotecas de Android para obtener instrucciones sobre cómo incluir esos archivos en tu proyecto de Unity.

Importa archivos fuente de Java y Kotlin

A partir de Unity 2018.2 o versiones posteriores, si el código de tu evento personalizado de Android incluye archivos *.java o *.kt no compilados, puedes usar archivos fuente de Java o Kotlin como complementos.

Importa archivos fuente y bibliotecas estáticas de iOS

Unity admite artefactos *.framework, archivos fuente *.h y *.m. La importación de artefactos y archivos fuente de iOS se explica en la guía de Unity para complementos nativos.

Prueba eventos personalizados con el inspector de anuncios

El inspector de anuncios se puede usar para probar que los eventos personalizados se hayan importado correctamente a tu aplicación. El inspector de anuncios se puede abrir solo con gestos o de forma programática con un código mínimo.

(Opcional) Llama a métodos nativos del SDK de terceros desde secuencias de comandos de C#

Es posible que los SDKs de redes de publicidad externas tengan requisitos especiales que requieran llamar a métodos de iOS o Android directamente. El proceso para llamar a estos métodos directamente es el siguiente:

1. Define una interfaz común para los clientes de la plataforma.
2. Implementa un cliente predeterminado para plataformas no compatibles.
3. Implementa un cliente de Android para llamar a métodos de Android.
4. Implementa un cliente de iOS para llamar a métodos de iOS.
5. Implementa una fábrica de clientes para cambiar de forma condicional entre clientes de iOS y Android.
6. Define una API para acceder a todas las funcionalidades del SDK de la red de publicidad externa.

En la siguiente sección, se muestra cómo se implementan estos pasos para una red de publicidad hipotética llamada "AdPub" en una API de C# que puede llamar a los métodos en iOS y Android:

package com.adpub.android;

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

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

Define una interfaz común para los clientes de la plataforma

Crea una interfaz IAdPubClient con un método que represente la API subyacente de iOS y Android.

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);
    }
}

Define un cliente predeterminado para plataformas no compatibles

Crea una clase DefaultClient que implemente la interfaz IAdPubClient que solo registre el nombre del método. Usa esta implementación para el editor de Unity y todas las plataformas que no sean iOS o Android.

Assets/AdPub/Common/DefaultClient.cs

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

Implementa un cliente de plataforma de iOS

Crea una clase iOSAdPubClient que implemente la interfaz IAdPubClient en iOS. Esta implementación usa InteropServices para llamar a el método setHasUserConsent() en la clase AdPubSdk de iOS.

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

A continuación, implementa el método GADUAdPubSetHasUserConsent() que se definió anteriormente. Crea AdPubClientBridge.m con un método C GADUAdPubSetHasUserConsent() para controlar la llamada de método desde Unity y, luego, invoca el AdPubSDK.

AdPubClientBridge es un archivo fuente de iOS y debe colocarse dentro de la carpeta Plugins/iOS, como se explica en la guía de Unity para complementos nativos.

Assets/AdPub/Plugins/iOS/AdPubClientBridge.m

#import <AdPubSDK/AdPubSDK.h>

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

Implementa un cliente de plataforma de Android

Crea una clase AndroidAdPubCient que implemente la interfaz IAdPubClient en Android. Esta implementación usa las clases auxiliares de Java de Android para llamar al método estático de Android setHasUserConsent().

Como las clases auxiliares de Java de Android solo están disponibles durante el tiempo de ejecución de Android, puedes evitar errores de compilación con la UNITY_ANDROID directiva del compilador para encapsular la clase como se muestra en el fragmento de código. Como alternativa, puedes usar definiciones de ensamblado en Unity 2017.4 y versiones posteriores para resolver este problema.

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

Crea un método de fábrica para mostrar la implementación correcta del cliente

Ahora que tienes implementaciones del cliente para cada plataforma, crea una clase AdPubClientFactory para mostrar la implementación correcta de la interfaz IAdPubClient según la plataforma de tiempo de ejecución. Esta clase usa directivas del compilador para mostrar el cliente IAdPubClientcorrecto.

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
        }
    }
}

Define una API pública para cada método de interfaz

Crea una clase AdPubApi que tenga llamadas a métodos para cada método de cliente en tu interfaz IAdPubClient. Esta clase usa AdPubClientFactory para obtener una instancia de IAdPubClient y llama a ese cliente para las funcionalidades subyacentes del 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);
        }
    }
}

Llama a tu API recién definida

A continuación, se muestra cómo puedes llamar a la API definida anteriormente:

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);
    }
}

Ejemplos adicionales de adaptadores de redes de publicidad externas

Visita el repositorio de Github del complemento de Google Mobile Ads para Unity para obtener ejemplos adicionales de adaptadores de mediación de terceros que implementan APIs de C# para encapsular llamadas a métodos de iOS y Android.