Özel Yerel Reklam Biçimleri

Özel yerel reklam biçimleri

Ad Manager yayıncıları, sistem tanımlı doğal biçimlere ek olarak özel öğe listeleri tanımlayarak kendi doğal reklam biçimlerini oluşturabilir. Bunlara özel yerel reklam biçimleri denir ve ayrılmış reklamlarla kullanılabilir. Bu sayede yayıncılar, uygulamalarına istedikleri yapılandırılmış verileri iletebilir. Bu reklamlar NativeCustomFormatAd nesnesi ile temsil edilir.

Özel yerel reklam biçimlerini yükleme

Bu kılavuzda, özel yerel reklam biçimlerinin nasıl yükleneceği ve gösterileceği açıklanmaktadır.

AdLoader oluşturma

Doğal reklamlar gibi özel doğal reklam biçimleri de AdLoader sınıfı kullanılarak yüklenir:

Java

AdLoader adLoader = new AdLoader.Builder(context, "/21775744923/example/native")
    .forCustomFormatAd("10063170",
      new NativeCustomFormatAd.OnCustomFormatAdLoadedListener() {
          @Override
          public void onCustomFormatAdLoaded(NativeCustomFormatAd ad) {
              // Show the custom format and record an impression.
          }
      },
      new NativeCustomFormatAd.OnCustomClickListener() {
          @Override
          public void onCustomClick(NativeCustomFormatAd ad, String s) {
              // Handle the click action
          }
      })
    .withAdListener( ... )
    .withNativeAdOptions( ... )
    .build();

Kotlin

val adLoader = AdLoader.Builder(this, "/21775744923/example/native")
        .forCustomFormatAd("10063170",
            { ad ->
                // Show the custom format and record an impression.
            },
            { ad, s ->
            // Handle the click action
            })
        .withAdListener( ... )
        .withNativeAdOptions( ... )
        .build()

forCustomFormatAd yöntemi, AdLoader öğesini özel doğal reklam biçimleri isteyecek şekilde yapılandırır. Yönteme üç parametre iletilir:

• AdLoader'ün istemesi gereken özel doğal reklam biçiminin kimliği. Her özel yerel reklam biçiminin ilişkili bir kimliği vardır. Bu parametre, uygulamanızın AdLoader'ün hangi biçimi istemesini istediğini belirtir.
• Bir reklam başarıyla yüklendiğinde çağrılacak OnCustomFormatAdLoadedListener.
• Kullanıcı reklama dokunduğunda veya reklamı tıkladığında çağrılacak isteğe bağlı bir OnCustomClickListener. Bu dinleyici hakkında daha fazla bilgi için aşağıdaki "Tıklamaları ve gösterimleri işleme" bölümüne bakın.

Tek bir reklam birimi birden fazla reklam öğesi biçimi yayınlamak üzere ayarlanabileceğinden, reklam yükleyiciyi birden fazla olası özel yerel reklam biçimine hazırlamak için forCustomFormatAd, benzersiz biçim kimlikleriyle birden çok kez çağrılabilir.

Not: Birden fazla reklam biçimi yayınlamak üzere yapılandırılmış bir reklam biriminiz varsa forNativeAd ve forCustomFormatAd, tek bir AdLoader ile aynı anda kullanılabilir.

Özel yerel reklam biçimi kimliği

Özel bir doğal reklam biçimini tanımlamak için kullanılan biçim kimliği, Ad Manager kullanıcı arayüzünde Yayınlama açılır menüsünün altındaki Doğal bölümünde bulunabilir:

Her özel yerel reklam biçimi kimliği, adının yanında görünür. Adlardan birini tıkladığınızda, biçimin alanlarıyla ilgili bilgileri gösteren bir ayrıntılar ekranına yönlendirilirsiniz:

Buradan tek tek alanlar eklenebilir, düzenlenebilir ve kaldırılabilir. Her bir öğenin adını not edin. Ad, özel yerel reklam biçiminizi görüntülerken her öğenin verilerini almak için kullanılan anahtardır.

Özel yerel reklam biçimlerini görüntüleme

Özel doğal reklam biçimleri, yayıncıların reklamı oluşturan kendi öğe listelerini tanımlama yetkisine sahip olması açısından sistem tarafından tanımlanan biçimlerden farklıdır. Bu nedenle, bu tür bir öğenin görüntüleme süreci, sistem tarafından tanımlanan biçimlerden birkaç açıdan farklıdır:

1. NativeCustomFormatAd sınıfı, Ad Manager'da tanımladığınız özel yerel reklam biçimlerinin tümünü işlemek için tasarlandığından, öğeler için adlandırılmış "alıcıları" yoktur. Bunun yerine, alanın adını parametre olarak alan getText ve getImage gibi yöntemler sunar.
2. NativeCustomFormatAd ile birlikte kullanılacak NativeAdView gibi özel bir reklam görüntüleme sınıfı yoktur. Kullanıcı deneyiminiz için uygun olan herhangi bir düzeni kullanabilirsiniz.
3. Özel bir ViewGroup sınıfı olmadığından, reklamın öğelerini görüntülemek için kullandığınız görünümlerden herhangi birini kaydetmeniz gerekmez. Bu, reklamı gösterirken birkaç kod satırından tasarruf etmenizi sağlar ancak daha sonra tıklamaları işlemek için biraz daha fazla çalışma yapmanız gerektiği anlamına da gelir.

NativeCustomFormatAd gösteren bir örnek işlevi aşağıda verilmiştir:

Java

public void displayCustomFormatAd (ViewGroup parent,
                                     NativeCustomFormatAd customFormatAd) {
    // Inflate a layout and add it to the parent ViewGroup.
    LayoutInflater inflater = (LayoutInflater) parent.getContext()
            .getSystemService(Context.LAYOUT_INFLATER_SERVICE);
    View adView = inflater.inflate(R.layout.custom_format_ad, parent);

    // Locate the TextView that will hold the value for "Headline" and
    // set its text.
    TextView myHeadlineView = (TextView) adView.findViewById(R.id.headline);
    myHeadlineView.setText(customFormatAd.getText("Headline"));

    // Locate the ImageView that will hold the value for "MainImage" and
    // set its drawable.
    Button myMainImageView = (ImageView) adView.findViewById(R.id.main_image);
    myMainImageView.setImageDrawable(
            customFormatAd.getImage("MainImage").getDrawable());

    ...
    // Continue locating views and displaying assets until finished.
    ...
}

Kotlin

public fun displayCustomFormatAd (parent: ViewGroup,
                                customFormatAd: NativeCustomFormatAd) {
    val adView = layoutInflater
            .inflate(R.layout.ad_simple_custom_format, null)

    val myHeadlineView = adView.findViewById<TextView>(R.id.headline)
    myHeadlineView.setText(customFormatAd.getText("Headline"));

    // Locate the ImageView that will hold the value for "MainImage" and
    // set its drawable.
    val myMainImageView = adView.findViewById(R.id.main_image);
    myMainImageView.setImageDrawable(
            customFormatAd.getImage("MainImage").drawable);

    ...
    // Continue locating views and displaying assets until finished.
    ...
}

Reklam Seçenekleri simgesini oluşturma

Dijital Hizmetler Yasası'nı (DSA) destekleme kapsamında, Avrupa Ekonomik Alanı'nda (AEA) yayınlanan rezervasyon reklamlarında bir Reklam Seçenekleri simgesi ve Google'ın Bu Reklam Hakkında sayfasının bağlantısı yer almalıdır. Özel doğal reklamları uygularken Reklam Seçenekleri simgesini oluşturma sorumluluğu size aittir. Ana reklam öğelerini oluştururken Reklam Seçenekleri simgesi için tıklama işleyici oluşturmak ve ayarlamak üzere bazı adımlar atmanızı öneririz.

Aşağıdaki örnekte, görüntüleme hiyerarşinizde Reklam Seçenekleri logosunu barındıracak bir <ImageView /> öğesi tanımladığınız varsayılmaktadır.

Önemli: Reklam Seçenekleri simgesini en az 15 piksel x 15 piksel olarak ayarlayın.

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android">
    <ImageView
        android:id="@+id/adChoices"
        android:layout_width="15dp"
        android:layout_height="15dp"
        android:adjustViewBounds="true"
        android:contentDescription="AdChoices icon." />
</LinearLayout>

Aşağıdaki örneklerde, Reklam Seçenekleri simgesi oluşturulmakta ve uygun tıklama davranışı yapılandırılmaktadır.

Java

private AdSimpleCustomTemplateBinding customTemplateBinding;

private void populateAdView(final NativeCustomFormatAd nativeCustomFormatAd) {
  // Render the AdChoices icon.
  String adChoicesKey = NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW;
  NativeAd.Image adChoicesAsset = nativeCustomFormatAd.getImage(adChoicesKey);
  if (adChoicesAsset == null) {
    customTemplateBinding.adChoices.setVisibility(View.GONE);
  } else {
    customTemplateBinding.adChoices.setVisibility(View.VISIBLE);
    customTemplateBinding.adChoices.setImageDrawable(adChoicesAsset.getDrawable());

    // Enable clicks on AdChoices.
    customTemplateBinding.adChoices.setOnClickListener(
        new View.OnClickListener() {
          @Override
          public void onClick(View v) {
            nativeCustomFormatAd.performClick(adChoicesKey);
          }
        });
  }
  ...
}

Kotlin

private lateinit var customTemplateBinding: AdSimpleCustomTemplateBinding

private fun populateAdView(nativeCustomFormatAd: NativeCustomFormatAd) {
  // Render the AdChoices icon.
  val adChoicesKey = NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW
  val adChoicesAsset = nativeCustomFormatAd.getImage(adChoicesKey)
  if (adChoicesAsset == null) {
    customTemplateBinding.adChoices.visibility = View.GONE
  } else {
    customTemplateBinding.adChoices.setImageDrawable(adChoicesAsset.drawable)
    customTemplateBinding.adChoices.visibility = View.VISIBLE

    // Enable clicks on AdChoices.
    customTemplateBinding.adChoices.setOnClickListener {
      nativeCustomFormatAd.performClick(adChoicesKey)
    }
  }
  ...
}

Önemli Bilgi: Yalnızca resim URL'lerini istemek için Resim indirme denetimini kullanırsanız AdChoices öğesi bu ayarlara uyar ve yalnızca resim URL'sini döndürür.

Özel yerel reklam biçimleri için doğal video

Özel biçim oluştururken biçimi video için uygun hale getirebilirsiniz.

Uygulama uygulamanızda, medya içeriğini almak için NativeCustomFormatAd.getMediaContent() kullanabilirsiniz. Ardından, medya görünümünüzdeki medya içeriğini ayarlamak için setMediaContent() yöntemini çağırın. Reklamda video içeriği yoksa reklamı video olmadan göstermek için alternatif planlar yapın.

Not: Video mevcut olmadığında medya görünümünde resim içeren doğal reklamların aksine, özel doğal reklamların medya görünümünde video yoksa içerik bulunmaz.

Aşağıdaki örnekte, reklamda video içeriği olup olmadığı kontrol edilir ve video yoksa bunun yerine bir resim gösterilir:

Java

// Called when a custom native ad loads.
@Override
public void onCustomFormatAdLoaded(final NativeCustomFormatAd ad) {

  MediaContent mediaContent = ad.getMediaContent();

  // Assumes you have a FrameLayout in your view hierarchy with the id media_placeholder.
  FrameLayout mediaPlaceholder = (FrameLayout) findViewById(R.id.media_placeholder);

  // Apps can check the MediaContent's hasVideoContent property to determine if the
  // NativeCustomFormatAd has a video asset.
  if (mediaContent != null && mediaContent.hasVideoContent()) {
    MediaView mediaView = new MediaView(mediaPlaceholder.getContext());
    mediaView.setMediaContent(mediaContent);
    mediaPlaceholder.addView(mediaView);

    // Create a new VideoLifecycleCallbacks object and pass it to the VideoController. The
    // VideoController will call methods on this object when events occur in the video
    // lifecycle.
    VideoController vc = mediaContent.getVideoController();
    vc.setVideoLifecycleCallbacks(
        new VideoController.VideoLifecycleCallbacks() {
          @Override
          public void onVideoEnd() {
            // Publishers should allow native ads to complete video playback before
            // refreshing or replacing them with another ad in the same UI location.
            super.onVideoEnd();
          }
        });
  } else {
    ImageView mainImage = new ImageView(this);
    mainImage.setAdjustViewBounds(true);
    mainImage.setImageDrawable(ad.getImage("MainImage").getDrawable());
    mediaPlaceholder.addView(mainImage);
    mainImage.setOnClickListener(
        new View.OnClickListener() {
          @Override
          public void onClick(View view) {
            ad.performClick("MainImage");
          }
        });
  }
}

Kotlin

// Called when a custom native ad loads.
NativeCustomFormatAd.OnCustomFormatAdLoadedListener { ad ->

  val mediaContent = ad.mediaContent

  // Apps can check the MediaContent's hasVideoContent property to determine if the
  // NativeCustomFormatAd has a video asset.
  if (mediaContent != null && mediaContent.hasVideoContent()) {
    val mediaView = MediaView(mediaPlaceholder.getContest())
    mediaView.mediaContent = mediaContent

    val videoController = mediaContent.videoController

    // Create a new VideoLifecycleCallbacks object and pass it to the VideoController. The
    // VideoController will call methods on this object when events occur in the video
    // lifecycle.
    if (videoController != null) {
      videoController.videoLifecycleCallbacks =
        object : VideoController.VideoLifecycleCallbacks() {
          override fun onVideoEnd() {
            // Publishers should allow native ads to complete video playback before refreshing
            // or replacing them with another ad in the same UI location.
            super.onVideoEnd()
          }
        }
    }
  } else {
    val mainImage = ImageView(this)
    mainImage.adjustViewBounds = true
    mainImage.setImageDrawable(ad.getImage("MainImage")?.drawable)

    mainImage.setOnClickListener { ad.performClick("MainImage") }
    customTemplateBinding.simplecustomMediaPlaceholder.addView(mainImage)
  }
}

Özel bir yerel reklamın video deneyimini nasıl özelleştirebileceğiniz hakkında daha fazla bilgi için MediaContent bölümüne bakın.

Yerel videonun kullanıldığı bir örnek görmek için Ad Manager Özel Oluşturma örneğini indirin.

Özel yerel reklam biçimi tıklamaları ve gösterimleri

Özel doğal reklam biçimlerinde, gösterim kaydetme ve tıklama etkinliklerini Google Mobile Ads SDK'sına bildirme sorumluluğu uygulamanıza aittir.

Gösterimleri kaydetme

Özel biçimli bir reklam için gösterim kaydetmek üzere ilgili NativeCustomFormatAd üzerinde recordImpressionyöntemini çağırın:

myCustomFormatAd.recordImpression();

Uygulamanız aynı reklam için yanlışlıkla yöntemi iki kez çağırırsa SDK, tek bir istek için yinelenen bir gösterimin kaydedilmesini otomatik olarak engeller.

Tıklamaları bildirme

SDK'ya bir öğe görünümünde tıklama gerçekleştiğini bildirmek için ilgili NativeCustomFormatAd üzerinde performClick yöntemini çağırın ve tıklanan öğenin adını iletin. Örneğin, özel biçiminizde "MainImage" adlı bir öğeniz varsa ve bu öğeye karşılık gelen ImageView öğesindeki bir tıklamayı bildirmek istiyorsanız kodunuz şu şekilde görünür:

myCustomFormatAd.performClick("MainImage");

Bu yöntemi, reklamınızla ilişkili her görüntüleme için çağırmanız gerekmediğini unutmayın. Gösterilmesi amaçlanan ancak kullanıcı tarafından tıklanmayan veya dokunulmayan "Altyazı" adlı başka bir alanınız varsa uygulamanızın bu öğenin görünümü için performClick'yi çağırması gerekmez.

Özel tıklama işlemlerine yanıt verme

Özel biçimli bir reklam tıklandığında SDK'dan üç olası yanıt gelir ve bu yanıtlar şu sırayla denenir:

1. Sağlandıysa AdLoader'ten OnCustomClickListener'yi çağırın.
2. Reklamın derin bağlantı URL'lerinin her biri için bir içerik çözücü bulmaya çalışın ve çözen ilk içeriği başlatın.
3. Bir tarayıcı açıp reklamın geleneksel hedef URL'sine gidin.

forCustomFormatAd yöntemi bir OnCustomClickListener kabul eder. Bir dinleyici nesnesi gönderirseniz SDK bunun yerine onCustomClick yöntemini çağırır ve başka işlem yapmaz. Ancak dinleyici olarak null değerini gönderirseniz SDK, reklama kayıtlı derin bağlantıya ve/veya hedef URL'lere geri döner.

Özel tıklama dinleyicileri, uygulamanızın bir tıklamaya yanıt olarak yapılacak en iyi işleme (kullanıcı arayüzünü güncelleme, yeni bir etkinlik başlatma veya yalnızca tıklamayı günlüğe kaydetme) karar vermesine olanak tanır. Aşağıda, yalnızca bir tıklamanın gerçekleştiğini günlüğe kaydeden bir örnek verilmiştir:

Java

AdLoader adLoader = new AdLoader.Builder(context, "/21775744923/example/native")
    .forCustomFormatAd("10063170",
      new NativeCustomFormatAd.OnCustomFormatAdLoadedListener() {
        // Display the ad.
      },
      new NativeCustomFormatAd.OnCustomClickListener() {
          @Override
          public void onCustomClick(NativeCustomFormatAd ad, String assetName) {
            Log.i("MyApp", "A custom click just happened for " + assetName + "!");
          }
      }).build();

Kotlin

val adLoader = AdLoader.Builder(this, "/21775744923/example/native")
    .forCustomFormatAd("10063170",
        { ad ->
            // Display the ad.
        },
        { ad, assetName ->
                Log.i("MyApp", "A custom click just happened for $assetName!")
    }).build()

Özel tıklama dinleyicilerinin varlığı ilk başta garip gelebilir. Sonuçta, uygulamanız SDK'ya bir tıklama olduğunu söyledi. SDK neden bunu uygulamaya bildirsin?

Bu bilgi akışı birkaç nedenden dolayı yararlıdır ancak en önemlisi, SDK'nın tıklamaya verilen yanıtın kontrolünü elinde tutmasına olanak tanımasıdır. Örneğin, reklam öğesi için ayarlanmış üçüncü taraf izleme URL'lerini otomatik olarak pingleyebilir ve ek kod olmadan arka planda diğer görevleri gerçekleştirebilir.