Özel etkinlikler oluştur

Özel etkinlikler, uyumlulaştırmayı kullanan yayıncıların AdMob desteklenen reklam ağlarından biri olmayan bir üçüncü taraf reklam ağı için şelale uyumlulaştırması eklemesini sağlar. Bu kılavuzda, Android ve iOS için derlenmiş mevcut bir özel etkinliğin Unity projesinde nasıl kullanılacağı açıklanmaktadır.

Ön koşullar

  • Başlayın'ı tamamlayın. Unity uygulamanızda Google Mobile Ads Unity eklentisi içe aktarılmış olmalıdır.

  • Android ve iOS için geliştirilmiş özel etkinlik bağdaştırıcıları. Özel etkinlik bağdaştırıcıları oluşturmak içinAndroid veiOSile ilgili özel etkinlik kılavuzlarımıza bakın.

Özel etkinlik tanımlama

Bir özel etkinliğin uyumlulaştırmaya katılması için özel etkinliğin AdMob web arayüzünde tanımlanması gerekir. Hem Android hem de iOS uyumlulaştırma gruplarınıza özel bir etkinlik ekleyin.

Bu ekran görüntüsünde, bazı örnek özel etkinlik ayarları gösterilmektedir:

Parametreler nasıl doldurulur?
Sınıf Adı (iOS)

iOS'te, özel etkinliği uygulayan sınıfın adını girin.

Sınıfınız Swift'te uygulandıysa sınıf adının önüne o sınıfın uygulama / çerçeve modülünün adını yazmanız gerekir (örneğin, appName.className).

Projenizde birden fazla hedef varsa veya proje adı hedef addan farklıysa hedef adı gereklidir. Hedef ad şöyle görünür: appName_targetName.className. Ayrıca, kısa çizgi gibi alfanümerik olmayan karakterleri alt çizgiyle değiştirmeyi unutmayın.

Sınıf Adı (Android) Android'de Class Name için verdiğiniz değerin, Android'in tam sınıf adı (örneğin com.google.ads.mediation.sample.customevent.SampleCustomEvent) olduğundan emin olun.
Etiket Etkinlik için benzersiz bir ad girin.
Parametre Özel etkinliğinize reklam birimi kimliği gibi bir dize bağımsız değişkeni aktarmak istiyorsanız.

Özel etkinlik kitaplıklarını içe aktarma

Özel etkinliklerin doğru şekilde çalışması için ek kitaplıkların eklenmesi gerekebilir. Örneğin, aşağıdaki kitaplıkları eklemeniz gerekebilir:

  • Android üçüncü taraf SDK'sı
  • Android üçüncü taraf özel etkinliği
  • iOS üçüncü taraf reklam SDK'sı
  • iOS üçüncü taraf özel etkinliği

Kitaplık türleri

Android veya iOS kodunu Unity projesine aktarmanın çeşitli yolları vardır. Örneğin:

  • Unity için Harici Bağımlılık Yöneticisi'ni kullanarak önceden oluşturulmuş Android veya iOS yapılarını içe aktarma
  • AAR eklentilerini ve Android kitaplıklarını içe aktarma
  • Java ve Kotlin kaynak dosyalarını içe aktarma
  • iOS kaynak dosyalarını ve statik kitaplıkları içe aktarma

Kullandığınız kitaplıkların paketlenme şekline bağlı olarak her kitaplık için farklı bir içe aktarma stratejisine ihtiyacınız olabilir. Her bir seçenek, daha sonra daha ayrıntılı olarak ele alınacaktır.

(Önerilir) Önceden oluşturulmuş Android veya iOS yapılarını içe aktarma

Unity için Harici Bağımlılık Yöneticisi'ni kullanarak Maven veya CocoaPods'taki önceden oluşturulmuş yapıları içe aktarın. Bu eklenti, GoogleMobileAds eklentisine dahildir.

Mevcut yapıları içe aktarmak için içe aktarma işlemlerinizi tanımlamak üzere bir yapılandırma dosyası oluşturun. Dosya adı ve yolu için aşağıdaki şartlar geçerlidir:

  • Dosya, /Editor/ klasöründe bulunmalıdır.
  • Dosya adı Dependencies.xml ile bitmelidir.

Örneğin, AdPub adlı varsayımsal bir reklam ağı için özel etkinlik bağdaştırıcılarını içe aktarmak üzere dosyayı oluşturun:

Assets/AdPub/Editor/AdPubDependencies.xml

Ardından, AdPubDependencies.xml dosyası içinde bağımlılıklarınızı tanımlayın. İçe aktarma işlemlerini yapılandırma kurallarını Unity'ye Giriş için Harici Bağımlılık Yöneticisi'nde bulabilirsiniz. Aşağıdaki kod snippet'i, Android ve iOS SDK'sının yanı sıra varsayımsal bir "AdPub" reklam ağı için özel etkinlik kitaplıkları içerir.

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>

Özel etkinlik yapınızın gerekli reklam ağı SDK'sına zaten bağımlılığı varsa SDK bağımlılığını açıkça tanımlamanız gerekmez: Örnek

Harici Bağımlılık Yöneticisi, yapılandırma değişikliklerini otomatik olarak izler ve bağımlılıkları çözer. Aşağıdaki menü komutunu kullanarak manuel çözüm de uygulayabilirsiniz:

Assets > External Dependency Manager > Android Resolver > Force Resolve

AAR eklentilerini ve Android kitaplıklarını içe aktarma

Unity, Android kitaplık projelerinin yanı sıra *.aar dosyalarının da içe aktarılmasını destekler. Android özel etkinliğiniz bu şekilde paketlenmişse bu dosyaları Unity projenize nasıl ekleyeceğinizle ilgili talimatlar için AAR eklentileri ve Android Kitaplıkları bölümüne bakın.

Java ve Kotlin kaynak dosyalarını içe aktarma

Unity 2018.2 veya sonraki sürümlerden itibaren, Android özel etkinlik kodunuz derlenmemiş *.java veya *.kt dosyalarından oluşuyorsa Java veya Kotlin kaynak dosyalarını eklenti olarak kullanabilirsiniz.

iOS kaynak dosyalarını ve statik kitaplıkları içe aktarma

Unity *.framework yapıları, *.h ve *.m kaynak dosyalarını destekler. iOS yapılarını ve kaynak dosyalarını içe aktarma işlemi, Unity'nin yerel eklentiler kılavuzunda açıklanmıştır.

Özel etkinlikleri reklam inceleyici ile test etme

Reklam inceleyici, özel etkinliklerin uygulamanıza doğru şekilde aktarılıp aktarılmadığını test etmek için kullanılabilir. Reklam inceleyici yalnızca hareketlerle veya çok az kodla programatik olarak açılabilir.

(İsteğe bağlı) C# komut dosyalarından üçüncü taraf SDK yerel yöntemlerini çağırma

Üçüncü taraf reklam ağı SDK'ları, doğrudan Android veya iOS yöntemlerinin çağrılmasını gerektiren özel gereksinimlere sahip olabilir. Bu yöntemleri doğrudan çağırma süreci şu şekildedir:

  1. Platform istemcileri için ortak bir arayüz tanımlama
  2. Desteklenmeyen platformlar için varsayılan istemci uygulama
  3. Android yöntemlerini çağırmak için bir Android istemcisi uygulama
  4. iOS yöntemlerini çağırmak için bir iOS istemcisi uygulayın
  5. iOS ve Android istemcileri arasında koşullu olarak geçiş yapmak için istemci fabrikası özelliğini uygulayın
  6. Tüm üçüncü taraf reklam ağı SDK işlevlerine erişmek için bir API tanımlama

Aşağıdaki bölümde, bu adımların Android ve iOS'teki yöntemleri çağırabilen C# API'sinde "AdPub" adlı varsayıma dayalı bir reklam ağı için nasıl uygulandığı gösterilmektedir:

Android

package com.adpub.android;

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

iOS

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

Platform istemcileri için ortak bir arayüz tanımlama

Temel Android ve iOS API'sini temsil eden bir yöntemle IAdPubClient arayüzü oluşturun.

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

Desteklenmeyen platformlar için varsayılan istemci tanımlama

Yalnızca yöntemin adını günlüğe kaydeden IAdPubClient arayüzünü uygulayan bir DefaultClient sınıfı oluşturun. Unity düzenleyicisi ve Android ya da iOS dışındaki tüm platformlar için bu uygulamayı kullanın.

Assets/AdPub/Common/DefaultClient.cs

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

iOS platform istemcisi uygulama

iOS'te IAdPubClient arayüzünü uygulayan bir iOSAdPubClient sınıfı oluşturun. Bu uygulama, iOS AdPubSdk sınıfında setHasUserConsent() yöntemini çağırmak için InteropServices kullanır.

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

Daha sonra, yukarıda tanımlanan GADUAdPubSetHasUserConsent() yöntemini uygulayın. Unity'den gelen yöntem çağrısını işlemek için AdPubClientBridge.m yöntemini bir C yöntemiyle oluşturun ve AdPubSDK yöntemini çağırın.GADUAdPubSetHasUserConsent()

AdPubClientBridge bir iOS kaynak dosyasıdır ve Unity'nin yerel eklentiler kılavuzunda açıklandığı gibi Plugins/iOS klasörüne yerleştirilmelidir.

Assets/AdPub/Plugins/iOS/AdPubClientBridge.m

#import <AdPubSDK/AdPubSDK.h>

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

Bir Android platform istemcisi uygulama

Android'de IAdPubClient arayüzünü uygulayan bir AndroidAdPubCient sınıfı oluşturun. Bu uygulama, Android statik yöntemini setHasUserConsent() çağırmak için Android Java yardımcı sınıflarını kullanır.

Android Java yardımcı sınıfları yalnızca Android çalışma zamanında kullanılabildiğinden, sınıfı kod snippet'inde gösterildiği gibi sarmalamak için UNITY_ANDROID derleyici yönergesini kullanarak derleme hatalarını önleyebilirsiniz. Alternatif olarak, bu sorunu çözmek için Unity 2017.4 ve sonraki sürümlerde Derleme tanımları'nı kullanabilirsiniz.

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

Doğru istemci uygulamasını döndürmek için fabrika yöntemi oluşturun

Artık her platform için istemci uygulamalarına sahip olduğunuza göre, çalışma zamanı platformuna bağlı olarak IAdPubClient arayüzünün doğru uygulamasını döndürmek için bir AdPubClientFactory sınıfı oluşturun. Bu sınıf, doğru IAdPubClientistemcisini döndürmek için derleyici yönergelerini kullanır.

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

Her arayüz yöntemi için genel bir API tanımlayın

IAdPubClient arayüzünüzdeki her istemci yöntemi için yöntem çağrıları içeren bir AdPubApi sınıfı oluşturun. Bu sınıf, IAdPubClient örneğini almak için AdPubClientFactory protokolünü kullanır ve temel SDK işlevleri için bu istemciyi çağırır.

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

Yeni tanımladığınız API'yi çağırın

Yukarıda tanımlanan API'yi şu şekilde çağırabilirsiniz:

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

Ek üçüncü taraf reklam ağı bağdaştırıcısı örnekleri

Çağrıları iOS ve Android yöntemlerine sarmalamak üzere C# API'lerini uygulayan üçüncü taraf uyumlulaştırma bağdaştırıcılarına ilişkin diğer örnekler için Google Mobile Ads Unity eklentisi GitHub deposunu ziyaret edin.