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

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

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

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

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

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

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

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

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

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

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() เรียกโดยส่งอินสแตนซ์ของคลาสที่ implements MediationNativeAd

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

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

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

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

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

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

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

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

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

ชิ้นงานรูปภาพแผนที่

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ติดตามการคลิกและการแสดงผลด้วย SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google

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

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

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

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

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

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

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

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

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

@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

เหตุการณ์ที่กําหนดเองต้องส่งต่อการเรียกกลับเหล่านี้ให้ได้มากที่สุด เพื่อให้แอปได้รับเหตุการณ์ที่เทียบเท่าเหล่านี้จาก Google Mobile Ads SDK ตัวอย่างการใช้การเรียกกลับมีดังนี้

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