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