Özel yerel reklam biçimlerini kullanma

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.

Ö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

Özel bir doğal reklam yüklemek için aşağıdakileri yapın:

  1. NativeAdRequest içinde reklam türü olarak NativeAdType.CUSTOM_NATIVE türünü ekleyin.

  2. Özel doğal reklamın biçim kimliğini ayarlayın.

Kotlin

val adRequest =
  NativeAdRequest.Builder("AD_UNIT_ID", listOf(NativeAdType.CUSTOM_NATIVE))
    .setCustomFormatIds(listOf("CUSTOM_NATIVE_FORMAT_ID"))
    .build()

// Load the native ad with the ad request and callback.
NativeAdLoader.load(
  adRequest,
  object : NativeAdLoaderCallback {
    override fun onCustomNativeAdLoaded(customNativeAd: CustomNativeAd) {
      // TODO: Store the custom native ad.
    }

    override fun onAdFailedToLoad(adError: LoadAdError) {}
  },
)

Java

NativeAdRequest adRequest =
    new NativeAdRequest.Builder("AD_UNIT_ID", List.of(NativeAd.NativeAdType.CUSTOM_NATIVE))
        .setCustomFormatIds(Arrays.asList("CUSTOM_NATIVE_FORMAT_ID"))
        .build();

// Load the native ad with the ad request and callback.
NativeAdLoader.load(
    adRequest,
    new NativeAdLoaderCallback() {
      @Override
      public void onCustomNativeAdLoaded(@NonNull CustomNativeAd customNativeAd) {
        // TODO: Store the custom native ad.
      }

      @Override
      public void onAdFailedToLoad(@NonNull LoadAdError adError) {}
    });

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

Bu örnekte, CustomNativeAd öğesinin nasıl gösterileceği açıklanmaktadır:

Kotlin

private fun displayCustomNativeAd(customNativeAd: CustomNativeAd, context: Context) {
  // Render the text elements.

  // The `customNativeAdBinding` is the layout binding for the ad container that
  // contains all `CustomNativeAd` assets.
  customNativeAdBinding.headline.text = customNativeAd.getText("Headline")
  customNativeAdBinding.caption.text = customNativeAd.getText("Caption")

  // If the main asset is an image, render it with an ImageView.
  val imageView = ImageView(context)
  imageView.adjustViewBounds = true
  imageView.setImageDrawable(customNativeAd.getImage("MainImage")?.drawable)
  imageView.setOnClickListener { customNativeAd.performClick("MainImage") }
  customNativeAdBinding.mediaPlaceholder.addView(imageView)

  // Render the ad choices icon.
  renderAdChoices(customNativeAd)

  // Record an impression.
  customNativeAd.recordImpression()
}

Java

private void displayCustomNativeAd(CustomNativeAd customNativeAd, Context context) {
  // Render the text elements.

  // The `customNativeAdBinding` is the layout binding for the ad container that
  // contains all `CustomNativeAd` assets.
  if (customNativeAdBinding != null) {
    customNativeAdBinding.headline.setText(customNativeAd.getText("Headline"));
    customNativeAdBinding.caption.setText(customNativeAd.getText("Caption"));

    ImageView imageView = new ImageView(context);
    imageView.setAdjustViewBounds(true);
    imageView.setImageDrawable(customNativeAd.getImage("MainImage").getDrawable());
    imageView.setOnClickListener(
        new View.OnClickListener() {
          @Override
          public void onClick(View v) {
            customNativeAd.performClick("MainImage");
          }
        });
    customNativeAdBinding.mediaPlaceholder.addView(imageView);

    // Render the ad choices icon.
    renderAdChoices(customNativeAd);

    // Record an impression.
    customNativeAd.recordImpression();
  }
}

Ö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 CustomNativeAd.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:

Kotlin

private fun displayVideoCustomNativeAd(customNativeAd: CustomNativeAd, context: Context) {
  // Check whether the custom native ad has video content.
  val mediaContent = customNativeAd.mediaContent
  if (mediaContent != null && mediaContent.hasVideoContent) {
    // Render the media content in a MediaView.
    val mediaView = MediaView(context)
    mediaView.mediaContent = mediaContent
    customNativeAdBinding.mediaPlaceholder.addView(mediaView)
  } else {
    // Fall back to other assets defined on your custom native ad.
    val imageView = ImageView(context)
    imageView.adjustViewBounds = true
    imageView.setImageDrawable(customNativeAd.getImage("MainImage")?.drawable)
    customNativeAdBinding.mediaPlaceholder.addView(imageView)
  }

  // Record an impression.
  customNativeAd.recordImpression()
}

Java

private void displayVideoCustomNativeAd(CustomNativeAd customNativeAd, Context context) {
  // Check whether the custom native ad has video content.
  MediaContent mediaContent = customNativeAd.getMediaContent();
  if (mediaContent != null && mediaContent.getHasVideoContent()) {
    // Render the media content in a MediaView.
    MediaView mediaView = new MediaView(context);
    mediaView.setMediaContent(mediaContent);
    customNativeAdBinding.mediaPlaceholder.addView(mediaView);
  } else {
    // Fall back to other assets defined on your custom native ad.
    ImageView imageView = new ImageView(context);
    imageView.setAdjustViewBounds(true);
    imageView.setImageDrawable(customNativeAd.getImage("MainImage").getDrawable());
    customNativeAdBinding.mediaPlaceholder.addView(imageView);
  }

  // Record an impression.
  customNativeAd.recordImpression();
}

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

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

Kotlin

private fun renderAdChoices(customNativeAd: CustomNativeAd) {
  // Render the AdChoices image.
  val adChoiceAsset = customNativeAd.getImage(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW)
  if (adChoiceAsset != null) {
    customNativeAdBinding.adchoices.setImageDrawable(adChoiceAsset.drawable)
    customNativeAdBinding.adchoices.visibility = View.VISIBLE
    customNativeAdBinding.adchoices.setOnClickListener {
      // Handle click. See the next section for more details.
      customNativeAd.performClick(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW)
    }
  } else {
    customNativeAdBinding.adchoices.visibility = View.GONE
  }
}

Java

private void renderAdChoices(CustomNativeAd customNativeAd) {
  // Render the AdChoices image.
  Image adChoiceAsset =
      customNativeAd.getImage(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW);
  if (adChoiceAsset != null) {
    if (customNativeAdBinding != null) {
      customNativeAdBinding.adchoices.setImageDrawable(adChoiceAsset.getDrawable());
      customNativeAdBinding.adchoices.setVisibility(View.VISIBLE);
      customNativeAdBinding.adchoices.setOnClickListener(
          new View.OnClickListener() {
            @Override
            public void onClick(View v) {
              // Handle click.
              customNativeAd.performClick(NativeAdAssetNames.ASSET_ADCHOICES_CONTAINER_VIEW);
            }
          });
    }
  } else {
    if (customNativeAdBinding != null) {
      customNativeAdBinding.adchoices.setVisibility(View.GONE);
    }
  }
}

Gösterimleri kaydetme ve tıklamaları raporlama

Uygulamanız, gösterimleri kaydetmekten ve tıklama etkinliklerini GMA Next-Gen SDK adresine bildirmekten sorumludur.

Gösterimleri kaydetme

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

Kotlin

// Record an impression.
customNativeAd.recordImpression()

Java

// Record an impression.
customNativeAd.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.

Kotlin

imageView.setOnClickListener { customNativeAd.performClick("MainImage") }

Java

imageView.setOnClickListener(
    new View.OnClickListener() {
      @Override
      public void onClick(View v) {
        customNativeAd.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:

Kotlin

customNativeAd.onCustomClickListener =
  object : OnCustomClickListener {
    override fun onCustomClick(assetName: String) {
      // Perform your custom action.
    }
  }

Java

customNativeAd.setOnCustomClickListener(
    new OnCustomClickListener() {
      @Override
      public void onCustomClick(@NonNull String assetName) {
        // Perform your custom action.
      }
    });

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