Google ใช้เทคโนโลยี AI เพื่อแปลเนื้อหาเป็นภาษาที่คุณต้องการ การแปลโดย AI อาจมีข้อผิดพลาด

เหตุการณ์ที่กำหนดเองของโฆษณาเนทีฟ

เลือกแพลตฟอร์ม: Android iOS Android (เดิม)

ข้อกำหนดเบื้องต้น

ทำการตั้งค่าเหตุการณ์ที่กำหนดเองให้เสร็จสมบูรณ์

ส่งคำขอโฆษณาเนทีฟ

เมื่อรายการโฆษณาเหตุการณ์ที่กำหนดเองไปถึงเชนสื่อกลางตามลำดับขั้น (Waterfall Mediation) ระบบจะเรียกใช้เมธอด loadNativeAd() ในชื่อคลาสที่คุณระบุเมื่อสร้างเหตุการณ์ที่กำหนดเอง ในกรณีนี้ เมธอดดังกล่าวอยู่ใน SampleCustomEvent ซึ่งจะเรียกใช้ เมธอด loadNativeAd() ใน SampleNativeCustomEventLoader

หากต้องการขอโฆษณาเนทีฟ ให้สร้างหรือแก้ไขคลาสที่ขยาย Adapter เพื่อใช้ loadNativeAd() หากมีคลาสที่ขยาย Adapter อยู่แล้ว ให้ใช้ loadNativeAd() ในคลาสนั้น นอกจากนี้ ให้สร้างคลาสใหม่เพื่อใช้ UnifiedNativeAdMapper

ในตัวอย่างเหตุการณ์ที่กำหนดเอง SampleCustomEvent จะขยายคลาส Adapter แล้วมอบสิทธิ์ให้ SampleNativeCustomEventLoader

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 มีหน้าที่รับผิดชอบงานต่อไปนี้

กำลังโหลดโฆษณาเนทีฟ
การใช้คลาส UnifiedNativeAdMapper
การรับและรายงาน Callback ของเหตุการณ์โฆษณาไปยัง GMA Next-Gen SDK

พารามิเตอร์ที่ไม่บังคับซึ่งกำหนดไว้ใน UI ของ AdMob จะรวมอยู่ในการกำหนดค่าโฆษณา คุณเข้าถึงพารามิเตอร์ได้ผ่าน adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD) โดยทั่วไปพารามิเตอร์นี้จะเป็นตัวระบุหน่วยโฆษณาที่ SDK เครือข่ายโฆษณาต้องใช้เมื่อสร้างอินสแตนซ์ออบเจ็กต์โฆษณา

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

คุณจะเรียกใช้ onSuccess() หรือ onFailure() ขึ้นอยู่กับว่าดึงข้อมูลโฆษณาสำเร็จหรือพบข้อผิดพลาด ระบบจะเรียกใช้ onSuccess() โดยส่งอินสแตนซ์ของคลาสที่ใช้ MediationNativeAd

โดยปกติแล้ว เมธอดเหล่านี้จะใช้ภายใน Callback จาก SDK ของบุคคลที่สามที่อะแดปเตอร์ของคุณใช้ สำหรับตัวอย่างนี้ SDK ตัวอย่างจะมี SampleAdListener พร้อม Callback ที่เกี่ยวข้อง ดังนี้

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

โฆษณาเนทีฟใน Maps

SDK แต่ละรายการมีรูปแบบเฉพาะของตนเองสำหรับโฆษณาเนทีฟ เช่น แหล่งข้อมูลหนึ่งอาจแสดงผลออบเจ็กต์ที่มีฟิลด์ "title" ขณะที่อีกแหล่งข้อมูลหนึ่งอาจมี "headline" นอกจากนี้ วิธีการที่ใช้ในการติดตามการแสดงผลและประมวลผลการคลิกอาจแตกต่างกันไปในแต่ละ SDK

UnifiedNativeAdMapper มีหน้าที่รับผิดชอบในการปรับความแตกต่างเหล่านี้และปรับออบเจ็กต์โฆษณาเนทีฟของ SDK ที่ใช้สื่อกลางให้ตรงกับอินเทอร์เฟซที่ GMA Next-Gen SDK คาดหวัง เหตุการณ์ที่กำหนดเองควรขยายคลาสนี้เพื่อสร้าง Mapper ของตนเองซึ่งเจาะจงสำหรับ SDK ที่ใช้สื่อกลาง ต่อไปนี้คือตัวอย่างเครื่องมือแมปโฆษณาจากโปรเจ็กต์เหตุการณ์ที่กำหนดเองตัวอย่างของเรา

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

ตอนนี้เราจะมาดูโค้ดคอนสตรัคเตอร์อย่างละเอียด

เก็บการอ้างอิงออบเจ็กต์โฆษณาเนทีฟที่ใช้สื่อกลางไว้

ตัวสร้างจะยอมรับพารามิเตอร์ SampleNativeAd ซึ่งเป็นคลาสโฆษณาเนทีฟที่ SDK ตัวอย่างใช้สำหรับโฆษณาเนทีฟ ตัวกลางต้องมีการอ้างอิงถึงโฆษณาที่ใช้สื่อกลางเพื่อให้สามารถส่งต่อเหตุการณ์การคลิกและการแสดงผลได้ SampleNativeAd จะจัดเก็บเป็นตัวแปรในเครื่อง

ตั้งค่าพร็อพเพอร์ตี้ของเนื้อหาที่แมป

ตัวสร้างจะใช้ออบเจ็กต์ SampleNativeAd เพื่อป้อนข้อมูลชิ้นงานใน UnifiedNativeAdMapper

ข้อมูลโค้ดนี้จะรับข้อมูลราคาของโฆษณาสื่อกลางและใช้เพื่อกำหนดราคาของ Mapper ดังนี้

Java

if (sampleAd.getPrice() != null) {
    NumberFormat formatter = NumberFormat.getCurrencyInstance();
    String priceString = formatter.format(sampleAd.getPrice());
    setPrice(priceString);
}

ในตัวอย่างนี้ โฆษณาที่ใช้สื่อกลางจะจัดเก็บราคาเป็น double ขณะที่ AdMob ใช้ String สำหรับชิ้นงานเดียวกัน เครื่องมือแมปมีหน้าที่รับผิดชอบในการจัดการ Conversion ประเภทเหล่านี้

แมปชิ้นงานรูปภาพ

การแมปชิ้นงานรูปภาพมีความซับซ้อนมากกว่าการแมปประเภทข้อมูล เช่น double หรือ String ระบบอาจดาวน์โหลดรูปภาพโดยอัตโนมัติหรือแสดงผลเป็นค่า URL นอกจากนี้ สเกลพิกเซลต่อ DPI ยังอาจแตกต่างกันด้วย

GMA Next-Gen SDK มีคลาส NativeAd.Image เพื่อช่วยคุณจัดการรายละเอียดเหล่านี้ คุณควรสร้างคลาสย่อยของ NativeAd.Image เมื่อแมปชิ้นงานรูปภาพในลักษณะเดียวกับที่ต้องสร้างคลาสย่อยของ UnifiedNativeAdMapper เพื่อแมปโฆษณาเนทีฟสื่อกลาง

ตัวอย่างคลาส SampleNativeMappedImage ของเหตุการณ์ที่กำหนดเองมีดังนี้

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 ใช้คลาสรูปภาพที่แมปไว้ในบรรทัดนี้เพื่อตั้งค่าชิ้นงานรูปภาพไอคอนของ Mapper ดังนี้

Java

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

เพิ่มช่องลงในแพ็กเกจส่วนเสริม

SDK ที่ใช้สื่อกลางบางรายการมีชิ้นงานเพิ่มเติมนอกเหนือจากชิ้นงานในรูปแบบโฆษณาเนทีฟของ AdMob คลาส UnifiedNativeAdMapper มีเมธอด setExtras() ที่ใช้เพื่อส่งเนื้อหาเหล่านี้ไปยังผู้เผยแพร่โฆษณา SampleNativeAdMapper ใช้ประโยชน์จากสิ่งนี้สำหรับชิ้นงาน "ระดับความยอดเยี่ยม" ของ SDK ตัวอย่าง

Java

Bundle extras = new Bundle();
extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, ad.getDegreeOfAwesomeness());
this.setExtras(extras);

ผู้เผยแพร่โฆษณาสามารถดึงข้อมูลโดยใช้เมธอด getExtras() ของคลาส NativeAd

ตัวเลือกโฆษณาอื่นๆ

เหตุการณ์ที่กำหนดเองมีหน้าที่แสดงไอคอนตัวเลือกโฆษณาอื่นๆ โดยใช้เมธอด setAdChoicesContent() ใน UnifiedNativeAdMapper ต่อไปนี้เป็นข้อมูลโค้ดจาก SampleNativeAdMapper ที่แสดงวิธีระบุไอคอนตัวเลือกโฆษณาอื่นๆ

Java

public SampleNativeAdMapper(SampleNativeAd ad) {
    ...
    setAdChoicesContent(sampleAd.getInformationIcon());
}

เหตุการณ์การแสดงผลและกิจกรรมการคลิก

ทั้ง GMA Next-Gen SDK และ SDK ที่ใช้สื่อกลางจำเป็นต้องทราบเมื่อมีการแสดงผลหรือการคลิกเกิดขึ้น แต่มี SDK เพียงรายการเดียวเท่านั้นที่ต้องติดตามเหตุการณ์เหล่านี้ เหตุการณ์ที่กำหนดเองสามารถใช้แนวทางที่แตกต่างกัน 2 แนวทาง โดยขึ้นอยู่กับว่า SDK ที่ใช้สื่อกลางรองรับการติดตามการแสดงผลและการคลิกด้วยตัวเองหรือไม่

ติดตามการคลิกและการแสดงผลด้วย GMA Next-Gen SDK

หาก SDK ที่ใช้สื่อกลางไม่ได้ติดตามการแสดงผลและการคลิกของตนเอง แต่มีวิธีบันทึกการคลิกและการแสดงผล GMA Next-Gen SDK จะติดตามเหตุการณ์เหล่านี้และแจ้งให้อะแดปเตอร์ทราบได้ คลาส UnifiedNativeAdMapper มี 2 เมธอด ได้แก่ recordImpression() และ handleClick() ซึ่งเหตุการณ์ที่กำหนดเองสามารถใช้เพื่อเรียกใช้เมธอดที่เกี่ยวข้องในออบเจ็กต์โฆษณาเนทีฟที่สื่อกลางได้

Java

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

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

เนื่องจาก SampleNativeAdMapper มีการอ้างอิงออบเจ็กต์โฆษณาเนทีฟของ SDK ตัวอย่าง จึงสามารถเรียกใช้เมธอดที่เหมาะสมในออบเจ็กต์นั้นเพื่อรายงานการคลิกหรือการแสดงผลได้ โปรดทราบว่าเมธอด handleClick() จะใช้พารามิเตอร์เดียว ซึ่งก็คือออบเจ็กต์ View ที่สอดคล้องกับชิ้นงานโฆษณาเนทีฟที่ได้รับการคลิก

ติดตามการคลิกและการแสดงผลด้วย SDK ที่ใช้สื่อกลาง

SDK ที่ใช้สื่อกลางบางรายการอาจต้องการติดตามการคลิกและการแสดงผลด้วยตนเอง ในกรณีนี้ คุณควรลบล้างการติดตามการคลิกและการแสดงผลเริ่มต้นโดยทำการเรียก 2 ครั้งต่อไปนี้ในคอนสตรัคเตอร์ของ UnifiedNativeAdMapper

Java

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

เหตุการณ์ที่กำหนดเองซึ่งลบล้างการติดตามการคลิกและการแสดงผลจำเป็นต้องรายงานเหตุการณ์ onAdClicked() และ onAdImpression() ไปยัง Google Mobile Ads SDK

หากต้องการติดตามการแสดงผลและการคลิก SDK ที่ใช้สื่อกลางอาจต้องเข้าถึงมุมมองเพื่อเปิดใช้การติดตาม เหตุการณ์ที่กำหนดเองควรลบล้างเมธอด trackViews() และใช้เพื่อส่งมุมมองของโฆษณาเนทีฟไปยัง SDK สื่อกลางเพื่อติดตาม SDK ตัวอย่างจากโปรเจ็กต์ตัวอย่างเหตุการณ์ที่กำหนดเอง (ซึ่งเป็นที่มาของข้อมูลโค้ดในคู่มือนี้) ไม่ได้ใช้วิธีนี้ แต่หากใช้ โค้ดเหตุการณ์ที่กำหนดเองจะมีลักษณะดังนี้

Java

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

หาก SDK ที่ใช้สื่อกลางรองรับการติดตามเนื้อหาแต่ละรายการ ก็จะดูภายใน clickableAssetViews เพื่อดูว่ามุมมองใดควรทำให้คลิกได้ แผนที่นี้มีคีย์เป็นชื่อชิ้นงานใน NativeAdAssetNames UnifiedNativeAdMapper มีเมธอด untrackView() ที่เกี่ยวข้องซึ่งเหตุการณ์ที่กำหนดเองสามารถลบล้างเพื่อเผยแพร่การอ้างอิงไปยังมุมมองและยกเลิกการเชื่อมโยงกับออบเจ็กต์โฆษณาเนทีฟได้

ส่งต่อเหตุการณ์สื่อกลางไปยัง GMA Next-Gen SDK

คุณดู Callback ทั้งหมดที่สื่อกลางรองรับได้ในเอกสารประกอบของ MediationNativeAdCallback

เหตุการณ์ที่กำหนดเองควรส่งต่อ Callback เหล่านี้ให้มากที่สุดเท่าที่จะเป็นไปได้ เพื่อให้แอปได้รับเหตุการณ์ที่เทียบเท่าเหล่านี้จาก GMA Next-Gen SDK ตัวอย่างการใช้ Callback มีดังนี้

ขั้นตอนนี้เป็นการติดตั้งใช้งานเหตุการณ์ที่กำหนดเองสำหรับโฆษณาเนทีฟให้เสร็จสมบูรณ์ ดูตัวอย่างแบบเต็มได้ใน GitHub