דרישות מוקדמות
משלימים את הגדרת האירועים המותאמים אישית.
בקשה למודעה מותאמת
כשמגיעים לפריט של האירוע המותאם אישית בשרשרת של רשימת הרשתות בתהליך בחירת הרשת,
לשיטה loadNativeAd()
קוראים את שם הכיתה שסיפקתם,
יצירת התאמה אישית
אירוע. במקרה הזה,
ה-method הזה הוא ב-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.
הפרמטר האופציונלי שמוגדר בממשק המשתמש של 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
.
בדרך כלל, השיטות האלה מוטמעות בתוך קריאות חוזרות (callbacks)
ה-SDK של הצד השלישי שהמתאם מטמיע. לצורך הדוגמה הזו, ערכת ה-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 שונות יש פורמטים ייחודיים משלהן למודעות מותאמות. אחד עשוי להחזיר אובייקטים שמכילים 'title'. לדוגמה, בעוד שבשדה אחר יכול להיות 'headline'. כמו כן, השיטות שמשמשות למעקב אחר חשיפות ועיבוד מספר הקליקים יכול להשתנות בין ערכת SDK אחת לאחרת.
הגורם האחראי לפתרון ההבדלים האלה הוא UnifiedNativeAdMapper
להתאים את האובייקט של מודעות מותאמות ב-SDK שמשתתף בתהליך בחירת הרשת (Mediation) כך שיתאים לממשק הצפוי:
Google Mobile Ads SDK. על אירועים מותאמים אישית להרחיב את הכיתה הזו כדי ליצור
ממפים ספציפיים ל-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. } }
עכשיו אנחנו נבחן מקרוב את הקוד של ה-constructor.
כוללים הפניה לאובייקט של המודעה המותאמת שמשתתפת בתהליך בחירת הרשת
ה-constructor מקבל את הפרמטר SampleNativeAd
, סוג המודעות המותאמות שבו נעשה שימוש
ה-SDK לדוגמה כדי ליצור את המודעות המותאמות. הממפה צריך הפניה אל
מודעה שמשתתפת בתהליך בחירת הרשת, כדי שהיא תוכל להעביר אירועים מסוג קליק וחשיפות. SampleNativeAd
הוא
מאוחסנים כמשתנה מקומי.
הגדרת מאפיינים של נכסים ממופים
ה-constructor משתמש באובייקט SampleNativeAd
כדי לאכלס נכסים
UnifiedNativeAdMapper
.
קטע הקוד הזה מקבל את נתוני המחירים של המודעה בתהליך בחירת הרשת ומשתמש בהם כדי להגדיר מחיר:
Java
if (sampleAd.getPrice() != null) { NumberFormat formatter = NumberFormat.getCurrencyInstance(); String priceString = formatter.format(sampleAd.getPrice()); setPrice(priceString); }
בדוגמה הזו, במודעה בתהליך בחירת הרשת המחיר נשמר בתור double
. עם זאת,
מערכת Ad Manager משתמשת בפרמטר String
עבור אותו נכס.
"ממפה" אחראי לטיפול בסוגים אלה של המרות.
מיפוי נכסי תמונות
מיפוי נכסי תמונות מסובך יותר ממיפוי סוגי נתונים כמו
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
משתמש במחלקה של התמונה הממופה בשורה הזו כדי להגדיר את
נכס תמונות סמל של מיפוי:
Java
setIcon(new SampleNativeMappedImage(ad.getAppIcon(), ad.getAppIconUri(), SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));
הוספת שדות לחבילת התוספות
חלק מערכות ה-SDK שמשתתפות בתהליך בחירת הרשת (Mediation) מספקות נכסים נוספים, מעבר לאלה שכלולים
פורמט של מודעות מותאמות ב-Ad Manager. UnifiedNativeAdMapper
המחלקה כוללת את השיטה setExtras()
שמשמשת להעברת הנכסים האלה אל
בעלי תוכן דיגיטלי. השדה הזה משמש את SampleNativeAdMapper
בערכות ה-SDK לדוגמה
"מידת המגניבות" נכס:
Java
Bundle extras = new Bundle(); extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, ad.getDegreeOfAwesomeness()); this.setExtras(extras);
בעלי אפליקציות יכולים לאחזר את הנתונים באמצעות המחלקה NativeAd
getExtras()
.
AdChoices
באחריות האירוע המותאם אישית שלך להוסיף את הסמל AdChoices באמצעות
setAdChoicesContent()
בשיטה UnifiedNativeAdMapper
. הנה קטע קוד מתוך
SampleNativeAdMapper
שמראה איך לספק את סמל AdChoices:
Java
public SampleNativeAdMapper(SampleNativeAd ad) { ... setAdChoicesContent(sampleAd.getInformationIcon()); }
אירועי חשיפות וקליקים
גם Google Mobile Ads SDK וגם ה-SDK שמשתתפות בתהליך בחירת הרשת צריכים לדעת מתי חשיפה או קליק מתרחשים, אבל רק ערכת SDK אחת צריכה לעקוב אחר האירועים האלה. יש קיימות שתי גישות שונות שבהן אירועים מותאמים אישית יכולים להשתמש, בהתאם ב-SDK בתהליך בחירת הרשת אפשר לעקוב בנפרד אחרי חשיפות וקליקים.
מעקב אחרי קליקים וחשיפות בעזרת Google Mobile Ads SDK
אם ערכת ה-SDK שמשתתפת בתהליך בחירת הרשת לא מבצעת מעקב אחרי חשיפות וקליקים משלה, אבל
מספק שיטות לתיעוד קליקים וחשיפות, Google Mobile Ads SDK יכול
לעקוב אחרי האירועים האלה ולהודיע למתאם.
מחלקה אחת (UnifiedNativeAdMapper
) כוללת שתי שיטות:
recordImpression()
וגם handleClick()
אפשר להטמיע אירועים מותאמים אישית כדי להפעיל את השיטה המתאימה בתהליך בחירת הרשת
אובייקט של מודעה מותאמת:
Java
@Override public void recordImpression() { sampleAd.recordImpression(); } @Override public void handleClick(View view) { sampleAd.handleClick(view); }
כי ב-SampleNativeAdMapper
יש הפניה למקור של ה-SDK לדוגמה
אובייקט של מודעה, הוא יכול לקרוא לשיטה המתאימה באובייקט הזה כדי לדווח על קליק
או חשיפה. שימו לב שהשיטה handleClick()
פרמטר יחיד: האובייקט View
שתואם לנכס המודעה המותאם
קיבל את הקליק.
מעקב אחרי קליקים וחשיפות באמצעות ה-SDK בתהליך בחירת הרשת (Mediation)
יכול להיות שחלק מערכות ה-SDK שמשתתפות בתהליך בחירת הרשת יעדיפו לעקוב אחרי קליקים וחשיפות בעצמם. לחשבון
במקרה כזה, יש לעקוף את מעקב ברירת המחדל של קליקים וחשיפות על ידי
לבצע את שתי הקריאות הבאות ב-constructor של
UnifiedNativeAdMapper
:
Java
setOverrideClickHandling(true); setOverrideImpressionRecording(true);
אירועים מותאמים אישית שמבטלים את המעקב אחרי קליקים וחשיפות נדרשים כדי
לדווח על האירועים onAdClicked()
ו-onAdImpression()
ל-Google Mobile
Ads SDK.
כדי לעקוב אחרי חשיפות וקליקים, סביר להניח ל-SDK שמשתתף בתהליך בחירת הרשת גישה אל
כדי להפעיל את המעקב. האירוע המותאם אישית צריך לבטל את
trackViews()
ולהשתמש בה כדי להעביר את הצפייה של המודעה המותאמת אל תהליך בחירת הרשת
SDK למעקב. ה-SDK לדוגמה מהפרויקט לדוגמה של אירוע מותאם אישית (שממנו הוא
כבר לקחנו את קטעי הקוד במדריך הזה) אינם משתמשים בגישה הזו. אבל אם
זה היה נראה כך, קוד האירוע המותאם אישית ייראה כך:
Java
@Override public void trackViews(View containerView, Map<String, View> clickableAssetViews, Map<String, View> nonClickableAssetViews) { sampleAd.setNativeAdViewForTracking(containerView); }
אם ערכת ה-SDK שמשתתפת בתהליך בחירת הרשת (Mediation) תומכת במעקב אחרי נכסים ספציפיים, היא יכולה לבדוק את המידע מבפנים.
clickableAssetViews
כדי לבדוק אילו תצוגות צריך להיות קליקביליות. המפה הזו
מופיע לפי שם נכס ב-NativeAdAssetNames
. UnifiedNativeAdMapper
הוא מציע שיטה תואמת של untrackView()
שאירועים מותאמים אישית יכולים לבטל.
כדי להסיר הפניות לתצוגה המפורטת ולבטל את השיוך שלה למודעה המותאמת
לאובייקט.
העברת אירועי תהליך בחירת הרשת (Mediation) אל Google Mobile Ads SDK
אפשר למצוא את כל הקריאות החוזרות שנתמכות בתהליך בחירת הרשת
MediationNativeAdCallback
מסמכים.
חשוב שהאירוע בהתאמה אישית יעביר כמה שיותר מהקריאות החוזרות האלה כדי שהאפליקציה שלך תקבל את האירועים המקבילים האלה Mobile Ads SDK. דוגמה לשימוש בקריאות חוזרות (callback):
הושלמה ההטמעה של אירועים מותאמים אישית במודעות מותאמות. הדוגמה המלאה זמין ב- GitHub.