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

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

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

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

כשמגיעים לפריט האירוע המותאם אישית בשרשרת בחירת הרשת ב-Waterfall, מתבצעת קריאה ל-method‏ loadNativeAd() עם שם המחלקה שסיפקתם בזמן יצירת האירוע המותאם אישית. במקרה הזה, ה-method נמצא ב-SampleCustomEvent, שמפעיל את ה-method loadNativeAd() ב-SampleNativeCustomEventLoader.

כדי לבקש מודעת Native, יוצרים או משנים כיתה שמרחיבה את Adapter כדי להטמיע את loadNativeAd(). אם כבר יש כיתה שמרחיבה את Adapter, צריך להטמיע את loadNativeAd() בה. בנוסף, יוצרים כיתה חדשה כדי להטמיע את UnifiedNativeAdMapper.

בדוגמה לאירוע מותאם אישית, המחלקה SampleCustomEvent מרחיבה את המחלקה Adapter ולאחר מכן מעבירה את הגישה למחלקה SampleNativeCustomEventLoader.

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 ודיווח עליהן.

הפרמטר האופציונלי שמוגדר בממשק המשתמש של AdMob נכלל בהגדרות המודעה. אפשר לגשת לפרמטר דרך adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD). הפרמטר הזה הוא בדרך כלל מזהה של יחידת מודעות שנדרש ל-SDK של רשת המודעות כשיוצרים מופע של אובייקט מודעה.

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 עם קריאות חוזרות רלוונטיות:

@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 ל-SDK.

ה-UnifiedNativeAdMapper אחראי על התאמת ההבדלים האלה ועל התאמת אובייקט המודעה המותאם של ה-SDK שעבר תהליך בחירת רשת כך שיתאים לממשק ש-Google Mobile Ads SDK מצפה לו. אירועים מותאמים אישית צריכים להרחיב את המחלקה הזו כדי ליצור ממיפויים משלהם שספציפיים ל-SDK שלהם בתהליך בחירת הרשת. לפניכם דוגמה למיפוי מודעות מפרויקט לדוגמה של אירוע בהתאמה אישית:

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), ומשתמש בהם כדי להגדיר את המחיר של הממפה:

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 יש את הכיתה NativeAd.Image. בדומה לאופן שבו צריך ליצור קבוצת משנה של UnifiedNativeAdMapper כדי למפות מודעה לאורגניזציה שמנוהלת על ידי מערכת לבחירת רשת (Mediation), צריך גם ליצור קבוצת משנה של NativeAd.Image כשממפים נכסי תמונות.

דוגמה למחלקה SampleNativeMappedImage של האירוע המותאם אישית:

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 משתמש בכיתה של התמונה הממופה בשורה הזו כדי להגדיר את נכס תמונת הסמל של הממפה:

setIcon(new SampleNativeMappedImage(ad.getAppIcon(), ad.getAppIconUri(),
    SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));

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

חלק מ-SDKs בתהליך בחירת צד שלישי מספקים נכסים נוספים מעבר לאלה שבפורמט המודעות המותאם של AdMob. הכיתה UnifiedNativeAdMapper כוללת את השיטה setExtras() שמשמשת להעברת הנכסים האלה לבעלי האפליקציות. ה-SampleNativeAdMapper משתמש בזה בנכס 'מידת העוצמתיות' של ה-SDK לדוגמה:

Bundle extras = new Bundle();
extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, ad.getDegreeOfAwesomeness());
this.setExtras(extras);

בעלי תוכן דיגיטלי יכולים לאחזר את הנתונים באמצעות השיטה getExtras() של הכיתה NativeAd.

AdChoices

האירוע בהתאמה אישית אחראי לספק סמל של AdChoices באמצעות השיטה setAdChoicesContent() ב-UnifiedNativeAdMapper. לפניכם קטע קוד מ-SampleNativeAdMapper שמראה איך להציג את סמל AdChoices:

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(), שאירועים מותאמים אישית יכולים להטמיע כדי לקרוא לשיטה התואמת באובייקט המודעה הנתמכת:

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

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

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

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

יכול להיות שחלק מ-SDKs בתהליך בחירת הרשת יעדיפו לעקוב אחרי קליקים וחשיפות בעצמם. במקרה כזה, צריך לשנות את ברירת המחדל של מעקב הקליקים והחשיפות על ידי ביצוע שתי הקריאות הבאות ב-constructor של UnifiedNativeAdMapper:

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

אירועים מותאמים אישית שמבטלים את מעקב הקליקים והחשיפות חייבים לדווח על האירועים onAdClicked() ו-onAdImpression() ל-Google Mobile Ads SDK.

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

@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.

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

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