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

בחירת פלטפורמה: Android iOS Android (Legacy)

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

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

שליחת בקשה להצגת מודעה מותאמת

כשמגיעים לפריט של אירוע מותאם אישית בשרשרת של רשימת הרשתות בתהליך בחירת הרשת, מתבצעת קריאה לשיטה loadNativeAd() בשם המחלקה שסיפקתם כשיצרתם אירוע מותאם אישית. במקרה הזה, ה-method נמצא ב-SampleCustomEvent, שקורא ל-method‏ 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 (Legacy).

הפרמטר האופציונלי שהוגדר בממשק המשתמש של 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() מופעלת על ידי העברת מופע של המחלקה שמטמיעה את MediationNativeAd.

בדרך כלל, השיטות האלה מוטמעות בתוך פונקציות callback מתוך ה-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));
}

מודעות מותאמות במפות

ל-SDK שונים יש פורמטים ייחודיים משלהם למודעות מותאמות. לדוגמה, יכול להיות שאחד יחזיר אובייקטים שמכילים שדה בשם title, ואילו השני יחזיר אובייקטים עם שדה בשם headline. בנוסף, השיטות שמשמשות למעקב אחרי חשיפות ולעיבוד קליקים יכולות להשתנות מ-SDK אחד לאחר.

ה-UnifiedNativeAdMapper אחראי לגישור על הפערים האלה ולהתאמת אובייקט של מודעה מותאמת של SDK לגישור כך שיתאים לממשק שנדרש על ידי Google Mobile Ads SDK (Legacy). אירועים מותאמים אישית צריכים להרחיב את המחלקה הזו כדי ליצור ממפים משלהם שספציפיים ל-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.

השהיית הפניה לאובייקט של מודעה מותאמת באתר שמוצגת באמצעות Mediation

הבנאי מקבל את הפרמטר 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 לאותו נכס. המיפוי אחראי לטיפול בסוגי ההמרות האלה.

נכסי תמונות של מפות

מיפוי של נכסי תמונות הוא מורכב יותר ממיפוי של סוגי נתונים כמו double או String. יכול להיות שהתמונות יורדו באופן אוטומטי או שיוחזרו כערכי כתובות URL. גם קנה המידה של הפיקסלים ל-DPI יכול להיות שונה.

כדי לעזור לכם לנהל את הפרטים האלה, Google Mobile Ads SDK (Legacy) מספקת את המחלקה 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));

הוספת שדות לחבילת התוספים

חלק מה-SDKs של רשתות גישור מספקים נכסים נוספים מעבר לאלה שבפורמט המודעה המקורית של AdMob. המחלקות UnifiedNativeAdMapper כוללות שיטה setExtras() שמשמשת להעברת הנכסים האלה לבעלי תוכן דיגיטלי. ה-SampleNativeAdMapper משתמש בזה בשביל נכס 'רמת המדהימות' של Sample 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 (Legacy) וגם ה-SDK לבחירת רשת צריכים לדעת מתי מתרחשים צפייה או קליק, אבל רק SDK אחד צריך לעקוב אחרי האירועים האלה. יש שני סוגים של אירועים מותאמים אישית, בהתאם לשאלה אם ה-SDK של הרשת המגשרת תומך במעקב אחרי חשיפות וקליקים באופן עצמאי.

מעקב אחרי קליקים וחשיפות באמצעות Google Mobile Ads SDK (Legacy)

אם ה-SDK של הרשת המגשרת לא מבצע מעקב משלו אחרי חשיפות וקליקים, אבל מספק שיטות לתיעוד קליקים וחשיפות, Google Mobile Ads SDK (Legacy) יכול לעקוב אחרי האירועים האלה ולעדכן את המתאם. המחלקה UnifiedNativeAdMapper כוללת שתי שיטות: recordImpression() ו-handleClick(). אירועים מותאמים אישית יכולים להטמיע את השיטות האלה כדי להפעיל את השיטה המתאימה באובייקט של המודעה המקורית שמוצגת באמצעות גישור:

Java

@Override
public void recordImpression() {
  sampleAd.recordImpression();
}

@Override
public void handleClick(View view) {
  sampleAd.handleClick(view);
}

המשתנה SampleNativeAdMapper מכיל הפניה לאובייקט המודעה המקורי של ערכת ה-SDK לדוגמה, ולכן אפשר להשתמש בו כדי להפעיל את השיטה המתאימה באובייקט הזה ולדווח על קליק או על חשיפה. שימו לב שהשיטה handleClick() מקבלת פרמטר יחיד: האובייקט View שמתאים לנכס שמצורף למודעה המותאמת שקיבל את הקליק.

מעקב אחר קליקים וחשיפות באמצעות ה-SDK של הגישור

יכול להיות שחלק מה-SDKs של רשתות גישור יעדיפו לעקוב אחרי קליקים וחשיפות בעצמם. במקרה כזה, צריך לבטל את ברירת המחדל של מעקב הקליקים והחשיפות על ידי ביצוע שתי הקריאות הבאות בבונה של 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 של הרשת המגשרת תומך במעקב אחרי נכסים נפרדים, הוא יכול לבדוק בתוך clickableAssetViews אילו תצוגות צריכות להיות קליקביליות. המפה הזו מבוססת על שם נכס ב-NativeAdAssetNames. ה-API ‏UnifiedNativeAdMapper כולל שיטה תואמת untrackView() שאירועים מותאמים אישית יכולים לבטל כדי לשחרר הפניות לתצוגה ולבטל את השיוך שלה לאובייקט של המודעה המקורית.

העברת אירועים של בחירת רשת (Mediation) אל Google Mobile Ads SDK (Legacy)

כל הקריאות החוזרות שנתמכות בתהליך בחירת הרשת מפורטות במסמכי MediationNativeAdCallback.

חשוב שהאירוע המותאם אישית יעביר כמה שיותר מהקריאות החוזרות האלה, כדי שהאפליקציה תקבל את האירועים המקבילים האלה מ-Google Mobile Ads SDK (Legacy). דוגמה לשימוש בפונקציות קריאה חוזרת:

כך מסיימים את ההטמעה של אירועים מותאמים אישית במודעות מותאמות. הדוגמה המלאה זמינה ב-GitHub.