Yerel reklam özel etkinlikleri

Ön koşullar

Özel etkinlik kurulumunu tamamlayın.

Doğal reklam isteme

Şelale uyumlulaştırma zincirinde özel etkinlik satır öğesine ulaşıldığında, özel etkinlik oluştururken sağladığınız sınıf adınathe loadNativeAd() method çağrılır. Bu örnekte, bu yöntem SampleCustomEvent içindedir ve daha sonrathe loadNativeAd() method içinde SampleNativeCustomEventLoaderçağrısı yapar.

Yerel reklam isteğinde bulunmak için loadNativeAd() uygulamasını uygulamak üzere Adapter öğesini genişleten bir sınıf oluşturun veya mevcut bir sınıfı değiştirin. Adapter öğesini genişleten bir sınıf zaten varsa loadNativeAd() öğesini burada uygulayın. Ayrıca, UnifiedNativeAdMapper yöntemini uygulamak için yeni bir sınıf oluşturun.

Özel etkinlik örneğimizde SampleCustomEvent,the Adapter interface uygulamasını uygular ve ardındanSampleNativeCustomEventLoaderöğesine 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 yükleniyor

• UnifiedNativeAdMapper interface

• Reklam etkinliği geri çağırmalarını Google Mobile Ads SDK'sına alma ve raporlama

Kullanıcı arayüzünde tanımlanan AdMob isteğe bağlı parametre, reklam yapılandırmasına dahildir. Parametreye adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD) üzerinden erişilebilir. Bu parametre, genellikle reklam ağı SDK'sının bir reklam nesnesi örneği oluştururken ihtiyaç duyduğu 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ğine geçirilerek ç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 Örnek SDK'da alakalı geri çağırma işlevleri olan bir SampleAdListener bulunur:

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

Yerel reklamları eşleme

Farklı SDK'ların yerel reklamlar için kendi benzersiz biçimleri vardır. Örneğin, biri "başlık" alanı içeren nesneleri döndürürken, diğeri "başlık" öğesine sahip olabilir. Ayrıca, gösterimleri izlemek ve tıklamaları işlemek için kullanılan yöntemler SDK'lar arasında farklılık gösterebilir.

Bu farklılıkların çözümlenmesinden ve uyumlulaştırılmış bir SDK'nın yerel reklam nesnesini, Google Mobile Ads SDK'sının beklediği arayüzle eşleşecek şekilde uyarlamaktan UnifiedNativeAdMapper sorumludur. Özel etkinlikler, uyumlulaştırılmış SDK'larına özel kendi haritacılarını oluşturmak için bu sınıfı genişletmelidir. Örnek özel etkinlik projemizden örnek bir reklam eşleyiciyi aşağıda 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, oluşturucu koduna daha yakından bakalım.

Uyumlulaştırılmış yerel reklam nesnesine yönelik bir referans tutun

Oluşturucu, Örnek SDK'nın yerel reklamlar için kullandığı yerel reklam sınıfı olan SampleNativeAd parametresini kabul eder. Haritacının, tıklama ve gösterim etkinliklerini aktarabilmesi için uyumlulaştırılan reklama referans vermesi gerekir. SampleNativeAd, yerel değişken olarak depolanır.

Eşlenen öğe özelliklerini ayarla

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

Bu snippet, uyumlulaştırılmış reklamın fiyat verilerini alır ve haritacının 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 depolarkenAdMob aynı öğe için String kullanır. Haritacı, bu tür dönüşümleri ele almaktan 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. Bunların 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. Uyumlulaştırılmış bir yerel reklamı eşlemek için UnifiedNativeAdMapper alt sınıfını oluştururken yaptığınız gibi, resim öğelerini eşlerken de NativeAd.Image alt sınıfı oluşturmanız gerekir.

Aşağıda, özel etkinliğin SampleNativeMappedImage sınıfı için bir örnek 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, haritacının 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));

Ekstra pakete alan ekle

Bazı uyumlulaştırılmış SDK'lar, yerel reklam biçimindekilerin dışında AdMob ek öğeler sağlar. UnifiedNativeAdMapper sınıfı, bu öğeleri yayıncılara aktarmak 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.

AdChoices

UnifiedNativeAdMapper üzerinde setAdChoicesContent() yöntemini kullanarak Reklam Seçenekleri simgesi sağlamak özel etkinliğinizden sorumludur. SampleNativeAdMapper sitesinden Reklam Seçenekleri simgesinin nasıl sağlanacağını gösteren bir snippet'i burada 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 uyumlulaştırılmış 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österim ve tıklama izlemeyi kendi başına destekleyip desteklememesine 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 izleme işlemlerini gerçekleştirmiyorsa, ancak tıklamaları ve gösterimleri kaydetmeye yönelik yöntemler sağlıyorsa Google Mobile Ads SDK'sı bu etkinlikleri izleyip bağdaştırıcıya bildirimde bulunabilir. UnifiedNativeAdMapper interface İki yöntem içerir: recordImpression() ve handleClick() özel etkinliklerin uyumlulaştırılmış yerel reklam nesnesinde ilgili yöntemi çağırmak için uygulayabileceği:

Java

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

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

SampleNativeAdMapper, Örnek SDK'nın yerel reklam nesnesine bir referans içerdiğinden, bir tıklama veya gösterimi bildirmek için söz konusu nesnedeki 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.

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

Bazı uyumlulaştırılmış SDK'lar, tıklamaları ve gösterimleri kendi başlarına izlemeyi tercih edebilir. Bu durumda, UnifiedNativeAdMapper oluşturucunuzda 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 gerekir.

Uyumlulaştırılmış SDK'nın gösterimleri ve tıklamaları izlemek amacıyla izlemeyi etkinleştirmek için görünümlere erişmesi gerekir. Özel etkinlik, trackViews() yöntemini geçersiz kılmalı ve yerel reklamın görünümünü izlemek üzere uyumlulaştırılmış SDK'ya iletmek için bunu kullanmalıdır. Özel etkinlik örneği projemizdeki örnek SDK (bu kılavuzun kod snippet'leri alınmıştır) bu yaklaşımı kullanmaz ancak kullanılmışsa özel etkinlik kodu aşağıdaki gibi görünür:

Java

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

Uyumlulaştırılmış SDK, öğelerin bağımsız olarak izlenmesini destekliyorsa hangi görünümlerin tıklanabilir yapılması gerektiğini görmek için clickableAssetViews öğesinin içine bakabilir. Bu harita, NativeAdAssetNames içinde bir öğe adıyla kilitlenir. 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ğırmaları MediationNativeAdCallback dokümanlarında bulabilirsiniz.

Uygulamanızın Google Mobile Ads SDK'sından bu eşdeğer etkinlikleri alması için özel etkinliğinizin bu geri çağırmaları mümkün olduğunca fazla yönlendirmesi önemlidir. Geri çağırma işlevinin kullanımına ilişkin bir örneği burada bulabilirsiniz:

Böylece yerel reklamlar için özel etkinlikler uygulama işlemi tamamlanır. Tam örneği GitHub'da bulabilirsiniz.