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

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

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

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

เมื่อระบบเข้าถึงรายการโฆษณาของเหตุการณ์ที่กําหนดเองในเชนสื่อกลางตามลำดับขั้น มีการเรียกใช้เมธอด 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 ไปใช้

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

พารามิเตอร์ที่ไม่บังคับที่กำหนดไว้ใน UI ของ Ad Manager คือ ที่รวมอยู่ในการกำหนดค่าโฆษณา พารามิเตอร์นี้สามารถเข้าถึงได้ 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() โดยการส่งต่อในอินสแตนซ์ของคลาสที่นำไปใช้ MediationNativeAd

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

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

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

เครื่องมือสร้างใช้ออบเจ็กต์ SampleNativeAd เพื่อสร้างเนื้อหาใน UnifiedNativeAdMapper

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

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 ของเหตุการณ์ที่กำหนดเองมีดังนี้

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

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

ผู้เผยแพร่โฆษณาสามารถเรียกดูข้อมูลโดยใช้คลาส NativeAd วันที่ getExtras()

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

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

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

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

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

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

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

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

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

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

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

หากต้องการติดตามการแสดงผลและการคลิก 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

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

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

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