אירועים בהתאמה אישית של מודעות מותאמות

דרישות מוקדמות

משלימים את הגדרת האירועים המותאמים אישית.

בקשה למודעה מותאמת

כשמגיעים לפריט של האירוע המותאם אישית בשרשרת של רשימת הרשתות בתהליך בחירת הרשת, לשיטה 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.