Créer des événements personnalisés

Sélectionnez la plate-forme : Android Android iOS Unity

Les événements personnalisés permettent aux éditeurs qui utilisent la médiation Ad Manager d'ajouter une médiation en cascade pour un réseau publicitaire tiers qui ne fait pas partie des réseaux publicitaires compatibles. Ce guide explique comment utiliser un événement personnalisé existant conçu pour Android et iOS dans un projet Unity.

Prérequis

Avant de continuer, procédez comme suit :

• Configurez Google Mobile Ads Unity Plugin. Le plug-in Google Mobile Ads Unity doit déjà être importé dans votre application Unity.

• Les adaptateurs d'événements personnalisés sont déjà conçus pour Android et iOS. Pour créer des adaptateurs d'événements personnalisés, consultez nos guides sur les événements personnalisés sur Android et iOS.

Définir un événement personnalisé

Pour qu'un événement personnalisé participe à la médiation, il doit être défini dans l'interface Web Ad Manager. Ajoutez un événement personnalisé à vos groupes de médiation Android et iOS.

Importer des bibliothèques d'événements personnalisés

Les événements personnalisés peuvent nécessiter l'inclusion de bibliothèques supplémentaires pour fonctionner correctement. Par exemple, vous devrez peut-être inclure les bibliothèques suivantes :

• SDK tiers Android
• Événement personnalisé tiers Android
• SDK publicitaire tiers iOS
• Événement personnalisé tiers iOS

Types de bibliothèques

Il existe plusieurs façons d'importer du code Android ou iOS dans un projet Unity, y compris :

• Importer des artefacts Android ou iOS prédéfinis à l'aide du gestionnaire de dépendances externes pour Unity
• Importer des plug-ins AAR et des bibliothèques Android
• Importer des fichiers sources Java et Kotlin
• Importer des fichiers sources iOS et des bibliothèques statiques

Selon la façon dont les bibliothèques que vous utilisez sont empaquetées, vous devrez peut-être utiliser une stratégie d'importation différente pour chaque bibliothèque. Chaque option est abordée plus en détail ci-dessous.

(Recommandé) Importer des artefacts Android ou iOS prédéfinis

Importez des artefacts prédéfinis à partir de Maven ou de CocoaPods à l'aide du gestionnaire de dépendances externes pour Unity. Ce plug-in est inclus dans le plug-in GoogleMobileAds.

Pour importer des artefacts existants, créez un fichier de configuration pour définir vos importations. Le nom et le chemin d'accès du fichier doivent respecter les exigences suivantes :

• Le fichier doit se trouver dans le dossier /Editor/.
• Le nom du fichier doit se terminer par Dependencies.xml.

Par exemple, pour importer les adaptateurs d'événements personnalisés pour un réseau publicitaire hypothétique nommé AdPub, créez le fichier :

Assets/AdPub/Editor/AdPubDependencies.xml

Ensuite, définissez vos dépendances dans le fichier AdPubDependencies.xml. Vous trouverez des règles de configuration des importations dans le guide de démarrage du gestionnaire de dépendances externes pour Unity. L'extrait de code suivant inclut le SDK Android et iOS, ainsi que les bibliothèques d'événements personnalisés pour un réseau publicitaire hypothétique "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 votre artefact d'événement personnalisé dépend déjà du SDK du réseau publicitaire requis, vous n'avez pas besoin de définir explicitement la dépendance du SDK : Exemple

Le gestionnaire de dépendances externes surveille automatiquement les modifications de configuration et résout les dépendances. Vous pouvez également exécuter une résolution manuelle à l'aide de la commande de menu suivante :

Assets > External Dependency Manager > Android Resolver > Force Resolve

Importer des plug-ins AAR et des bibliothèques Android

Unity permet d'importer des fichiers *.aar ainsi que des projets de bibliothèque Android. Si votre événement personnalisé Android est empaqueté de cette manière, consultez Plug-ins AAR et bibliothèques Android pour savoir comment inclure ces fichiers dans votre projet Unity.

Importer des fichiers sources Java et Kotlin

À partir d'Unity 2018.2 ou version ultérieure, si votre code d'événement personnalisé Android comprend des fichiers *.java ou *.kt non compilés, vous pouvez utiliser des fichiers sources Java ou Kotlin comme plug-ins.

Importer des fichiers sources iOS et des bibliothèques statiques

Unity est compatible avec les artefacts *.framework, les fichiers sources *.h et *.m. L'importation d'artefacts et de fichiers sources iOS est expliquée dans le guide de Unity pour les plug-ins natifs.

Tester des événements personnalisés avec l'inspecteur d'annonces

L'inspecteur d'annonces peut être utilisé pour vérifier que les événements personnalisés ont été importés correctement dans votre application. L'inspecteur d'annonces peut être ouvert avec des gestes ou par programmation avec un minimum de code.

(Facultatif) Appeler des méthodes natives de SDK tiers à partir de scripts C#

Les SDK de réseaux publicitaires tiers peuvent avoir des exigences particulières qui nécessitent d'appeler directement des méthodes Android ou iOS. Pour appeler directement ces méthodes, procédez comme suit :

1. Définissez une interface commune pour les clients de plate-forme
2. Implémentez un client par défaut pour les plates-formes non compatibles
3. Implémentez un client Android pour appeler des méthodes Android
4. Implémentez un client iOS pour appeler des méthodes iOS
5. Implémentez une fabrique de clients pour basculer de manière conditionnelle entre les clients iOS et Android
6. Définissez une API pour accéder à toutes les fonctionnalités du SDK de réseau publicitaire tiers

La section suivante montre comment ces étapes sont implémentées pour un réseau publicitaire hypothétique appelé "AdPub" dans une API C# qui peut appeler les méthodes sur Android et iOS :

package com.adpub.android;

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

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

Définir une interface commune pour les clients de plate-forme

Créez une interface IAdPubClient avec une méthode qui représente l'API Android et iOS sous-jacente.

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

Définir un client par défaut pour les plates-formes non compatibles

Créez une classe DefaultClient qui implémente l'interface IAdPubClient et qui enregistre simplement le nom de la méthode. Utilisez cette implémentation pour l'éditeur Unity et toutes les plates-formes autres qu'Android ou iOS.

Assets/AdPub/Common/DefaultClient.cs

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

Implémenter un client de plate-forme iOS

Créez une classe iOSAdPubClient qui implémente l'interface IAdPubClient sur iOS. Cette implémentation utilise InteropServices pour appeler la méthode setHasUserConsent() dans la classe 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

Ensuite, implémentez la méthode GADUAdPubSetHasUserConsent() définie ci-dessus. Créez AdPubClientBridge.m avec une méthode C GADUAdPubSetHasUserConsent() pour gérer l'appel de méthode à partir d'Unity et appelez le AdPubSDK.

AdPubClientBridge est un fichier source iOS qui doit être placé dans le dossier Plugins/iOS, comme expliqué dans le guide de Unity's pour les plug-ins natifs.

Assets/AdPub/Plugins/iOS/AdPubClientBridge.m

#import <AdPubSDK/AdPubSDK.h>

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

Implémenter un client de plate-forme Android

Créez une classe AndroidAdPubCient qui implémente l'interface IAdPubClient sur Android. Cette implémentation utilise les classes d'assistance Java Android pour appeler la méthode statique Android setHasUserConsent().

Comme les classes d'assistance Java Android ne sont disponibles que lors de l'exécution Android , vous pouvez éviter les erreurs de compilation à l'aide de la UNITY_ANDROID directive de compilateur pour encapsuler la classe, comme indiqué dans l'extrait de code. Vous pouvez également utiliser des définitions d'assemblage sur Unity 2017.4 et versions ultérieures pour résoudre ce problème.

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

Créer une méthode de fabrique pour renvoyer l'implémentation du client appropriée

Maintenant que vous disposez d'implémentations du client pour chaque plate-forme, créez une classe AdPubClientFactory pour renvoyer l'implémentation correcte de l'interface IAdPubClient en fonction de la plate-forme d'exécution. Cette classe utilise des directives de compilateur pour renvoyer le client approprié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
        }
    }
}

Définir une API publique pour chaque méthode d'interface

Créez une classe AdPubApi qui comporte des appels de méthode pour chaque méthode client de votre interface IAdPubClient. Cette classe utilise AdPubClientFactory pour obtenir une instance de IAdPubClient et appelle ce client pour les fonctionnalités du SDK sous-jacent.

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

Appeler l'API que vous venez de définir

Voici comment appeler l'API définie ci-dessus :

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

Autres exemples d'adaptateurs de réseaux publicitaires tiers

Consultez le dépôt GitHub du plug-in Google Mobile Ads Unity pour obtenir d'autres exemples d'adaptateurs de médiation tiers implémentant des API C# afin d'encapsuler les appels aux méthodes iOS et Android.