ข้อกำหนดเบื้องต้น
ตั้งค่าเหตุการณ์ที่กำหนดเองให้เสร็จสมบูรณ์
ส่งคำขอโฆษณาเนทีฟ
เมื่อถึงรายการโฆษณาเหตุการณ์ที่กำหนดเองในเชนสื่อกลางตามลำดับขั้น (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 เหตุการณ์โฆษณาไปยัง Google Mobile Ads SDK
ระบบจะรวมพารามิเตอร์ที่ไม่บังคับซึ่งกำหนดไว้ใน UI ของ Ad Manager ไว้ในการกำหนดค่าโฆษณา โดยคุณเข้าถึงพารามิเตอร์ได้ผ่าน 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 ของบุคคลที่สามที่อะแดปเตอร์ของคุณใช้ ในตัวอย่างนี้ Sample 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)); }
แมปโฆษณาเนทีฟ
SDK ต่างๆ มีรูปแบบเฉพาะของตนเองสำหรับโฆษณาเนทีฟ เช่น SDK หนึ่งอาจแสดงออบเจ็กต์ที่มีช่อง "title" ขณะที่อีก SDK อาจมี "headline" นอกจากนี้ เมธอดที่ใช้ติดตามการแสดงผลและประมวลผลการคลิกอาจแตกต่างกันไปในแต่ละ SDK
UnifiedNativeAdMapper มีหน้าที่รับผิดชอบในการแก้ไขความแตกต่างเหล่านี้และ
ปรับออบเจ็กต์โฆษณาเนทีฟของ SDK สื่อกลางให้ตรงกับอินเทอร์เฟซที่
Google Mobile Ads SDK คาดหวัง เหตุการณ์ที่กำหนดเองควรขยายคลาสนี้เพื่อสร้าง Mapper ของตนเองที่เฉพาะเจาะจงกับ SDK สื่อกลาง ต่อไปนี้คือตัวอย่าง Mapper โฆษณาจากโปรเจ็กต์เหตุการณ์ที่กำหนดเองตัวอย่าง
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 ซึ่งเป็นคลาสโฆษณาเนทีฟที่ Sample SDK ใช้สำหรับโฆษณาเนทีฟ Mapper ต้องมีการอ้างอิงโฆษณาสื่อกลางเพื่อให้ส่งต่อเหตุการณ์การคลิกและการแสดงผลได้ ระบบจะจัดเก็บ SampleNativeAd เป็นตัวแปรภายใน
ตั้งค่าพร็อพเพอร์ตี้ชิ้นงานที่แมป
คอนสตรักเตอร์ใช้ออบเจ็กต์ SampleNativeAd เพื่อป้อนข้อมูลชิ้นงานใน UnifiedNativeAdMapper
ข้อมูลโค้ดนี้จะดึงข้อมูลราคาของโฆษณาสื่อกลางและใช้ข้อมูลดังกล่าวเพื่อตั้งค่าราคาของ Mapper
Java
if (sampleAd.getPrice() != null) { NumberFormat formatter = NumberFormat.getCurrencyInstance(); String priceString = formatter.format(sampleAd.getPrice()); setPrice(priceString); }
ในตัวอย่างนี้ โฆษณาสื่อกลางจะจัดเก็บราคาเป็น double ขณะที่ Ad Manager ใช้ String สำหรับชิ้นงานเดียวกัน Mapper มีหน้าที่รับผิดชอบในการจัดการ Conversion ประเภทนี้
แมปชิ้นงานรูปภาพ
การแมปชิ้นงานรูปภาพมีความซับซ้อนกว่าการแมปประเภทข้อมูล เช่น double หรือ String เนื่องจากระบบอาจดาวน์โหลดรูปภาพโดยอัตโนมัติหรือแสดงผลเป็นค่า URL นอกจากนี้ สเกลพิกเซลต่อ DPI ก็อาจแตกต่างกันด้วย
เพื่อช่วยคุณจัดการรายละเอียดเหล่านี้ Google Mobile Ads SDK มีคลาส 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 ใช้คลาสรูปภาพที่แมปในบรรทัดนี้เพื่อตั้งค่าชิ้นงานรูปภาพไอคอนของ Mapper
Java
setIcon(new SampleNativeMappedImage(ad.getAppIcon(), ad.getAppIconUri(), SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));
เพิ่มช่องลงใน Bundle ส่วนเพิ่มเติม
SDK สื่อกลางบางรายการมีชิ้นงานเพิ่มเติมนอกเหนือจากชิ้นงานในรูปแบบโฆษณาเนทีฟของ Ad Manager คลาส UnifiedNativeAdMapper มีเมธอด setExtras() ที่ใช้ส่งชิ้นงานเหล่านี้ไปยังผู้เผยแพร่โฆษณา SampleNativeAdMapper ใช้เมธอดนี้สำหรับชิ้นงาน "degree of awesomeness" ของ Sample 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()); }
เหตุการณ์การแสดงผลและการคลิก
ทั้ง Google Mobile Ads SDK และ SDK สื่อกลางต้องทราบเมื่อมีการแสดงผลหรือการคลิก แต่มีเพียง SDK เดียวเท่านั้นที่ต้องติดตามเหตุการณ์เหล่านี้ เหตุการณ์ที่กำหนดเองสามารถใช้แนวทางที่แตกต่างกัน 2 แนวทาง ขึ้นอยู่กับว่า SDK สื่อกลางรองรับการติดตามการแสดงผลและการคลิกด้วยตนเองหรือไม่
ติดตามการคลิกและการแสดงผลด้วย Google Mobile Ads SDK
หาก SDK สื่อกลางไม่ได้ติดตามการแสดงผลและการคลิกด้วยตนเอง แต่
มีเมธอดในการบันทึกการคลิกและการแสดงผล Google Mobile Ads SDK สามารถ
ติดตามเหตุการณ์เหล่านี้และแจ้งอะแดปเตอร์ คลาส UnifiedNativeAdMapper มี 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() ไปยัง Google Mobile Ads SDK
ในการติดตามการแสดงผลและการคลิก SDK สื่อกลางอาจต้องเข้าถึงมุมมองเพื่อเปิดใช้การติดตาม เหตุการณ์ที่กำหนดเองควรลบล้างเมธอด trackViews() และใช้เมธอดนี้เพื่อส่งมุมมองของโฆษณาเนทีฟไปยัง SDK สื่อกลางเพื่อติดตาม Sample SDK จากโปรเจ็กต์เหตุการณ์ที่กำหนดเองตัวอย่าง (ซึ่งเรานำข้อมูลโค้ดในคู่มือนี้มา) ไม่ได้ใช้แนวทางนี้ แต่หากใช้ โค้ดเหตุการณ์ที่กำหนดเองจะมีลักษณะดังนี้
Java
@Override public void trackViews(View containerView, Map<String, View> clickableAssetViews, Map<String, View> nonClickableAssetViews) { sampleAd.setNativeAdViewForTracking(containerView); }
หาก SDK สื่อกลางรองรับการติดตามชิ้นงานแต่ละรายการ SDK จะดูภายใน clickableAssetViews เพื่อดูว่าควรทำให้มุมมองใดคลิกได้ แผนที่นี้มีคีย์เป็นชื่อชิ้นงานใน NativeAdAssetNames UnifiedNativeAdMapper มีเมธอด untrackView() ที่สอดคล้องกัน ซึ่งเหตุการณ์ที่กำหนดเองสามารถลบล้างเพื่อปล่อยการอ้างอิงมุมมองและยกเลิกการเชื่อมโยงมุมมองกับออบเจ็กต์โฆษณาเนทีฟได้
ส่งต่อเหตุการณ์สื่อกลางไปยัง Google Mobile Ads SDK
คุณดู Callback ทั้งหมดที่สื่อกลางรองรับได้ในเอกสารประกอบ
MediationNativeAdCallback
เหตุการณ์ที่กำหนดเองควรส่งต่อ Callback เหล่านี้ให้ได้มากที่สุด เพื่อให้แอปได้รับเหตุการณ์ที่เทียบเท่าจาก Google Mobile Ads SDK ต่อไปนี้คือตัวอย่างการใช้ Callback
การดำเนินการนี้จะทำให้การติดตั้งใช้งานเหตุการณ์ที่กำหนดเองสำหรับโฆษณาเนทีฟเสร็จสมบูรณ์ ดูตัวอย่างฉบับเต็มได้ใน GitHub