Ön koşullar
Özel etkinlik kurulumunu tamamlayın.
Yerel reklam isteme
Şelale uyumlulaştırması zincirinde özel etkinlik satır öğesine ulaşıldığında, özel etkinlik oluştururken belirttiğiniz sınıf adında loadNativeAd()
yöntemi çağrılır. Bu durumda, söz konusu yöntem SampleCustomEvent
içindedir ve SampleNativeCustomEventLoader
içindeki loadNativeAd()
yöntemini çağırır.
Yerel reklam istemek için loadNativeAd()
'ü uygulamak üzere Adapter
'ü genişleten bir sınıf oluşturun veya mevcut bir sınıfta değişiklik yapın. Adapter
sınıfını genişleten bir sınıf zaten varsa loadNativeAd()
sınıfını buraya uygulayın. Ayrıca, UnifiedNativeAdMapper
özelliğini uygulamak için yeni bir sınıf oluşturun.
Özel etkinlik örneğimizde, SampleCustomEvent
sınıfını genişleten SampleCustomEvent
, ardından SampleNativeCustomEventLoader
sınıfına yetki verir.
Java
package com.google.ads.mediation.sample.customevent; import com.google.android.gms.ads.mediation.Adapter; import com.google.android.gms.ads.mediation.MediationAdConfiguration; import com.google.android.gms.ads.mediation.MediationAdLoadCallback; import com.google.android.gms.ads.mediation.MediationNativeAdCallback; ... public class SampleCustomEvent extends Adapter { private SampleNativeCustomEventLoader nativeLoader; @Override public void loadNativeAd( @NonNull MediationNativeAdConfiguration adConfiguration, @NonNull MediationAdLoadCallback<UnifiedNativeAdMapper, MediationNativeAdCallback> callback) { nativeLoader = new SampleNativeCustomEventLoader(adConfiguration, callback); nativeLoader.loadAd(); } }
SampleNativeCustomEventLoader
aşağıdaki görevlerden sorumludur:
Yerel reklamın yüklenmesi.
UnifiedNativeAdMapper
sınıfı uygulanıyor.Google Mobile Ads SDK'sına reklam etkinliği geri çağırma isteklerini alma ve bildirme.
AdMob kullanıcı arayüzünde tanımlanan isteğe bağlı parametre, reklam yapılandırmasına dahil edilir. Parametreye adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD)
üzerinden erişilebilir.
Bu parametre genellikle bir reklam ağı SDK'sının reklam nesnesi oluştururken ihtiyaç duyduğu bir reklam birimi tanımlayıcısıdır.
Java
package com.google.ads.mediation.sample.customevent; import com.google.android.gms.ads.mediation.Adapter; import com.google.android.gms.ads.mediation.MediationNativeAdConfiguration; import com.google.android.gms.ads.mediation.MediationAdLoadCallback; import com.google.android.gms.ads.mediation.MediationNativeAdCallback; ... public class SampleNativeCustomEventLoader extends SampleNativeAdListener { /** Configuration for requesting the native ad from the third-party network. */ private final MediationNativeAdConfiguration mediationNativeAdConfiguration; /** Callback that fires on loading success or failure. */ private final MediationAdLoadCallback<UnifiedNativeAdMapper, MediationNativeAdCallback> mediationAdLoadCallback; /** Callback for native ad events. */ private MediationNativeAdCallback nativeAdCallback; /** Constructor */ public SampleNativeCustomEventLoader( @NonNull MediationNativeAdConfiguration mediationNativeAdConfiguration, @NonNull MediationAdLoadCallback<MediationNativeAd, MediationNativeAdCallback> mediationAdLoadCallback) { this.mediationNativeAdConfiguration = mediationNativeAdConfiguration; this.mediationAdLoadCallback = mediationAdLoadCallback; } /** Loads the native ad from the third-party ad network. */ public void loadAd() { // Create one of the Sample SDK's ad loaders to request ads. Log.i("NativeCustomEvent", "Begin loading native ad."); SampleNativeAdLoader loader = new SampleNativeAdLoader(mediationNativeAdConfiguration.getContext()); // All custom events have a server parameter named "parameter" that returns // back the parameter entered into the UI when defining the custom event. String serverParameter = mediationNativeAdConfiguration .getServerParameters() .getString(MediationConfiguration .CUSTOM_EVENT_SERVER_PARAMETER_FIELD); Log.d("NativeCustomEvent", "Received server parameter."); loader.setAdUnit(serverParameter); // Create a native request to give to the SampleNativeAdLoader. SampleNativeAdRequest request = new SampleNativeAdRequest(); NativeAdOptions options = mediationNativeAdConfiguration.getNativeAdOptions(); if (options != null) { // If the NativeAdOptions' shouldReturnUrlsForImageAssets is true, the adapter should // send just the URLs for the images. request.setShouldDownloadImages(!options.shouldReturnUrlsForImageAssets()); request.setShouldDownloadMultipleImages(options.shouldRequestMultipleImages()); switch (options.getMediaAspectRatio()) { case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_LANDSCAPE: request.setPreferredImageOrientation(SampleNativeAdRequest.IMAGE_ORIENTATION_LANDSCAPE); break; case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_PORTRAIT: request.setPreferredImageOrientation(SampleNativeAdRequest.IMAGE_ORIENTATION_PORTRAIT); break; case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_SQUARE: case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_ANY: case NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_UNKNOWN: default: request.setPreferredImageOrientation(SampleNativeAdRequest.IMAGE_ORIENTATION_ANY); } } loader.setNativeAdListener(this); // Begin a request. Log.i("NativeCustomEvent", "Start fetching native ad."); loader.fetchAd(request); } }
Reklamın başarıyla getirilip getirilmediğine veya bir hatayla karşılaşıp karşılaşmadığına bağlı olarak onSuccess()
veya onFailure()
çağrısını yaparsınız.
onSuccess()
, MediationNativeAd
'u uygulayan sınıfın bir örneği geçirilerek çağrılır.
Bu yöntemler genellikle, bağdaştırıcının uyguladığı üçüncü taraf SDK'dan gelen geri çağırma işlevlerinin içinde uygulanır. Bu örnekte, Örnek SDK'da alakalı geri çağırmalara sahip bir SampleAdListener
bulunmaktadır:
Java
@Override public void onNativeAdFetched(SampleNativeAd ad) { SampleUnifiedNativeAdMapper mapper = new SampleUnifiedNativeAdMapper(ad); mediationNativeAdCallback = mediationAdLoadCallback.onSuccess(mapper); } @Override public void onAdFetchFailed(SampleErrorCode errorCode) { mediationAdLoadCallback.onFailure(SampleCustomEventError.createSampleSdkError(errorCode)); }
Doğal reklamları eşleştirme
Farklı SDK'ların yerel reklamlar için kendine özgü biçimleri vardır. Örneğin, bir işlev "title" alanı içeren nesneler döndürebilirken başka bir işlev "headline" alanına sahip olabilir. Ayrıca, gösterimleri izlemek ve tıklamaları işlemek için kullanılan yöntemler SDK'ya göre değişiklik gösterebilir.
UnifiedNativeAdMapper
, bu farklılıkları uzlaştırmaktan ve aracı SDK'nın yerel reklam nesnesini Google Mobile Ads SDK'sı tarafından beklenen arayüzle eşleşecek şekilde uyarlamaktan sorumludur. Özel etkinlikler, aracılı SDK'larına özel kendi eşleyicilerini oluşturmak için bu sınıfı genişletmelidir. Aşağıda, örnek özel etkinlik projemizden
bir reklam eşleme aracını görebilirsiniz:
Java
package com.google.ads.mediation.sample.customevent; import com.google.android.gms.ads.mediation.UnifiedNativeAdMapper; import com.google.android.gms.ads.nativead.NativeAd; ... public class SampleUnifiedNativeAdMapper extends UnifiedNativeAdMapper { private final SampleNativeAd sampleAd; public SampleUnifiedNativeAdMapper(SampleNativeAd ad) { sampleAd = ad; setHeadline(sampleAd.getHeadline()); setBody(sampleAd.getBody()); setCallToAction(sampleAd.getCallToAction()); setStarRating(sampleAd.getStarRating()); setStore(sampleAd.getStoreName()); setIcon( new SampleNativeMappedImage( ad.getIcon(), ad.getIconUri(), SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE)); setAdvertiser(ad.getAdvertiser()); List<NativeAd.Image> imagesList = new ArrayList<NativeAd.Image>(); imagesList.add(new SampleNativeMappedImage(ad.getImage(), ad.getImageUri(), SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE)); setImages(imagesList); if (sampleAd.getPrice() != null) { NumberFormat formatter = NumberFormat.getCurrencyInstance(); String priceString = formatter.format(sampleAd.getPrice()); setPrice(priceString); } Bundle extras = new Bundle(); extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, ad.getDegreeOfAwesomeness()); this.setExtras(extras); setOverrideClickHandling(false); setOverrideImpressionRecording(false); setAdChoicesContent(sampleAd.getInformationIcon()); } @Override public void recordImpression() { sampleAd.recordImpression(); } @Override public void handleClick(View view) { sampleAd.handleClick(view); } // The Sample SDK doesn't do its own impression/click tracking, instead relies on its // publishers calling the recordImpression and handleClick methods on its native ad object. So // there's no need to pass a reference to the View being used to display the native ad. If // your mediated network does need a reference to the view, the following method can be used // to provide one. @Override public void trackViews(View containerView, Map<String, View> clickableAssetViews, Map<String, View> nonClickableAssetViews) { super.trackViews(containerView, clickableAssetViews, nonClickableAssetViews); // If your ad network SDK does its own impression tracking, here is where you can track the // top level native ad view and its individual asset views. } @Override public void untrackView(View view) { super.untrackView(view); // Here you would remove any trackers from the View added in trackView. } }
Şimdi de oluşturucu koduna daha yakından bakalım.
Uyumlulaştırılmış yerel reklam nesnesine referans tutma
Oluşturucu, Sample SDK'nın doğal reklamları için kullandığı doğal reklam sınıfı olan SampleNativeAd
parametresini kabul eder. Haritacının, tıklama ve gösterim etkinliklerini iletebilmesi için
uyumlulaştırılmış reklama bir referansı olması gerekir. SampleNativeAd
yerel değişken olarak saklanır.
Eşlenen öğe özelliklerini ayarlama
Oluşturucu, UnifiedNativeAdMapper
öğelerini doldurmak için SampleNativeAd
nesnesini kullanır.
Bu snippet, aracılı reklamın fiyat verilerini alır ve eşleyicinin fiyatını ayarlamak için kullanır:
Java
if (sampleAd.getPrice() != null) { NumberFormat formatter = NumberFormat.getCurrencyInstance(); String priceString = formatter.format(sampleAd.getPrice()); setPrice(priceString); }
Bu örnekte, uyumlulaştırılmış reklam fiyatı double
olarak depolarken AdMob aynı öğe için String
kullanır. Bu tür dönüşümlerin işlenmesinden haritacı sorumludur.
Resim öğelerini eşleme
Resim öğelerini eşlemek, double
veya String
gibi veri türlerini eşlemeye kıyasla daha karmaşıktır. Resimler otomatik olarak indirilebilir veya URL değerleri olarak döndürülebilir. Piksel-dpi ölçekleri de değişiklik gösterebilir.
Bu ayrıntıları yönetmenize yardımcı olmak için Google Mobile Ads SDK'sı NativeAd.Image
sınıfını sağlar. Aracılıklı bir yerel reklamı eşlemek için UnifiedNativeAdMapper
alt sınıfı oluşturmanız gerektiği gibi, resim öğelerini eşlerken de NativeAd.Image
alt sınıfı oluşturmanız gerekir.
Özel etkinliğin SampleNativeMappedImage
sınıfı için bir örnek aşağıda verilmiştir:
Java
public class SampleNativeMappedImage extends NativeAd.Image { private Drawable drawable; private Uri imageUri; private double scale; public SampleNativeMappedImage(Drawable drawable, Uri imageUri, double scale) { this.drawable = drawable; this.imageUri = imageUri; this.scale = scale; } @Override public Drawable getDrawable() { return drawable; } @Override public Uri getUri() { return imageUri; } @Override public double getScale() { return scale; } }
SampleNativeAdMapper
, eşleyicinin simge resim öğesini ayarlamak için bu satırda eşlenmiş resim sınıfını kullanır:
Java
setIcon(new SampleNativeMappedImage(ad.getAppIcon(), ad.getAppIconUri(), SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));
Ekstralar paketine alan ekleme
Bazı uyumlulaştırılmış SDK'lar, AdMob yerel reklam biçiminde olanlar dışında ek öğeler sağlar. UnifiedNativeAdMapper
sınıfı, bu öğeleri yayıncılara iletmek için kullanılan bir setExtras()
yöntemi içerir. SampleNativeAdMapper
, Örnek SDK'nın "müthişlik derecesi" öğesi için bunu kullanır:
Java
Bundle extras = new Bundle(); extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, ad.getDegreeOfAwesomeness()); this.setExtras(extras);
Yayıncılar, NativeAd
sınıfının getExtras()
yöntemini kullanarak verileri alabilir.
Reklam Seçenekleri
Özel etkinliğiniz, UnifiedNativeAdMapper
üzerinde setAdChoicesContent()
yöntemini kullanarak bir Reklam Seçenekleri simgesi sağlamaktan sorumludur. SampleNativeAdMapper
sitesinden Reklam Seçenekleri simgesinin nasıl sağlanacağını gösteren snippet'i aşağıda bulabilirsiniz:
Java
public SampleNativeAdMapper(SampleNativeAd ad) { ... setAdChoicesContent(sampleAd.getInformationIcon()); }
Gösterim ve tıklama etkinlikleri
Hem Google Mobile Ads SDK'sının hem de aracı SDK'nın bir gösterim veya tıklamanın ne zaman gerçekleştiğini bilmesi gerekir ancak bu etkinliklerin yalnızca bir SDK tarafından izlenmesi gerekir. Aracılıklı SDK'nın gösterimleri ve tıklamaları kendi başına izlemeyi destekleyip desteklemediğine bağlı olarak, özel etkinliklerin kullanabileceği iki farklı yaklaşım vardır.
Google Mobile Ads SDK'sı ile tıklamaları ve gösterimleri izleme
Uyumlulaştırılmış SDK kendi gösterim ve tıklama izlemesini gerçekleştirmez ancak tıklamaları ve gösterimleri kaydetme yöntemleri sağlarsa Google Mobile Ads SDK'sı bu etkinlikleri izleyebilir ve bağdaştırıcıyı bilgilendirebilir. UnifiedNativeAdMapper
sınıfı, özel etkinliklerin aracılı doğal reklam nesnesinde ilgili yöntemi çağırmak için uygulayabileceği iki yöntem içerir: recordImpression()
ve handleClick()
:
Java
@Override public void recordImpression() { sampleAd.recordImpression(); } @Override public void handleClick(View view) { sampleAd.handleClick(view); }
SampleNativeAdMapper
, Örnek SDK'nın yerel reklam nesnesine referans sunduğundan bir tıklama veya gösterimi bildirmek için bu nesnede uygun yöntemi çağırabilir. handleClick()
yönteminin tek bir parametre aldığını unutmayın: Tıklamayı alan yerel reklam öğesine karşılık gelen View
nesnesi.
Arabulucu SDK'sı ile tıklamaları ve gösterimleri izleme
Bazı aracı SDK'lar tıklamaları ve gösterimleri kendi başlarına izlemeyi tercih edebilir. Bu durumda, UnifiedNativeAdMapper
sınıfınızın oluşturucusuna aşağıdaki iki çağrıyı yaparak varsayılan tıklama ve gösterim izlemeyi geçersiz kılmanız gerekir:
Java
setOverrideClickHandling(true); setOverrideImpressionRecording(true);
onAdClicked()
ve onAdImpression()
etkinliklerini Google Mobile Ads SDK'sına bildirmek için tıklama ve gösterim izlemeyi geçersiz kılan özel etkinlikler gereklidir.
Gösterimleri ve tıklamaları izlemek için aracı SDK'nın, izlemeyi etkinleştirmek amacıyla görünümlere erişmesi gerekir. Özel etkinlik, trackViews()
yöntemini geçersiz kılmalı ve izlemek için doğal reklamın görünümünü aracı SDK'ya iletmek üzere bu yöntemi kullanmalıdır. Özel etkinlik örnek projemizdeki örnek SDK'da (bu kılavuzun kod snippet'leri bu projeden alınmıştır) bu yaklaşım kullanılmaz. Ancak bu yaklaşım kullanılsaydı özel etkinlik kodu aşağıdaki gibi görünürdü:
Java
@Override public void trackViews(View containerView, Map<String, View> clickableAssetViews, Map<String, View> nonClickableAssetViews) { sampleAd.setNativeAdViewForTracking(containerView); }
Aracılıklı SDK, tek tek öğelerin izlenmesini destekliyorsa hangi görünümlerin tıklanabilir hale getirileceğini görmek için clickableAssetViews
içine bakabilir. Bu harita, NativeAdAssetNames
içindeki bir öğe adına göre anahtarlanır. UnifiedNativeAdMapper
, görünüm referanslarını serbest bırakmak ve yerel reklam nesnesiyle ilişkisini kesmek için özel etkinliklerin geçersiz kılabileceği karşılık gelen bir untrackView()
yöntemi sunar.
Uyumlulaştırma etkinliklerini Google Mobile Ads SDK'sına yönlendirme
Uyumlulaştırmanın desteklediği tüm geri çağırma işlevlerini MediationNativeAdCallback
belgelerinde bulabilirsiniz.
Uygulamanızın bu eşdeğer etkinlikleri Google Mobile Ads SDK'sından alabilmesi için özel etkinliğinizin bu geri çağırmaların mümkün olduğunca çoğunu yönlendirmesi önemlidir. Aşağıda, geri çağırma işlevinin kullanımına dair bir örnek verilmiştir:
Bu işlemle, doğal reklamlar için özel etkinliklerin uygulanması tamamlanır. Örneğin tamamını GitHub'da bulabilirsiniz.