דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

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

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

מיפוי של מודעות מותאמות

ל-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, סוג המודעות המותאמות שבו נעשה שימוש ה-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 מספק כיתה אחת (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));

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

חלק מערכות ה-SDK שמשתתפות בתהליך בחירת הרשת (Mediation) מספקות נכסים נוספים, מעבר לאלה שכלולים פורמט של מודעות מותאמות ב-AdMob. הכיתה 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)

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

העברה של אירועי בחירת רשת מודעות אל Google Mobile Ads SDK

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

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

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