หน้านี้ได้รับการแปลโดย Cloud Translation API

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

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

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

ขอโฆษณาเนทีฟ

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

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

ในตัวอย่างเหตุการณ์ที่กำหนดเอง SampleCustomEvent ใช้งานthe Adapter interface แล้วมอบสิทธิ์ให้กับ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 interface
การรับและการรายงานการเรียกกลับของเหตุการณ์โฆษณาไปยัง SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google

พารามิเตอร์ที่ไม่บังคับที่กำหนดไว้ใน Ad Manager UI จะรวมอยู่ในการกำหนดค่าโฆษณา คุณเข้าถึงพารามิเตอร์นี้ได้ผ่านทาง 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

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

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

แมปโฆษณาเนทีฟ

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

UnifiedNativeAdMapper มีหน้าที่แก้ไขความแตกต่างเหล่านี้และปรับออบเจ็กต์โฆษณาเนทีฟของ SDK ที่ใช้สื่อกลางให้ตรงกับอินเทอร์เฟซที่ SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google คาดหวัง เหตุการณ์ที่กำหนดเองควรขยายคลาสนี้เพื่อสร้างตัวแมปของตนเองสำหรับ 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

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

Java

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

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

จับคู่ชิ้นงานรูปภาพ

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

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

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

Java

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

เพิ่มช่องลงในแพ็กเกจเพิ่มเติม

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

Java

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

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

AdChoices

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

Java

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

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

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

ติดตามคลิกและการแสดงผลด้วย Google Mobile Ads SDK

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

Java

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

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

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

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

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

Java

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

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

หากต้องการติดตามการแสดงผลและการคลิก 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() ที่เกี่ยวข้องซึ่งเหตุการณ์ที่กำหนดเองจะลบล้างเพื่อปล่อยการอ้างอิงไปยังมุมมอง และยกเลิกการเชื่อมโยงพร็อพเพอร์ตี้นั้นจากออบเจ็กต์โฆษณาเนทีฟ

ส่งต่อเหตุการณ์สื่อกลางไปยัง SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google

ดูโค้ดเรียกกลับทั้งหมดที่สื่อกลางรองรับได้ในเอกสาร MediationNativeAdCallback

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

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