Benutzerdefinierte Ereignisse erstellen

Mit benutzerdefinierten Ereignissen können Publisher, die die AdMob-Vermittlung verwenden, die abfolgebasierte Vermittlung für ein Drittanbieter-Werbenetzwerk hinzufügen, das nicht zu den unterstützten Werbenetzwerken gehört. In diesem Leitfaden wird beschrieben, wie Sie ein vorhandenes benutzerdefiniertes Ereignis, das für Android und iOS entwickelt wurde, in einem Unity-Projekt verwenden.

Vorbereitung

  • Führen Sie die Schritte unter Jetzt starten aus. Das Google Mobile Ads Unity-Plug-in sollte bereits in Ihre Unity-App importiert sein.

  • Benutzerdefinierte Ereignisadapter, die bereits für Android und iOS erstellt wurden Informationen zum Erstellen benutzerdefinierter Ereignisadapter finden Sie in unseren Leitfäden zu benutzerdefinierten Ereignissen für Android und iOS.

Benutzerdefiniertes Ereignis definieren

Damit ein benutzerdefiniertes Ereignis an der Vermittlung teilnehmen kann, muss es in der AdMob-Weboberfläche definiert werden. Fügen Sie beiden Vermittlungsgruppen für Android und iOS ein benutzerdefiniertes Ereignis hinzu.

Auf diesem Screenshot sind einige Beispieleinstellungen für benutzerdefinierte Ereignisse zu sehen:

Parameter ausfüllen
Kursname (iOS)

Geben Sie unter iOS den Namen der Klasse ein, in der das benutzerdefinierte Ereignis implementiert ist.

Wenn Sie zur Implementierung der Klasse Swift verwendet haben, müssen Sie den Namen der zugehörigen App / des zugehörigen Framework-Moduls vor den Namen der Klasse stellen (z. B. appName.className).

Der Zielname ist erforderlich, wenn Sie mehrere Ziele in Ihrem Projekt haben oder sich der Projektname vom Zielnamen unterscheidet. Mit dem Zielnamen würde es so aussehen: appName_targetName.className. Denken Sie außerdem daran, alle nicht alphanumerischen Zeichen wie Bindestriche durch Unterstriche zu ersetzen.

Kursname (Android) Achten Sie bei Android darauf, dass der Wert für Class Name der vollqualifizierte Klassenname für Android ist (z. B. com.google.ads.mediation.sample.customevent.SampleCustomEvent).
Label Geben Sie einen eindeutigen Namen für das Ereignis ein.
Parameter Wenn Sie ein Stringargument an Ihr benutzerdefiniertes Ereignis übergeben möchten, z. B. eine Anzeigenblock-ID.

Benutzerdefinierte Ereignisbibliotheken importieren

Für benutzerdefinierte Ereignisse müssen möglicherweise zusätzliche Bibliotheken eingebunden werden, damit sie ordnungsgemäß funktionieren. Möglicherweise müssen Sie beispielsweise die folgenden Bibliotheken einschließen:

  • Android-Drittanbieter-SDK
  • Benutzerdefiniertes Ereignis von Drittanbietern für Android
  • iOS-Drittanbieter-Anzeigen-SDK
  • Benutzerdefiniertes Ereignis von Drittanbietern für iOS

Arten von Bibliotheken

Es gibt mehrere Möglichkeiten, Android- oder iOS-Code in ein Unity-Projekt zu importieren:

  • Vorgefertigte Android- oder iOS-Artefakte mit dem externen Abhängigkeitsmanager für Unity importieren
  • AAR-Plug-ins und Android-Bibliotheken importieren
  • Java- und Kotlin-Quelldateien importieren
  • iOS-Quelldateien und statische Bibliotheken importieren

Je nachdem, wie die von Ihnen verwendeten Bibliotheken verpackt sind, benötigen Sie möglicherweise für jede Bibliothek eine andere Importstrategie. Die einzelnen Optionen werden später ausführlicher beschrieben.

(Empfohlen) Vorab erstellte Android- oder iOS-Artefakte importieren

Importieren Sie vorkonfigurierte Artefakte aus Maven oder CocoaPods mit dem externen Abhängigkeitsmanager für Unity. Dieses Plug-in ist im GoogleMobileAds-Plug-in enthalten.

Wenn Sie vorhandene Artefakte importieren möchten, erstellen Sie eine Konfigurationsdatei, um Ihre Importe zu definieren. Für Dateiname und Pfad gelten die folgenden Anforderungen:

  • Die Datei muss sich im Ordner /Editor/ befinden.
  • Der Dateiname muss auf Dependencies.xml enden.

Wenn Sie beispielsweise die Adapter für benutzerdefinierte Ereignisse für ein hypothetisches Werbenetzwerk namens AdPub importieren möchten, erstellen Sie die Datei:

Assets/AdPub/Editor/AdPubDependencies.xml

Definieren Sie als Nächstes die Abhängigkeiten in der AdPubDependencies.xml-Datei. Regeln zum Konfigurieren der Importe finden Sie unter External Dependency Manager for Unity Getting Started (Externer Abhängigkeitsmanager für Unity – Erste Schritte). Das folgende Code-Snippet enthält das Android- und iOS-SDK sowie Bibliotheken für benutzerdefinierte Ereignisse für ein hypothetisches Werbenetzwerk namens „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>

Wenn Ihr benutzerdefiniertes Ereignis-Artefakt bereits eine Abhängigkeit vom erforderlichen SDK des Werbenetzwerks hat, müssen Sie die SDK-Abhängigkeit nicht explizit definieren: Beispiel

Der External Dependency Manager überwacht automatisch Konfigurationsänderungen und löst Abhängigkeiten. Sie können die Auflösung auch manuell mit dem folgenden Menübefehl festlegen:

Assets > External Dependency Manager > Android Resolver > Force Resolve

AAR-Plug-ins und Android-Bibliotheken importieren

Unity unterstützt den Import von *.aar-Dateien und Android-Bibliotheksprojekten. Wenn Ihr benutzerdefiniertes Android-Ereignis so verpackt ist, finden Sie unter AAR-Plug-ins und Android-Bibliotheken eine Anleitung zum Einbinden dieser Dateien in Ihr Unity-Projekt.

Java- und Kotlin-Quelldateien importieren

Ab Unity 2018.2 können Sie Java- oder Kotlin-Quelldateien als Plug-ins verwenden, wenn Ihr benutzerdefinierter Android-Ereigniscode aus nicht kompilierten *.java- oder *.kt-Dateien besteht.

iOS-Quelldateien und statische Bibliotheken importieren

Unity unterstützt *.framework-Artefakte, *.h- und *.m-Quelldateien. Informationen zum Importieren von iOS-Artefakten und ‑Quelldateien finden Sie im Unity-Leitfaden für native Plug-ins.

Benutzerdefinierte Ereignisse mit dem Anzeigenprüftool testen

Mit dem Anzeigenprüftool können Sie prüfen, ob benutzerdefinierte Ereignisse korrekt in Ihre Anwendung importiert wurden. Der Anzeigen-Inspector kann nur mit Touch-Gesten oder programmatisch mit minimalem Code geöffnet werden.

Optional: Native Methoden von Drittanbieter-SDKs aus C#-Scripts aufrufen

SDKs von Drittanbieter-Werbenetzwerken können spezielle Anforderungen haben, die das direkte Aufrufen von Android- oder iOS-Methoden erfordern. So rufen Sie diese Methoden direkt auf:

  1. Gemeinsame Schnittstelle für Plattformclients definieren
  2. Standardclient für nicht unterstützte Plattformen implementieren
  3. Android-Client zum Aufrufen von Android-Methoden implementieren
  4. iOS-Client zum Aufrufen von iOS-Methoden implementieren
  5. Implementiere eine Client-Factory, um bedingt zwischen iOS- und Android-Clients zu wechseln.
  6. API für den Zugriff auf alle SDK-Funktionen von Drittanbieter-Werbenetzwerken definieren

Im folgenden Abschnitt wird gezeigt, wie diese Schritte für ein hypothetisches Anzeigennetzwerk namens „AdPub“ in einer C#-API implementiert werden, die die Methoden auf Android- und iOS-Geräten aufrufen kann:

Android

package com.adpub.android;

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

iOS

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

Gemeinsame Schnittstelle für Plattformclients definieren

Erstellen Sie eine IAdPubClient-Schnittstelle mit einer Methode, die die zugrunde liegende Android- und iOS-API darstellt.

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

Standardclient für nicht unterstützte Plattformen definieren

Erstellen Sie eine DefaultClient-Klasse, die die IAdPubClient-Schnittstelle implementiert und nur den Methodennamen protokolliert. Verwenden Sie diese Implementierung für den Unity-Editor und alle anderen Plattformen außer Android oder iOS.

Assets/AdPub/Common/DefaultClient.cs

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

iOS-Plattformclient implementieren

Erstellen Sie eine iOSAdPubClient-Klasse, die die IAdPubClient-Schnittstelle auf iOS implementiert. Bei dieser Implementierung wird InteropServices verwendet, um die Methode setHasUserConsent() in der iOS-Klasse AdPubSdk aufzurufen.

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

Implementieren Sie als Nächstes die oben definierte GADUAdPubSetHasUserConsent()-Methode. Erstelle AdPubClientBridge.m mit einer C-Methode GADUAdPubSetHasUserConsent(), um den Methodenaufruf von Unity zu verarbeiten, und rufe die AdPubSDK auf.

AdPubClientBridge ist eine iOS-Quelldatei und muss sich im Ordner Plugins/iOS befinden, wie im Unity-Leitfaden für native Plug-ins beschrieben.

Assets/AdPub/Plugins/iOS/AdPubClientBridge.m

#import <AdPubSDK/AdPubSDK.h>

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

Android-Plattformclient implementieren

Erstellen Sie eine AndroidAdPubCient-Klasse, die die IAdPubClient-Schnittstelle auf Android implementiert. In dieser Implementierung werden die Android Java-Hilfsklassen verwendet, um die statische Android-Methode setHasUserConsent() aufzurufen.

Da die Android-Java-Hilfsklassen nur während der Android-Laufzeit verfügbar sind, können Sie mit der UNITY_ANDROID-Compileranweisung Kompilierungsfehler verhindern, indem Sie die Klasse wie im Code-Snippet gezeigt einschließen. Alternativ können Sie Assembly-Definitionen in Unity 2017.4 und höher verwenden, um dieses Problem zu beheben.

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

Erstellen Sie eine Fabrikmethode, um die richtige Clientimplementierung zurückzugeben.

Da Sie jetzt Implementierungen des Clients für jede Plattform haben, erstellen Sie eine AdPubClientFactory-Klasse, um je nach Laufzeitplattform die richtige Implementierung der IAdPubClient-Schnittstelle zurückzugeben. Diese Klasse verwendet Compileranweisungen, um den richtigen IAdPubClient-Client zurückzugeben.

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

Für jede Schnittstellenmethode eine öffentliche API definieren

Erstellen Sie eine AdPubApi-Klasse mit Methodenaufrufen für jede Clientmethode in Ihrer IAdPubClient-Schnittstelle. Diese Klasse verwendet die AdPubClientFactory, um eine Instanz des IAdPubClient abzurufen, und ruft diesen Client für die zugrunde liegenden SDK-Funktionen auf.

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

Ihre neu definierte API aufrufen

So rufen Sie die oben definierte API auf:

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

Weitere Beispiele für Adapter für Drittanbieter-Werbenetzwerke

Im Github-Repository des Google Mobile Ads Unity-Plug-ins finden Sie weitere Beispiele für Vermittlungsadapter von Drittanbietern, die C# APIs implementieren, um Aufrufe an iOS- und Android-Methoden zu verpacken.