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

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

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

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

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

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

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

בדוגמה של האירוע בהתאמה אישית, SampleCustomEvent מטמיעthe Adapter interface ואז מעניק גישה ל-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 interface
קבלת קריאות חוזרות של אירועי מודעות ודיווח עליהן ל-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.

בדרך כלל, השיטות האלה מוטמעות בקריאות חוזרות מ-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", ואילו אובייקט אחר עשוי להכיל "כותרת". בנוסף, השיטות שמשמשות למעקב אחרי חשיפות ולעיבוד קליקים יכולות להשתנות מערכת 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, מחלקת המודעות המותאמות שבה נעשה שימוש ב-Sample 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 שמשתתפות בתהליך בחירת הרשת מספקות נכסים נוספים, מעבר לאלה שבפורמטAd Manager מודעות מותאמות. המחלקה 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 וגם ה-SDK של תהליך בחירת הרשת צריכים לדעת מתי מתרחשים חשיפה או קליק, אבל רק ערכת SDK אחת צריכה לעקוב אחרי האירועים האלה. יש שתי גישות שונות שבהן ניתן להשתמש באירועים מותאמים אישית, בהתאם לשאלה האם ה-SDK המתווך תומך במעקב אחר חשיפות וקליקים בעצמו.

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

אם ה-SDK של תהליך בחירת הרשת לא מבצע מעקב אחר חשיפות וקליקים משלו, אבל מספק שיטות לתיעוד קליקים וחשיפות, Google Mobile Ads SDK יכול לעקוב אחרי האירועים האלה ולהודיע למתאם. UnifiedNativeAdMapper interface כולל שתי שיטות: 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 שמשתתפות בתהליך בחירת הרשת מומלץ לעקוב בעצמן אחרי קליקים וחשיפות. במקרה כזה, כדאי לבטל את ברירת המחדל למעקב אחר קליקים וחשיפות על ידי ביצוע שתי הקריאות הבאות ב-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

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

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

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