דרישות מוקדמות
משלימים את הגדרת האירועים בהתאמה אישית.
שליחת בקשה להצגת מודעה מותאמת
כשמגיעים לפריט האירוע המותאם אישית בשרשרת בחירת הרשת ב-Waterfall, מתבצעת קריאה ל-method loadNativeAd()
עם שם המחלקה שסיפקתם בזמן יצירת האירוע המותאם אישית. במקרה הזה, ה-method נמצא ב-SampleCustomEvent
, שמפעיל את ה-method loadNativeAd()
ב-SampleNativeCustomEventLoader
.
כדי לבקש מודעת Native, יוצרים או משנים כיתה שמרחיבה את 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
.קבלת קריאות חזרה (callbacks) של אירועי מודעות ודיווח עליהן ל-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
עם קריאות חוזרות רלוונטיות:
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)); }
מיפוי של מודעות מותאמות
ל-SDKs שונים יש פורמטים ייחודיים משלהם של מודעות מותאמות. לדוגמה, פונקציה אחת עשויה להחזיר אובייקטים שמכילים את השדה 'title', ואילו פונקציה אחרת עשויה להחזיר את השדה 'headline'. בנוסף, השיטות שבהן נעשה שימוש למעקב אחר חשיפות ולעיבוד קליקים עשויות להשתנות מ-SDK אחד למשנהו.
ה-UnifiedNativeAdMapper
אחראי על התאמת ההבדלים האלה ועל התאמת אובייקט המודעה המותאם של ה-SDK שעבר תהליך בחירת רשת כך שיתאים לממשק ש-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
, שהוא הכיתה של המודעות המותאמות שבה נעשה שימוש ב-Sample SDK למודעות המותאמות שלו. לממפה צריכה להיות הפניה למודעה שבאמצעותה בוצעה בחירת הרשת, כדי שהוא יוכל להעביר אירועי קליקים ואירועי חשיפות. המשתנה SampleNativeAd
מאוחסן כמשתנה מקומי.
הגדרת מאפיינים של נכסים ממופה
ה-constructor משתמש באובייקט SampleNativeAd
כדי לאכלס נכסים ב-UnifiedNativeAdMapper
.
קטע הקוד הזה מקבל את נתוני המחיר של המודעה שבוצעה עבורה תהליך בחירת רשת (Mediation), ומשתמש בהם כדי להגדיר את המחיר של הממפה:
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
כדי למפות מודעה לאורגניזציה שמנוהלת על ידי מערכת לבחירת רשת (Mediation), צריך גם ליצור קבוצת משנה של 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));
הוספת שדות לחבילת התוספים
חלק מ-SDKs בתהליך בחירת הרשת מספקים נכסים נוספים מעבר לאלה שכלולים בפורמט המודעות המותאם של 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
האירוע בהתאמה אישית אחראי לספק סמל של 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
מכיל הפניה לאובייקט המודעות המקורי של Sample SDK, הוא יכול להפעיל את השיטה המתאימה באובייקט הזה כדי לדווח על קליק או על חשיפת מודעה. שימו לב שהשיטה handleClick()
מקבלת פרמטר אחד: אובייקט View
שתואם לנכס המודעה המותאמת שקיבל את הקליק.
מעקב אחר קליקים וחשיפות באמצעות ה-SDK המתווך
יכול להיות שחלק מ-SDKs בתהליך בחירת הרשת יעדיפו לעקוב אחרי קליקים וחשיפות בעצמם. במקרה כזה, צריך לשנות את ברירת המחדל של מעקב הקליקים והחשיפות על ידי ביצוע שתי הקריאות הבאות ב-constructor של UnifiedNativeAdMapper
:
Java
setOverrideClickHandling(true); setOverrideImpressionRecording(true);
אירועים מותאמים אישית שמבטלים את מעקב הקליקים והחשיפות חייבים לדווח על האירועים onAdClicked()
ו-onAdImpression()
ל-Google Mobile Ads SDK.
כדי לעקוב אחרי חשיפות וקליקים, סביר להניח ש-SDK המתווך צריך גישה לתצוגות כדי לאפשר את המעקב. האירוע המותאם אישית צריך לשנות את השיטה trackViews()
ולהשתמש בה כדי להעביר את התצוגה של המודעה המותאמת ל-SDK לבחירת הרשת (Mediated 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()
, שאירועים מותאמים אישית יכולים לשנות כדי לשחרר את כל ההפניות לתצוגה ולבטל את השיוך שלה לאובייקט המודעה המקורי.
העברה של אירועי בחירת רשת מודעות אל Google Mobile Ads SDK
כל קריאות החזרה (callbacks) שנתמכות בתהליך בחירת הרשת מפורטות במסמכים של MediationNativeAdCallback
.
חשוב שהאירוע המותאם אישית יעביר כמה שיותר קריאות חוזרות כאלה, כדי שהאפליקציה תקבל את האירועים המקבילים האלה מ-Google Mobile Ads SDK. דוגמה לשימוש בקריאות חזרה (callbacks):
זהו סוף תהליך ההטמעה של האירועים בהתאמה אישית במודעות מותאמות. הדוגמה המלאה זמינה ב-GitHub.