Questa pagina è stata tradotta dall'API Cloud Translation.

Crea eventi personalizzati

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

Prerequisiti

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

Definisci un evento personalizzato

Affinché un evento personalizzato partecipi alla mediazione, è necessario definire l'evento personalizzato nell'interfaccia AdMob web. Aggiungi un evento personalizzato a entrambi i gruppi di mediazione Android e iOS.

Questo screenshot mostra alcuni esempi di impostazioni degli eventi personalizzati:

Come compilare i parametri
Nome corso (iOS)	Per iOS, inserisci il nome della classe che implementa l'evento personalizzato. Se la tua classe è implementata in Swift, devi anteporre al nome della classe il nome della relativa app / modulo del framework (ad esempio `appName.className`). Il nome della destinazione è obbligatorio se nel progetto sono presenti più destinazioni o se il nome del progetto è diverso dal nome della destinazione. Con il nome della destinazione, l'aspetto sarebbe simile al seguente: `appName_targetName.className`. Inoltre, ricorda di sostituire tutti i caratteri non alfanumerici, come i trattini, con il trattino basso.
Nome corso (Android)	Per Android, assicurati che il valore assegnato 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

Gli eventi personalizzati potrebbero richiedere l'inclusione di librerie aggiuntive per funzionare correttamente. Ad esempio, potrebbe essere necessario 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 il codice Android o iOS in un progetto Unity, tra cui:

Importazione di artefatti Android o iOS predefiniti con External Dependency Manager per Unity
Importazione di plug-in AAR e librerie Android
Importazione di file di origine Java e Kotlin
Importazione di file di origine e librerie statiche in iOS

A seconda della modalità di pacchettizzazione delle librerie che utilizzi, potresti avere bisogno di una strategia di importazione diversa per ogni libreria. Ogni opzione verrà discussa più dettagliatamente in seguito.

(Consigliato) Importa elementi Android o iOS predefiniti

Importa gli artefatti predefiniti da Maven o CocoaPods utilizzando External Dependency Manager per Unity. Questo plug-in è incluso nel plug-in GoogleMobileAds.

Per importare gli artefatti esistenti, crea un file di configurazione per definire le importazioni. Il nome file e il percorso hanno 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 di eventi personalizzati per un'ipotetica rete pubblicitaria denominata AdPub, crea il file:

Assets/AdPub/Editor/AdPubDependencies.xml

A questo punto, definisci le dipendenze all'interno del file AdPubDependencies.xml. Le regole per la configurazione delle importazioni sono disponibili in External Dependency Manager for Unity Getting Started. Il seguente snippet di codice include l'SDK per Android e iOS e le librerie di eventi personalizzati per un'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'artefatto dell'evento personalizzato ha già una dipendenza dall'SDK della rete pubblicitaria richiesto, non è necessario definire esplicitamente la dipendenza dell'SDK: Esempio

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

Assets > External Dependency Manager > Android Resolver > Force Resolve

Importa plug-in AAR e librerie Android

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

Importa file di origine Java e Kotlin

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

Importa file di origine e librerie statiche iOS

Unity supporta gli artefatti *.framework, *.h e i file di origine *.m. L'importazione di elementi e file di origine iOS è spiegata 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. Lo strumento di controllo degli annunci può essere aperto con semplici gesti o in modo programmatico con una minima parte di codice.

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

Gli SDK di 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:

Definisci 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 tra i client iOS e Android
Definire un'API per accedere a tutte le funzionalità dell'SDK delle reti pubblicitarie di terze parti

La seguente sezione mostra come vengono implementati questi passaggi per un'ipotetica rete pubblicitaria chiamata "AdPub" in un'API C# in grado di richiamare i metodi su Android e iOS:

Android

package com.adpub.android;

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

iOS

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

Definisci un'interfaccia comune per i client della piattaforma

Crea un'interfaccia IAdPubClient con un metodo che rappresenti l'API per Android e iOS sottostante.

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

Definisci un client predefinito per le piattaforme non supportate

Crea una classe DefaultClient che implementi l'interfaccia IAdPubClient che registra 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 per una piattaforma iOS

Crea una classe iOSAdPubClient che implementa l'interfaccia IAdPubClient su iOS. Questa implementazione utilizza InteropServices per chiamare il metodo setHasUserConsent() nella classe AdPubSdk per 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 questo punto, implementa il metodo GADUAdPubSetHasUserConsent() definito sopra. Crea AdPubClientBridge.m con un metodo C GADUAdPubSetHasUserConsent() per gestire la chiamata al metodo da Unity e richiama AdPubSDK.

AdPubClientBridge è un file di origine iOS e deve essere posizionato all'interno della cartella Plugins/iOS, 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 implementa l'interfaccia IAdPubClient su Android. Questa implementazione utilizza le classi helper Java di Android per chiamare il metodo statico di Android setHasUserConsent().

Poiché le classi helper Java per Android sono disponibili solo durante il runtime Android, puoi evitare errori di compilazione utilizzando l'istruzione del compilatore UNITY_ANDROID per eseguire il wrapping della classe come mostrato nello snippet di codice. In alternativa, puoi utilizzare le definizioni di 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

Creare un metodo di fabbrica per restituire l'implementazione client corretta

Ora che hai implementato le implementazioni del client per ogni piattaforma, crea una classe AdPubClientFactory per restituire l'implementazione corretta dell'interfaccia IAdPubClient in base alla piattaforma di runtime. Questa classe utilizza le istruzioni di compilazione per restituire il client IAdPubClientcorretto.

`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 di interfaccia

Crea una classe AdPubApi con chiamate di metodo per ciascun metodo client nell'interfaccia IAdPubClient. Questa classe utilizza AdPubClientFactory per ottenere un'istanza di IAdPubClient e chiama quel client per le funzionalità dell'SDK sottostanti.

`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 rete pubblicitaria di terze parti

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