Özel yerel reklam biçimlerini kullanma

Platform seçin: Android iOS Android (Eski)

Ad Manager yayıncıları, sistem tarafından tanımlanan doğal biçimlerin yanı sıra özel öğe listeleri tanımlayarak kendi doğal reklam biçimlerini oluşturma seçeneğine de sahiptir. Bunlar özel doğal reklam biçimleri olarak adlandırılır ve rezerve edilmiş reklamlarla kullanılabilir. Bu sayede yayıncılar, uygulamalarına rastgele yapılandırılmış veriler iletebilir. Bu reklamlar NativeCustomFormatAd nesnesiyle temsil edilir.

Not: NativeCustomFormatAd sınıfı, ResponseInfo nesnesini veya extras paketini almayı desteklemez.

Özel doğal reklam biçimlerini yükleme

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

Özel doğal reklam yükleme

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

Java

AdLoader adLoader = new AdLoader.Builder(this, "/21775744923/example/native")
    .forCustomFormatAd("12387226",
        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
          }
        })
    .forCustomFormatAd("12406343",
        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
          }
        })
    .build();

Kotlin

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

forCustomFormatAd yöntemi, özel doğal reklam biçimleri istemek için AdLoader öğesini yapılandırır. Farklı özel biçim kimlikleri için yöntemi birden çok kez çağırabilirsiniz. Yöntem aşağıdaki parametreleri kabul eder:

• AdLoader tarafından istenmesi gereken özel doğal reklam biçiminin kimliği. Her özel doğal reklam biçiminin kendisiyle ilişkili bir kimliği vardır. Bu parametre, uygulamanızın AdLoader tarafından hangi biçimin istenmesini istediğini gösterir.
• Bir reklam başarıyla yüklendiğinde çağrılacak bir 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 "Tıklamaları ve gösterimleri işleme" bölümüne bakın.

Tek bir reklam birimi birden fazla reklam öğesi biçimi yayınlayacak şekilde ayarlanabildiğinden, reklam yükleyiciyi birden fazla olası özel doğal reklam biçimine hazırlamak için forCustomFormatAd, benzersiz biçim kimlikleriyle birden fazla kez çağrılabilir.

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

Özel doğal 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ündeki Doğal bölümünde bulunabilir:

Her özel doğal 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 alanlar tek tek eklenebilir, düzenlenebilir ve kaldırılabilir. Öğelerin her birinin adını not edin. Ad, özel doğal reklam biçiminizi gösterirken her bir öğenin verilerini almak için kullanılan anahtardır.

Özel doğal reklam biçimlerini görüntüleme

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

1. Metin ve resim öğeleri, alan adını parametre olarak alan getText() ve getImage() alıcıları aracılığıyla kullanılabilir.
2. Google'a kaydedilecek özel bir ViewGroup sınıfı olmadığından gösterimleri ve tıklamaları manuel olarak kaydetmeniz gerekir.
3. Reklamda video öğesi yoksa özel doğal reklamda null medya içeriği bulunur.

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

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.
    ...
}

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

Özel biçim oluştururken biçimi video için uygun hale getirme seçeneğiniz vardır.

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

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

Doğal videonun işleyişini gösteren çalışan bir örnek için Ad Manager Özel Oluşturma örneğini indirin.

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

Reklam Seçenekleri simgesini oluşturma

Dijital Hizmetler Yasası'nı (DSA) destekleme kapsamında, Avrupa Ekonomik Alanı'nda (AEA) yayınlanan rezervasyon reklamları için Reklam Seçenekleri simgesi ve Google'ın Bu reklam hakkında sayfasına bağlantı gerekir. Ö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ünüm 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 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şturulur ve uygun tıklama davranışı yapılandırılı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 nokta: Yalnızca resim URL'lerini istemek için Resim indirme kontrolü'nü kullanırsanız Reklam Seçenekleri öğesi bu ayara uyar ve yalnızca resim URL'sini döndürür.

Gösterimleri kaydetme ve tıklamaları raporlama

Uygulamanız, gösterimleri kaydetmekten ve tıklama etkinliklerini Google Mobile Ads SDK (Legacy) adresine bildirmekten sorumludur.

Gösterimleri kaydetme

Özel doğal reklam için gösterim kaydetmek üzere reklamın recordImpression() yöntemini çağırın:

myCustomFormatAd.recordImpression();

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

Rapor tıklamaları

SDK'ya bir öğe görünümünde tıklama gerçekleştiğini bildirmek için reklamın performClick() yöntemini çağırın. Ad Manager kullanıcı arayüzünde tanımladığınız dizeyi kullanarak tıklanan öğenin adını belirtin.

myCustomFormatAd.performClick("MainImage");

Bu yöntemi reklamınızla ilişkili her görüntüleme için çağırmanız gerekmez. "Başlık" adında, gösterilmesi amaçlanan ancak kullanıcı tarafından tıklanmayan veya dokunulmayan başka bir alanınız varsa uygulamanızın bu öğenin görünümü için performClick yöntemini çağırması gerekmez.

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

Özel biçimli bir reklam tıklandığında SDK'dan üç olası yanıt alınabilir. Bu yanıtlar şu sırayla denenir:

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

Özel bir tıklama işlemi uygulamak için OnCustomClickListener sağlayın:

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 işleyicilerinin varlığı ilk başta garip gelebilir. Sonuçta uygulamanız SDK'ya bir tıklama olduğunu bildirdi. SDK neden bunu uygulamaya geri bildirsin?

Bu bilgi akışı birkaç nedenden dolayı faydalı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'lerine otomatik olarak ping gönderebilir ve ek kod olmadan arka planda diğer görevleri gerçekleştirebilir.