Questa pagina è stata tradotta dall'API Cloud Translation.

Crea eventi personalizzati

Gli eventi personalizzati consentono ai publisher che utilizzano la mediazione AdMob di aggiungere la mediazione con struttura a cascata per una rete pubblicitaria di terze parti che non è una delle reti pubblicitarie supportate. Questa guida spiega come utilizzare un evento personalizzato esistente creato per Android e iOS in un progetto Unity.

Prerequisiti

Completa Inizia. Nell'app Unity dovrebbe essere già stato importato il plug-in per Unity di Google Mobile Ads.
Adattatori di eventi personalizzati già creati per Android e iOS. Per creare adattatori di eventi personalizzati, consulta le nostre guide sugli eventi personalizzati su Android e iOS.

Definire un evento personalizzato

Affinché un evento personalizzato possa partecipare alla mediazione, deve essere definito nell'interfaccia web di AdMob. Aggiungi un evento personalizzato a entrambi i gruppi di mediazione Android e iOS.

Questo screenshot mostra alcune impostazioni di eventi personalizzati di esempio:

Come compilare i parametri
Nome del corso (iOS)	Per iOS, inserisci il nome della classe che implementa l'evento personalizzato. Se la tua classe è implementata in Swift, devi anteporre il nome dell'app o del modulo framework a quello della classe corrispondente (ad es.`appName.className`). Il nome target è obbligatorio se il progetto ha più target o se il nome del progetto è diverso dal nome del target. Con il nome target, avrebbe il seguente aspetto: `appName_targetName.className`. Inoltre, ricordati di sostituire eventuali caratteri non alfanumerici, come i trattini, con i trattini bassi.
Nome del corso (Android)	Per Android, assicurati che il valore specificato per `Class Name` sia il nome completo della classe per Android (ad esempio `com.google.ads.mediation.sample.customevent.SampleCustomEvent`).
Etichetta	Inserisci un nome univoco per l'evento.
Parametro	Se vuoi passare un argomento stringa all'evento personalizzato, ad esempio un ID unità pubblicitaria.

Importa librerie di eventi personalizzati

Per funzionare correttamente, gli eventi personalizzati potrebbero richiedere l'inclusione di librerie aggiuntive. Ad esempio, potresti dover includere le seguenti librerie:

SDK di terze parti per Android
Evento personalizzato di terze parti per Android
SDK annunci di terze parti per iOS
Evento personalizzato di terze parti per iOS

Tipi di librerie

Esistono diversi modi per importare codice Android o iOS in un progetto Unity, tra cui:

Importazione di elementi precompilati per Android o iOS utilizzando il gestore delle dipendenze esterne per Unity
Importazione di plug-in AAR e librerie Android
Importazione dei file di origine Java e Kotlin
Importazione di file di origine e librerie statiche per iOS

A seconda del modo in cui le librerie che utilizzi sono pacchettizzate, potresti aver bisogno di una strategia di importazione diversa per ogni libreria. Ogni opzione viene discussa più nel dettaglio di seguito.

(Consigliato) Importa elementi precompilati per Android o iOS

Importa gli elementi precompilati da Maven o CocoaPods utilizzando il gestore delle dipendenze esterne per Unity. Questo plug-in è incluso nel plug-in GoogleMobileAds.

Per importare gli elementi esistenti, crea un file di configurazione per definire le importazioni. Il nome e il percorso del file devono soddisfare i seguenti requisiti:

Il file deve esistere nella cartella /Editor/.
Il nome del file deve terminare con Dependencies.xml.

Ad esempio, per importare gli adattatori degli eventi personalizzati per una rete pubblicitaria ipotetica chiamata AdPub, crea il file:

Assets/AdPub/Editor/AdPubDependencies.xml

Poi, definisci le dipendenze all'interno del file AdPubDependencies.xml. Le regole per la configurazione delle importazioni sono disponibili nella pagina External Dependency Manager for Unity Getting Started (Guida introduttiva a External Dependency Manager per Unity). Il seguente snippet di codice include l'SDK per Android e iOS e le librerie di eventi personalizzati per una ipotetica rete pubblicitaria "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>

Se l'elemento dell'evento personalizzato ha già una dipendenza dall'SDK della rete pubblicitaria richiesta, non è necessario definire esplicitamente la dipendenza dall'SDK: Esempio

Il gestore delle dipendenze esterne monitora automaticamente le modifiche alla configurazione e risolve le dipendenze. Puoi anche eseguire la risoluzione manuale con il seguente comando del menu:

Assets > External Dependency Manager > Android Resolver > Force Resolve

Importa plug-in AAR e librerie Android

Unity supporta l'importazione di file *.aar e di progetti di librerie Android. Se il tuo evento personalizzato per Android è pacchettizzato in questo modo, consulta Plug-in AAR e librerie Android per istruzioni su come includere questi file nel progetto Unity.

Importare i file di origine Java e Kotlin

A partire da Unity 2018.2 o versioni successive, se il codice dell'evento personalizzato Android è costituito da file *.java o *.kt non compilati, puoi utilizzare file di origine Java o Kotlin come plug-in.

Importare file di origine e librerie statiche per iOS

Unity supporta gli artefatti *.framework, i file di origine *.h e *.m. L'importazione di artefatti e file di origine per iOS è descritta nella guida di Unity per i plug-in nativi.

Testare gli eventi personalizzati con lo strumento di controllo degli annunci

Lo strumento di controllo degli annunci può essere utilizzato per verificare che gli eventi personalizzati siano stati importati correttamente nella tua applicazione. L'ispettore annunci può essere aperto solo con gesti o tramite codice con un codice minimo.

(Facoltativo) Chiama i metodi nativi dell'SDK di terze parti dagli script C#

Gli SDK delle reti pubblicitarie di terze parti potrebbero avere requisiti speciali che richiedono di chiamare direttamente i metodi Android o iOS. La procedura per chiamare direttamente questi metodi è la seguente:

Definire un'interfaccia comune per i client della piattaforma
Implementare un client predefinito per le piattaforme non supportate
Implementa un client Android per chiamare i metodi Android
Implementare un client iOS per chiamare i metodi iOS
Implementa una fabbrica di client per passare in modo condizionale da un client iOS a un client Android
Definire un'API per accedere a tutte le funzionalità dell'SDK della rete pubblicitaria di terze parti

La sezione seguente mostra come vengono implementati questi passaggi per una rete pubblicitaria ipotetica chiamata "AdPub" in un'API C# che può chiamare i metodi su Android e iOS:

AndroidiOS

package com.adpub.android;

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

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

Definire un'interfaccia comune per i client della piattaforma

Crea un'interfaccia IAdPubClient con un metodo che rappresenti l'API Android e iOS di base.

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

Definire un client predefinito per le piattaforme non supportate

Crea una classe DefaultClient che implementi l'interfaccia IAdPubClient e che registri solo il nome del metodo. Utilizza questa implementazione per l'editor Unity e per tutte le piattaforme diverse da Android o iOS.

`Assets/AdPub/Common/DefaultClient.cs`

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

Implementare un client della piattaforma iOS

Crea una classe iOSAdPubClient che implementi l'interfaccia IAdPubClient su iOS. Questa implementazione utilizza InteropServices per chiamare il metodo setHasUserConsent() nella classe AdPubSdk di 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

Poi, implementa il metodo GADUAdPubSetHasUserConsent() definito sopra. Crea AdPubClientBridge.m con un metodo C GADUAdPubSetHasUserConsent() per gestire la chiamata al metodo da Unity e invoca AdPubSDK.

AdPubClientBridge è un file di origine iOS e deve essere inserito nella Plugins/iOS cartella come spiegato nella guida di Unity per i plug-in nativi.

`Assets/AdPub/Plugins/iOS/AdPubClientBridge.m`

#import <AdPubSDK/AdPubSDK.h>

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

Implementare un client per la piattaforma Android

Crea una classe AndroidAdPubCient che implementi l'interfaccia IAdPubClient su Android. Questa implementazione utilizza le classi di assistenza Java per Android per chiamare il metodo statico Android setHasUserConsent().

Poiché le classi di assistenza Java di Android sono disponibili solo durante il runtime di Android, puoi evitare errori di compilazione utilizzando la UNITY_ANDROID direttiva del compilatore per avvolgere la classe come mostrato nello snippet di codice. In alternativa, puoi utilizzare le definizioni assembly su Unity 2017.4 e versioni successive per risolvere il 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 metodo di fabbrica per restituire l'implementazione del client corretta

Ora che hai implementazioni del client per ogni piattaforma, crea una classe AdPubClientFactory per restituire l'implementazione corretta dell'interfaccia IAdPubClient a seconda della piattaforma di runtime. Questa classe utilizza le direttive del compilatore per restituire il client IAdPubClient corretto.

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

Definisci un'API pubblica per ogni metodo dell'interfaccia

Crea una classe AdPubApi con chiamate ai metodi per ogni metodo client nell'interfaccia IAdPubClient. Questa classe utilizza AdPubClientFactory per ottenere un'istanza di IAdPubClient e chiama il client per le funzionalità dell'SDK sottostante.

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

Chiama l'API appena definita

Ecco come chiamare l'API definita sopra:

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

Altri esempi di adattatori di reti pubblicitarie di terze parti

Visita il repository GitHub del plug-in Unity di Google Mobile Ads per altri esempi di adattatori di mediazione di terze parti che implementano API C# per eseguire il wrapping delle chiamate ai metodi iOS e Android.