Doğal reklamlar özel etkinlikleri

Ön koşullar

Özel etkinlik kurulumunu tamamlayın.

Yerel reklam isteğinde bulunma

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

Yerel reklam isteğinde bulunmak için Adapter sınıfını genişleten bir sınıf oluşturun veya değiştirerek loadNativeAd()'yi uygulayın. Adapter öğesini genişleten bir sınıf zaten varsa loadNativeAd() öğesini orada uygulayın. Ayrıca, UnifiedNativeAdMapper uygulamak için yeni bir sınıf oluşturun.

Özel etkinlik örneğimizde, SampleCustomEvent, Adapter sınıfını genişletir ve ardından SampleNativeCustomEventLoader'e devreder.

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ını uygulama

  • Reklam etkinliği geri çağırmalarını Google Mobile Ads SDK'sına 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 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 getirilmesine veya bir hatayla karşılaşmasına bağlı olarak onSuccess() veya onFailure() çağrısını yaparsınız. onSuccess(), MediationNativeAd öğesini 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ğırmaların içinde uygulanır. Bu örnekte, Sample SDK'sında alakalı geri çağırmalar içeren bir SampleAdListener var:

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

Harita doğal reklamları

Farklı SDK'lar, doğal reklamlar için kendi benzersiz biçimlerine sahiptir. Birinde "title" alanı içeren nesneler döndürülürken diğerinde "headline" alanı olabilir. Ayrıca, gösterimleri izlemek ve tıklamaları işlemek için kullanılan yöntemler SDK'dan SDK'ya değişebilir.

UnifiedNativeAdMapper, bu farklılıkları uzlaştırmaktan ve aracılık edilen bir SDK'nın doğal reklam nesnesini Google Mobile Ads SDK'sının beklediği arayüze uyacak şekilde uyarlamaktan sorumludur. Özel etkinlikler, kendi aracılı SDK'larına özel eşleyiciler oluşturmak için bu sınıfı genişletmelidir. Örnek özel etkinlik projemizden bir örnek reklam eşleyici aşağıda verilmiştir:

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 oluşturucu kodunu daha yakından inceleyelim.

Uyumlulaştırılmış yerel reklam nesnesine referans tutma

Oluşturucu, SampleNativeAd parametresini kabul eder. Bu parametre, örnek SDK'nın doğal reklamları için kullandığı doğal reklam sınıfıdır. Eşleyici, tıklama ve gösterim etkinliklerini iletebilmesi için aracılı reklamla ilgili bir referansa ihtiyaç duyar. SampleNativeAd yerel değişken olarak saklanır.

Eşlenmiş öğe özelliklerini ayarlama

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

Bu snippet, aracılık edilen 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 saklarken AdMob aynı öğe için String kullanıyor. 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.

Google Mobile Ads SDK'sı, bu ayrıntıları yönetmenize yardımcı olmak için NativeAd.Image sınıfını sağlar. Aracılık edilen 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ıyla ilgili bir örneği aşağıda bulabilirsiniz:

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, bu satırda eşlenen resim sınıfını kullanarak eşleyenin simge resmi öğesini ayarlar:

Java

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

Ekstralar paketine alan ekleme

Bazı aracılık edilen SDK'lar, AdMob yerel 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 "harikalık derecesi" öğesi için bu özellikten yararlanı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ıngetExtras() 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'dan, Reklam Seçenekleri simgesinin nasıl sağlanacağını gösteren bir snippet aşağıda verilmiştir:

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ılık edilen SDK'nın bir gösterim veya tıklama gerçekleştiğinde bunu bilmesi gerekir ancak bu etkinlikleri yalnızca bir SDK'nın izlemesi gerekir. Aracılık edilen 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 yapmıyorsa ancak tıklamaları ve gösterimleri kaydetmek için yöntemler sağlıyorsa Google Mobile Ads SDK bu etkinlikleri izleyebilir ve bağdaştırıcıyı bilgilendirebilir. UnifiedNativeAdMapper sınıfı iki yöntem içerir: recordImpression() ve handleClick(). Özel etkinlikler, aracılık edilen yerel reklam nesnesinde karşılık gelen yöntemi çağırmak için bu yöntemleri uygulayabilir:

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 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 yerel reklam öğesine karşılık gelen handleClick() nesnesi.View

Aracılı SDK ile tıklamaları ve gösterimleri izleme

Bazı aracılık edilen SDK'lar, tıklamaları ve gösterimleri kendi başlarına izlemeyi tercih edebilir. Bu durumda, UnifiedNativeAdMapper 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 etkinlikler, onAdClicked() ve onAdImpression() etkinliklerini Google Mobile Ads SDK'sına bildirmek için gereklidir.

Gösterimleri ve tıklamaları izlemek için, aracılık edilen SDK'nın izlemeyi etkinleştirmek üzere görünümlere erişmesi gerekebilir. Özel etkinlik, trackViews() yöntemini geçersiz kılmalı ve izlenecek yerel reklamın görünümünü aracılık edilen SDK'ya iletmek için bu yöntemi kullanmalıdır. Özel etkinlik örneği projemizdeki örnek SDK (bu kılavuzdaki kod snippet'lerinin alındığı yer) bu yaklaşımı kullanmaz. Ancak bu yaklaşım kullanılsaydı özel etkinlik kodu şu şekilde görünürdü:

Java

@Override
public void trackViews(View containerView,
    Map<String, View> clickableAssetViews,
    Map<String, View> nonClickableAssetViews) {
  sampleAd.setNativeAdViewForTracking(containerView);
}

Aracılık edilen SDK, tek tek öğelerin izlenmesini destekliyorsa hangi görünümlerin tıklanabilir olması gerektiğini görmek için clickableAssetViews içine bakabilir. Bu harita, NativeAdAssetNames içindeki bir öğe adına göre anahtarlanır. UnifiedNativeAdMapper, özel etkinliklerin görünümle ilgili referansları serbest bırakmak ve görünümü yerel reklam nesnesinden ayırmak için geçersiz kılabileceği untrackView() yöntemini 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 Google Mobile Ads SDK'sından bu eşdeğer etkinlikleri alabilmesi için özel etkinliğinizin bu geri çağırmaların mümkün olduğunca çoğunu iletmesi önemlidir. Geri çağırmaları kullanma örneğini aşağıda bulabilirsiniz:

Böylece, yerel reklamlar için özel etkinlik uygulama işlemi tamamlanır. Örnek kodun tamamına GitHub'dan ulaşabilirsiniz.