ข้อกำหนดเบื้องต้น
ทําการตั้งค่าเหตุการณ์ที่กําหนดเองให้เสร็จสมบูรณ์
ขอโฆษณาเนทีฟ
เมื่อถึงรายการโฆษณาเหตุการณ์ที่กําหนดเองในเชนการแสดงโฆษณาสื่อกลางตามลําดับขั้น ระบบจะเรียกใช้เมธอด 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
การรับและการรายงานการเรียกกลับเหตุการณ์โฆษณาไปยัง SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google
พารามิเตอร์ที่ไม่บังคับซึ่งกําหนดไว้ใน 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()
เรียกโดยส่งอินสแตนซ์ของคลาสที่ implements
MediationNativeAd
โดยทั่วไปแล้ว วิธีการเหล่านี้จะใช้ภายในการเรียกกลับจาก 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
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
ซึ่งเป็นคลาสโฆษณาเนทีฟที่ Sample SDK ใช้สำหรับโฆษณาเนทีฟ โปรแกรมแมปต้องมีข้อมูลอ้างอิงถึงโฆษณาสื่อกลางเพื่อให้ส่งเหตุการณ์การคลิกและการแสดงผลได้ SampleNativeAd
จะเก็บไว้เป็นตัวแปรภายใน
ตั้งค่าพร็อพเพอร์ตี้ของชิ้นงานที่แมป
ตัวสร้างใช้ออบเจ็กต์ SampleNativeAd
เพื่อป้อนข้อมูลชิ้นงานใน UnifiedNativeAdMapper
ข้อมูลโค้ดนี้รับข้อมูลราคาของโฆษณาสื่อกลางและใช้ข้อมูลดังกล่าวเพื่อตั้งค่าราคาของโปรแกรมเปลี่ยนเส้นทาง
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 ของอุปกรณ์แต่ละเครื่องก็อาจแตกต่างกันไป
Google Mobile Ads 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
ใช้คลาสรูปภาพที่แมปในบรรทัดนี้เพื่อตั้งค่าชิ้นงานรูปภาพไอคอนของโปรแกรมแมป
Java
setIcon(new SampleNativeMappedImage(ad.getAppIcon(), ad.getAppIconUri(), SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));
เพิ่มช่องลงในแพ็กเกจพิเศษ
SDK แบบสื่อกลางบางรายการมีชิ้นงานเพิ่มเติมนอกเหนือจากชิ้นงานในโฆษณาเนทีฟรูปแบบ AdMob คลาส UnifiedNativeAdMapper
มีเมธอด setExtras()
ที่ใช้ส่งชิ้นงานเหล่านี้ไปยังผู้เผยแพร่โฆษณา SampleNativeAdMapper
ใช้ข้อมูลนี้สําหรับชิ้นงาน "ระดับความเจ๋ง" ของ Sample 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()); }
เหตุการณ์การแสดงผลและการคลิก
ทั้ง Google Mobile Ads SDK และ SDK ที่มีสื่อกลางจําเป็นต้องทราบว่าเมื่อใดที่เกิดการแสดงผลหรือการคลิกขึ้น แต่มีเพียง SDK เดียวเท่านั้นที่ต้องติดตามเหตุการณ์เหล่านี้ เหตุการณ์ที่กําหนดเองใช้ได้ 2 วิธี โดยขึ้นอยู่กับว่า SDK ที่สื่อกลางรองรับการติดตามการแสดงผลและการคลิกด้วยตนเองหรือไม่
ติดตามการคลิกและการแสดงผลด้วย SDK โฆษณาในอุปกรณ์เคลื่อนที่ของ Google
หาก 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()
ไปยัง 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
เหตุการณ์ที่กําหนดเองต้องส่งต่อการเรียกกลับเหล่านี้ให้ได้มากที่สุด เพื่อให้แอปได้รับเหตุการณ์ที่เทียบเท่าเหล่านี้จาก Google Mobile Ads SDK ตัวอย่างการใช้การเรียกกลับมีดังนี้
การดำเนินการนี้ถือเป็นการติดตั้งใช้งานเหตุการณ์ที่กําหนดเองสําหรับโฆษณาเนทีฟ ดูตัวอย่างแบบเต็มได้ใน GitHub