Doğal reklamlar özel etkinlikleri

Platform seçin: Android iOS Android (Eski)

Ön koşullar

Özel etkinlik kurulumunu tamamlayın.

Doğal reklam isteme

Şelale uyumlulaştırması zincirinde özel etkinlik satır öğesine ulaşıldığında, özel etkinlik oluştururken sağladığınız sınıf adında loadNativeAd() yöntemi çağrılır. Bu durumda, bu yöntem SampleCustomEvent içinde yer alır ve SampleNativeCustomEventLoader içindeki loadNativeAd() yöntemini çağırır.

Doğal reklam isteğinde bulunmak için loadNativeAd() uygulayacak şekilde Adapter genişleten bir sınıf oluşturun veya değiştirin. Adapter sınıfını genişleten bir sınıf zaten varsa loadNativeAd() sınıfını burada uygulayın. Ayrıca, UnifiedNativeAdMapper uygulayacak yeni bir sınıf oluşturun.

Özel etkinlik örneğimizde, SampleCustomEvent, Adapter sınıfını genişletir ve 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:

• Doğal reklam yükleniyor.

• UnifiedNativeAdMapper sınıfını uygulama

• Reklam etkinliği geri çağırmalarını alma ve Google Mobile Ads SDK (Legacy) platformuna 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 örneklendirirken gerektirdiği 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() yöntemini çağırırsınız. onSuccess(), MediationNativeAd uygulayan sınıfın bir örneği iletilerek çağrılır.

Genellikle bu yöntemler, bağdaştırıcınızın uyguladığı üçüncü taraf SDK'sından gelen geri çağırmalarda uygulanır. Bu örnekte, Örnek SDK'da alakalı geri çağırmalar içeren bir SampleAdListener vardı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));
}

Haritalar'daki doğal reklamlar

Farklı SDK'ların doğal reklamlar için kendi benzersiz biçimleri vardır. Örneğin, biri "title" alanı içeren nesneler döndürürken diğeri "headline" alanına sahip olabilir. Ayrıca gösterimleri izlemek ve tıklamaları işlemek için kullanılan yöntemler SDK'dan SDK'ya farklılık gösterebilir.

UnifiedNativeAdMapper, bu farklılıkları gidermek ve uyumlulaştırılmış bir SDK'nın doğal reklam nesnesini Google Mobile Ads SDK (Legacy) tarafından beklenen arayüze uyarlamakla sorumludur. Özel etkinlikler, uyumlulaştırılmış SDK'larına özel kendi eşleyicilerini oluşturmak için bu sınıfı genişletmelidir. Örnek özel etkinlik projemizden bir reklam eşleyici örneği:

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 yapıcı kodunu daha yakından inceleyelim.

Uyumlulaştırılmış doğal reklam nesnesine referans tutma

Oluşturucu, Örnek SDK'nın doğal reklamları için kullandığı doğal reklam sınıfı olan SampleNativeAd parametresini kabul eder. Eşleyicinin, tıklama ve gösterim etkinliklerini iletebilmesi için uyumlulaştırılmış reklama referans vermesi gerekir. SampleNativeAd, yerel değişken olarak saklanır.

Eşlenen öğe özelliklerini ayarlama

Oluşturucu, UnifiedNativeAdMapper içindeki öğeleri doldurmak için SampleNativeAd nesnesini kullanır.

Bu snippet, uyumlulaştırılan 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 eşleyici sorumludur.

Harita resmi öğeleri

Resim öğelerini eşlemek, double veya String gibi veri türlerini eşlemekten daha karmaşıktır. Resimler otomatik olarak indirilebilir veya URL değerleri olarak döndürülebilir. Piksel/dpi ölçekleri de farklılık gösterebilir.

Bu ayrıntıları yönetmenize yardımcı olmak için Google Mobile Ads SDK (Legacy), NativeAd.Image sınıfını sağlar. Uyumlulaştırılmış bir doğal 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şlenen resim sınıfını kullanır:

Java

setIcon(new SampleNativeMappedImage(ad.getAppIcon(), ad.getAppIconUri(),
    SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));

Ekstralar paketine alan ekleme

Uyumlulaştırılmış bazı SDK'lar, AdMob doğal reklam biçimindekilerin 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ükemmellik 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 sayfasından alınan aşağıdaki snippet'te, Reklam Seçenekleri simgesinin nasıl sağlanacağı gösterilmektedir:

Java

public SampleNativeAdMapper(SampleNativeAd ad) {
    ...
    setAdChoicesContent(sampleAd.getInformationIcon());
}

Gösterim ve tıklama etkinlikleri

Hem Google Mobile Ads SDK (Legacy) hem de uyumlulaştırılan SDK'nın bir gösterim veya tıklamanın ne zaman gerçekleştiğini bilmesi gerekir ancak bu etkinlikleri yalnızca bir SDK'nın izlemesi gerekir. Uyumlulaştırılan 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 (Legacy) ile tıklamaları ve gösterimleri izleme

Uyumlulaştırılan SDK kendi gösterim ve tıklama izleme işlemlerini gerçekleştirmiyor ancak tıklama ve gösterimleri kaydetmek için yöntemler sağlıyorsa Google Mobile Ads SDK (Legacy) bu etkinlikleri izleyebilir ve bağdaştırıcıyı bilgilendirebilir. UnifiedNativeAdMapper sınıfı, uyumlulaştırılan doğal reklam nesnesinde ilgili yöntemi çağırmak için özel etkinliklerin uygulayabileceği iki yöntem (recordImpression() ve handleClick()) içerir:

Java

@Override
public void recordImpression() {
  sampleAd.recordImpression();
}

@Override
public void handleClick(View view) {
  sampleAd.handleClick(view);
}

SampleNativeAdMapper, Sample SDK'nın doğal reklam nesnesine bir referans içerdiğinden, tıklama veya gösterim bildirmek için bu nesnede uygun yöntemi çağırabilir. handleClick() yönteminin tek bir parametre aldığını unutmayın: tıklamayı alan doğal reklam öğesine karşılık gelen View nesnesi.

Uyumlulaştırılmış SDK ile tıklamaları ve gösterimleri izleme

Uyumlulaştırılmış bazı SDK'lar, tıklamaları ve gösterimleri kendi başlarına izlemeyi tercih edebilir. Bu durumda, UnifiedNativeAdMapper öğenizin oluşturucusunda 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);

Tıklama ve gösterim izlemeyi geçersiz kılan özel etkinliklerin, onAdClicked() ve onAdImpression() etkinliklerini Google Mobile Ads SDK'sına bildirmesi gerekir.

Uyumlulaştırılan SDK'nın, gösterimleri ve tıklamaları izlemek için muhtemelen görüntülemelere erişmesi gerekir. Özel etkinlik, trackViews() yöntemini geçersiz kılmalı ve doğal reklamın görünümünü izlenecek uyumlulaştırılmış SDK'ya iletmek için bu yöntemi kullanmalıdır. Özel etkinlik örnek projemizdeki örnek SDK (bu kılavuzun kod snippet'leri bu projeden alınmıştır) bu yaklaşımı kullanmaz. Ancak kullansaydı ö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);
}

Uyumlulaştırılan SDK, bağımsız öğelerin izlenmesini destekliyorsa hangi görünümlerin tıklanabilir hale getirilmesi gerektiğini görmek için clickableAssetViews öğesinin içine bakabilir. Bu eşleme, NativeAdAssetNames içindeki bir öğe adıyla anahtarlanır. UnifiedNativeAdMapper, özel etkinliklerin görünüme yapılan tüm referansları serbest bırakmak ve görünümü doğal reklam nesnesinden ayırmak için geçersiz kılabileceği karşılık gelen bir untrackView() yöntemini sunar.

Uyumlulaştırma etkinliklerini Google Mobile Ads SDK (Legacy) adlı yayıncıya yönlendirme

Uyumlulaştırmanın desteklediği tüm geri çağırmaları MediationNativeAdCallback belgelerinde bulabilirsiniz.

Uygulamanızın Google Mobile Ads SDK (Legacy) platformundan bu eşdeğer etkinlikleri alabilmesi için özel etkinliğinizin bu geri çağırmalardan mümkün olduğunca fazlasını yönlendirmesi önemlidir. Geri çağırmaların kullanımına ilişkin bir örneği aşağıda bulabilirsiniz:

Böylece doğal reklamlar için özel etkinliklerin uygulanması tamamlanır. Örneğin tamamını GitHub'da bulabilirsiniz.