Crear eventos personalizados

Con los eventos personalizados, los editores pueden usar la función Mediación de AdMob para añadir a la mediación en cascada una red publicitaria de terceros que no sea una de las redes admitidas de AdMob. En esta guía se explica cómo utilizar un evento personalizado desarrollado para Android y iOS en un proyecto de Unity.

Requisitos previos

  • Hacer todo lo que se indica en la guía Primeros pasos. Tu aplicación Unity ya debería tener importado el complemento para Unity de anuncios de Google para móviles.

  • Tener adaptadores de eventos personalizados ya desarrollados para Android y iOS. Para crear adaptadores de eventos personalizados, consulta las guías de eventos personalizados para Android y iOS.

Definir un evento personalizado

Para que un evento personalizado participe en la mediación, este debe definirse en la interfaz de usuario de AdMob. Añade un evento personalizado a tus grupos de mediación de Android y iOS.

En esta captura de pantalla se muestran algunos ejemplos de ajustes de eventos personalizados:

Cómo rellenar parámetros
Nombre de clase (iOS)

En dispositivos iOS, indica el nombre de la clase que implementa el evento personalizado.

Si el lenguaje con el que has implementado tu clase es Swift, debes añadir al nombre de la clase un prefijo que indique el módulo de la aplicación o del framework (por ejemplo, appName.className).

Si el proyecto tiene varios destinos o no se llama igual que el destino seleccionado, debes indicar el nombre del destino en cuestión. Con el nombre de destino, el aspecto sería el siguiente: appName_targetName.className. Además, recuerda que tienes que sustituir todos los caracteres no alfanuméricos, como los guiones, por guiones bajos.

Nombre de clase (Android) En dispositivos Android, asegúrate de que el valor que asignes a Class Name sea el nombre completo de la clase que se corresponda con Android (por ejemplo, com.google.ads.mediation.sample.customevent.SampleCustomEvent).
Etiqueta Introduce un nombre único para el evento.
Parámetro Si quieres transferir un argumento de cadena a tu evento personalizado, como un ID de bloque de anuncios.

Importar bibliotecas de eventos personalizados

Es posible que, para que los eventos personalizados funcionen correctamente, deban añadirse otras bibliotecas. Por ejemplo, se pueden incluir bibliotecas para lo siguiente:

  • Un SDK de terceros para Android
  • Un evento personalizado de terceros para Android
  • Un SDK de anuncios de terceros para iOS
  • Un evento personalizado de terceros para iOS

Tipos de bibliotecas

Hay muchas formas de importar el código de Android o iOS en un proyecto de Unity. A continuación, indicamos algunas:

  • Importar artefactos de Android y iOS predefinidos mediante External Dependency Manager for Unity
  • Importar complementos de RAA y bibliotecas de Android
  • Importar archivos fuente de Java y Kotlin
  • Importar bibliotecas estáticas y archivos fuente de iOS

En función de cómo se empaqueten las bibliotecas que uses, es posible que necesites una estrategia de importación diferente para cada una de ellas. A continuación se explica con más detalle cada opción.

Importa artefactos predefinidos de Maven o CocoaPods con External Dependency Manager for Unity, un complemento que se incluye con GoogleMobileAds.

Para importar artefactos, crea un archivo de configuración y define las importaciones. El nombre y la ruta de este archivo tienen unos requisitos concretos:

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

Por ejemplo, para importar adaptadores de eventos personalizados en una red publicitaria ficticia con el nombre AdPub, crea el archivo:

Assets/AdPub/Editor/AdPubDependencies.xml

A continuación, define tus dependencias dentro del archivo AdPubDependencies.xml. Encontrarás las reglas para configurar las importaciones en la guía de Introducción a External Dependency Manager for Unity. El fragmento de código que aparece a continuación incluye el SDK de Android o iOS y las bibliotecas de eventos personalizados para la red publicitaria ficticia "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>

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

Assets > External Dependency Manager > Android Resolver > Force Resolve

Importar complementos de RAA y bibliotecas de Android

Con Unity puedes importar archivos *.aar y proyectos de la biblioteca de Android. Si tu evento personalizado se empaqueta en este modo, consulta la página sobre complementos de RAA y bibliotecas de Android para obtener instrucciones acerca de cómo incluir esos archivos en tu proyecto de Unity.

Importar archivos fuente de Java y Kotlin

Si tienes la versión de Unity 2018.2 o una posterior y tu código de evento personalizado de Android está compuesto por archivos *.java o *.kt sin compilar, puedes usar los archivos fuente de Java o Kotlin como complementos.

Importar archivos fuente de iOS y bibliotecas estáticas

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

Hacer pruebas en eventos personalizados con Inspector de anuncios

La función Inspector de anuncios sirve para comprobar que los eventos personalizados se han importado correctamente en la aplicación. Esta herramienta puede abrirse solo con gestos o de forma automatizada con solo unos pequeños cambios en el código.

(Opcional) Llamar a métodos nativos de SDKs de terceros con secuencias de comandos mediante C#

Los SDK de redes publicitarias de terceros pueden tener requisitos especiales que exijan llamar a métodos de Android o iOS directamente. El proceso para llamar directamente a los métodos de Android y iOS es el siguiente:

  1. Definir una interfaz común para los clientes de la plataforma.
  2. Definir un cliente predeterminado para las plataformas no admitidas.
  3. Implementar un cliente de Android para llamar a métodos de Android.
  4. Implementar un cliente de iOS para llamar a métodos de iOS.
  5. Implementar una fábrica de clientes para cambiar entre clientes de iOS y Android si se cumplen determinadas condiciones.
  6. Definir una API para acceder a todas las funciones del SDK de una red publicitaria de terceros.

En la siguiente sección se explica cómo se implementan estos pasos en una red publicitaria ficticia llamada "AdPub" y se muestra cómo definir una API de C# que pueda llamar a los siguientes métodos en Android o iOS.

Android

package com.adpub.android;

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

iOS

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

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

Crea una interfaz IAdPubClient con un método que represente la API subyacente de Android y 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);
    }
}

Definir un cliente predeterminado para las plataformas no admitidas

Crea una clase DefaultClient que implemente la interfaz IAdPubClient y que solo registre el nombre del método. Usaremos esta implementación en la interfaz de usuario del editor de Unity y en todas las plataformas, a excepción de Android y iOS.

Assets/AdPub/Common/DefaultClient.cs

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

Implementar un cliente de la plataforma iOS

Crea una clase iOSAdPubClient que implemente la interfaz IAdPubClient en iOS. Esta implementación utiliza InteropServices para llamar al 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 ha definido anteriormente. Crea AdPubClientBridge.m con un método C GADUAdPubSetHasUserConsent() para gestionar la llamada de método desde Unity e invoca AdPubSDK.

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

Assets/AdPub/Plugins/iOS/AdPubClientBridge.m

#import <AdPubSDK/AdPubSDK.h>

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

Implementar un cliente de la plataforma Android

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

Como las clases auxiliares de Java para Android solo están disponibles durante el tiempo de ejecución de Android, puedes evitar errores de compilación usando la directiva del compilador UNITY_ANDROID para encapsular la clase, tal como se muestra a continuación. Si lo prefieres, puedes utilizar las definiciones de ensamblado en Unity 2017.4 y versiones posteriores.

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

Crear un método de fábrica para devolver la implementación de cliente correcta

Ahora que tienes implementaciones del cliente en cada plataforma, crea una clase AdPubClientFactory para devolver la implementación correcta de la interfaz IAdPubClient en función de la plataforma que se esté ejecutando. Esta clase usa directivas de compilación para devolver el cliente IAdPubClient correcto.

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

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

Crea una clase AdPubApi que tenga las llamadas de método para cada método de cliente en la interfaz IAdPubClient. Esta clase utiliza el objeto AdPubClientFactory para obtener una instancia de IAdPubClient y llama a ese cliente para conocer las funciones del SDK subyacente.

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

Llamar a la nueva API definida

A continuación, te indicamos 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);
    }
}

Otros ejemplos de adaptadores de redes publicitarias de terceros

Accede al repositorio de GitHub del complemento de Unity de anuncios de Google para móviles para ver más ejemplos de adaptadores de mediación de terceros que implementan las APIs de C# para encapsular las llamadas con métodos de iOS y Android.