Utwórz zdarzenia niestandardowe

Zdarzenia niestandardowe umożliwiają wydawcom korzystającym z zapośredniczenia w Ad Managerze dodawanie zapośredniczenia kaskadowego w przypadku zewnętrznej sieci reklamowej, która nie jest jedną z obsługiwanych sieci reklamowych. Z tego przewodnika dowiesz się, jak używać w projekcie Unity utworzonego wcześniej zdarzenia niestandardowego przeznaczonego na Androida i iOS.

Wymagania wstępne

Zanim przejdziesz dalej:

• Skonfiguruj Google Mobile Ads Unity Plugin. W aplikacji Unity powinna być już zaimportowana wtyczka reklam mobilnych Google dla środowiska Unity.

• Adaptery zdarzeń niestandardowych są już dostępne na Androida i iOS. Aby utworzyć niestandardowe adaptery zdarzeń, zapoznaj się z naszymi przewodnikami po zdarzeniach niestandardowych na Android i iOS.

Definiowanie zdarzenia niestandardowego

Aby zdarzenie niestandardowe mogło brać udział w zapośredniczeniu, musi być zdefiniowane w interfejsie internetowym Ad Managera. Dodaj zdarzenie niestandardowe do obu grup zapośredniczenia na Androida i iOS.

Importowanie bibliotek zdarzeń niestandardowych

Aby zdarzenia niestandardowe działały prawidłowo, może być konieczne uwzględnienie dodatkowych bibliotek. Może być na przykład konieczne uwzględnienie tych bibliotek:

• Zewnętrzny pakiet SDK na Androida
• Niestandardowe zdarzenie zewnętrzne na Androidzie
• Pakiet SDK do wyświetlania reklam na iOS firmy zewnętrznej
• Niestandardowe zdarzenie zewnętrzne w iOS

Rodzaje bibliotek

Kod Androida lub iOS możesz zaimportować do projektu Unity na kilka sposobów, m.in.:

• Importowanie gotowych artefaktów Androida lub iOS za pomocą narzędzia External Dependency Manager for Unity
• Importowanie wtyczek AAR i bibliotek Androida
• Importowanie plików źródłowych w językach Java i Kotlin
• Importowanie plików źródłowych i bibliotek statycznych iOS

W zależności od sposobu pakowania używanych bibliotek może być konieczne zastosowanie innej strategii importowania dla każdej z nich. Każda z tych opcji zostanie omówiona szczegółowo w dalszej części artykułu.

(Zalecane) Importowanie gotowych artefaktów Androida lub iOS

Importuj gotowe artefakty z Maven lub CocoaPods za pomocą External Dependency Manager for Unity. Ta wtyczka jest dołączona do wtyczki GoogleMobileAds.

Aby zaimportować istniejące artefakty, utwórz plik konfiguracyjny, w którym zdefiniujesz importy. Nazwa pliku i ścieżka muszą spełniać te wymagania:

• Plik musi znajdować się w folderze /Editor/.
• Nazwa pliku musi kończyć się na Dependencies.xml.

Aby na przykład zaimportować adaptery zdarzeń niestandardowych dla hipotetycznej sieci reklamowej o nazwie AdPub, utwórz plik:

Assets/AdPub/Editor/AdPubDependencies.xml

Następnie zdefiniuj zależności w pliku AdPubDependencies.xml. Reguły konfigurowania importów znajdziesz w artykule External Dependency Manager for Unity – wprowadzenie. Poniższy fragment kodu zawiera pakiety SDK na Androida i iOS oraz biblioteki zdarzeń niestandardowych dla hipotetycznej sieci reklamowej „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>

Jeśli artefakt zdarzenia niestandardowego ma już zależność od wymaganego pakietu SDK sieci reklamowej, nie musisz definiować zależności SDK w sposób jawny: Przykład

Menedżer zależności zewnętrznych automatycznie monitoruje zmiany konfiguracji i rozwiązuje zależności. Możesz też wykonać ręczne rozwiązywanie problemów za pomocą tego polecenia menu:

Assets > External Dependency Manager > Android Resolver > Force Resolve

Importowanie wtyczek AAR i bibliotek Androida

Unity obsługuje importowanie plików *.aar oraz projektów bibliotek Androida. Jeśli Twoje zdarzenie niestandardowe na Androida jest spakowane w ten sposób, zapoznaj się z instrukcjami dotyczącymi wtyczek AAR i bibliotek Androida, aby dowiedzieć się, jak uwzględnić te pliki w projekcie Unity.

Importowanie plików źródłowych w językach Java i Kotlin

Jeśli korzystasz z Unity w wersji 2018.2 lub nowszej, a Twój kod zdarzenia niestandardowego na Androida składa się z nieskompilowanych plików *.java lub *.kt, możesz używać plików źródłowych Java lub Kotlin jako wtyczek.

Importowanie plików źródłowych i bibliotek statycznych iOS

Unity obsługuje artefakty *.framework, *.h i *.m. Importowanie artefaktów i plików źródłowych iOS jest opisane w przewodniku Unity dotyczącym wtyczek natywnych.

Testowanie zdarzeń niestandardowych za pomocą inspektora reklam

Inspektora reklam można używać do testowania, czy zdarzenia niestandardowe zostały prawidłowo zaimportowane do aplikacji. Inspektora reklam można otworzyć za pomocą gestów lub programowo przy użyciu minimalnej ilości kodu.

(Opcjonalnie) Wywoływanie natywnych metod pakietu SDK innej firmy ze skryptów w języku C#

Pakiety SDK sieci reklamowych innych firm mogą mieć specjalne wymagania, które wymagają bezpośredniego wywoływania metod Androida lub iOS. Proces bezpośredniego wywoływania tych metod wygląda tak:

1. Zdefiniuj wspólny interfejs dla klientów platformy
2. Wdrażanie domyślnego klienta na nieobsługiwanych platformach
3. Wdróż klienta Androida do wywoływania metod Androida
4. Wdrażanie klienta iOS do wywoływania metod iOS
5. Wdrażanie fabryki klientów, aby warunkowo przełączać się między klientami iOS i Androida
6. Określ interfejs API umożliwiający dostęp do wszystkich funkcji pakietu SDK sieci reklam innych firm.

W sekcji poniżej pokazujemy, jak te kroki są wdrażane w przypadku hipotetycznej sieci reklamowej o nazwie „AdPub” w interfejsie C#, który może wywoływać metody na Androidzie i iOS:

package com.adpub.android;

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

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

Zdefiniuj wspólny interfejs dla klientów platformy

Utwórz interfejs IAdPubClient z metodą reprezentującą podstawowy interfejs API Androida i 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);
    }
}

Określanie domyślnego klienta na nieobsługiwanych platformach

Utwórz klasę DefaultClient implementującą interfejs IAdPubClient, która rejestruje tylko nazwę metody. Użyj tej implementacji w edytorze Unity i na wszystkich platformach innych niż Android i iOS.

Assets/AdPub/Common/DefaultClient.cs

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

Implementowanie klienta platformy iOS

Utwórz klasę iOSAdPubClient implementującą interfejs IAdPubClient w iOS. Ta implementacja używa InteropServices do wywoływania metody setHasUserConsent() w klasie AdPubSdk 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

Następnie zaimplementuj metodę GADUAdPubSetHasUserConsent() zdefiniowaną powyżej. Utwórz AdPubClientBridge.m z metodą CGADUAdPubSetHasUserConsent(), aby obsługiwać wywołanie metody z Unity, i wywołaj AdPubSDK.

AdPubClientBridge to plik źródłowy iOS, który musi znajdować się w folderze Plugins/iOS, zgodnie z opisem w przewodniku Unity dotyczącym wtyczek natywnych.

Assets/AdPub/Plugins/iOS/AdPubClientBridge.m

#import <AdPubSDK/AdPubSDK.h>

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

Wdrażanie klienta platformy Android

Utwórz klasę AndroidAdPubCient implementującą interfejs IAdPubClient na Androidzie. Ta implementacja używa klas pomocniczych Java na Androida do wywoływania statycznej metody Androida setHasUserConsent().

Klasy pomocnicze Androida Java są dostępne tylko w czasie działania Androida, więc możesz zapobiec błędom kompilacji, używając UNITY_ANDROID dyrektywy kompilatora do opakowania klasy, jak pokazano we fragmencie kodu. Możesz też użyć definicji zestawu w Unity 2017.4 lub nowszej, aby rozwiązać ten problem.

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

Utwórz metodę fabryczną, która zwraca prawidłową implementację klienta.

Teraz, gdy masz implementacje klienta na każdej platformie, utwórz klasę AdPubClientFactory, która będzie zwracać prawidłową implementację interfejsu IAdPubClient w zależności od platformy środowiska wykonawczego. Ta klasa używa dyrektyw kompilatora, aby zwracać prawidłowy IAdPubClientklient.

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

Zdefiniuj publiczny interfejs API dla każdej metody interfejsu

Utwórz klasę AdPubApi, która zawiera wywołania metod dla każdej metody klienta w interfejsie IAdPubClient. Ta klasa używa interfejsu AdPubClientFactory, aby uzyskać instancję interfejsu IAdPubClient, i wywołuje tego klienta w celu uzyskania dostępu do podstawowych funkcji pakietu SDK.

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

Wywoływanie nowo zdefiniowanego interfejsu API

Oto jak możesz wywołać zdefiniowany powyżej interfejs API:

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

Dodatkowe przykłady adapterów zewnętrznych sieci reklamowych

Więcej przykładów adapterów zapośredniczenia innych firm, które implementują interfejsy API w języku C# do opakowywania wywołań metod iOS i Androida, znajdziesz w repozytorium wtyczki reklam mobilnych Google dla środowiska Unity w Githubie.