Özel etkinlikler oluştur

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

Ön koşullar

  • Başlayın bölümünü tamamlayın. Unity uygulamanıza Google Mobil Reklamlar Unity eklentisi zaten aktarılmış olmalıdır.

  • Android ve iOS için önceden oluşturulmuş özel etkinlik bağdaştırıcılar. Özel etkinlik bağdaştırıcılar oluşturmak için Android ve iOS'teki özel etkinlik kılavuzlarımızı inceleyin.

Özel etkinlik tanımlama

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

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

Parametreleri doldurma
Sınıf Adı (iOS)

iOS için özel etkinliği uygulayan sınıfın adını girin.

Sınıfınız Swift'te aktif hale getirildiyse 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 adından farklıysa hedef adı zorunludur. Hedef adla birlikte şu şekilde 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 için Class Name parametresi olarak verdiğiniz değerin Android'in tam nitelikli sınıf adı olduğundan emin olun (ör. com.google.ads.mediation.sample.customevent.SampleCustomEvent).
Şirket Etkinlik için benzersiz bir ad girin.
Parametre Özel etkinliğinize bir dize bağımsız değişkeni (ör. reklam birimi kimliği) iletmek istiyorsanız

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

Özel etkinliklerin düzgün ç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 birden çok yolu 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 biçimine bağlı olarak her kitaplık için farklı bir içe aktarma stratejisine ihtiyacınız olabilir. Her seçenek daha sonra ayrıntılı olarak ele alınacaktır.

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

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

Mevcut yapıları içe aktarmak için içe aktarma işlemlerinizi tanımlayacak 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ında bağımlılıklarınızı tanımlayın. İçe aktarma işlemlerini yapılandırmayla ilgili kuralları Unity Başlangıç İçin Harici Bağımlılık Yöneticisi bölümünde bulabilirsiniz. Aşağıdaki kod snippet'inde, varsayımsal bir "AdPub" reklam ağı için Android ve iOS SDK'sı ve özel etkinlik kitaplıkları yer almaktadır.

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ızda gerekli reklam ağı SDK'sına yönelik bir bağımlılık 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. Manuel çözümü aşağıdaki menü komutuyla da yürütebilirsiniz:

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 içe aktarılmasını destekler. Android özel etkinliğiniz bu şekilde paketlenmişse bu dosyaları Unity projenize ekleme talimatları için AAR eklentileri ve Android kitaplıkları başlıklı makaleyi inceleyin.

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

Unity 2018.2 veya sonraki sürümlerde, 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ını, *.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 Denetleyici, yalnızca hareketlerle veya minimum 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ının, Android veya iOS yöntemlerini doğrudan çağırmayı gerektiren özel koşulları olabilir. Bu yöntemleri doğrudan çağırma işlemi aşağıdaki gibidir:

  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 Android istemcisi uygulama
  4. iOS yöntemlerini çağırmak için iOS istemcisi uygulama
  5. iOS ve Android istemcileri arasında koşullu olarak geçiş yapmak için bir istemci fabrikası 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 bir C# API'sinde "AdPub" adlı varsayımsal 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'yi 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öntem adını günlüğe kaydeden IAdPubClient arayüzünü uygulayan bir DefaultClient sınıfı oluşturun. Unity düzenleyici 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ındaki setHasUserConsent() yöntemini çağırmak için InteropServices'i 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

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

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

Android platform istemcisi uygulama

Android'de IAdPubClient arayüzünü uygulayan bir AndroidAdPubCient sınıfı oluşturun. Bu uygulama, Android statik yöntemi setHasUserConsent()'yi ç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 bir fabrika yöntemi oluşturun

Her platform için istemci uygulamalarınız olduğuna 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 IAdPubClientistemciyi 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 herkese açık 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ği almak için AdPubClientFactory'ü kullanır ve temel SDK işlevleri için bu müşteriyi ç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ımlanan API'nizi çağırma

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

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

iOS ve Android yöntemlerine yapılan çağrıları sarmalamak için C# API'lerini uygulayan üçüncü taraf uyumlulaştırma bağdaştırıcılarına dair ek örnekler için Google Mobil Reklamlar Unity eklentisi Github deposunu ziyaret edin.