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

בחירת פלטפורמה: Android iOS Android (גרסה קודמת)

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

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

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

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

בדרך כלל, השיטות האלה מוטמעות בתוך קריאות חוזרות (callbacks) מ-SDK של צד שלישי שהמתאם שלכם מטמיע. בדוגמה הזו, ל-Sample SDK יש SampleAdListener עם קריאות חוזרות (callbacks) רלוונטיות:

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));
}

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

לערכות 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)

ה-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, ואילו 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));

הוספת שדות ל-Bundle של התוספות

חלק מה-SDK של רשתות המודעות מספקים נכסים נוספים מעבר לאלה שקיימים בפורמט המודעות המותאמות של AdMob. המחלקה UnifiedNativeAdMapper כוללת את השיטה setExtras() שמשמשת להעברת הנכסים האלה לבעלי האפליקציות. ה-SampleNativeAdMapper משתמש בזה לנכס "degree of awesomeness" של ה-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 לדוגמה, הוא יכול להפעיל את השיטה המתאימה באובייקט הזה כדי לדווח על קליק או חשיפה. שימו לב שה-method‏ handleClick() מקבלת פרמטר אחד: האובייקט View שתואם לנכס שמצורף למודעה המותאמת שקיבל את הקליק.

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

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

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

במסמכי התיעוד של MediationNativeAdCallback מפורטים כל הקריאות החוזרות (callbacks) שנתמכות בתהליך בחירת הרשת.

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

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