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

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

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

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

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

כדי לבקש מודעת Native, יוצרים או משנים כיתה שמרחיבה את 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 ודיווח עליהן.

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

בדרך כלל, השיטות האלה מיושמות בתוך קריאות חזרה (callbacks) מ-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));
}

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

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

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

קטע הקוד הזה מקבל את נתוני המחיר של המודעה שבוצעה עבורה תהליך בחירת רשת (Mediation), ומשתמש בהם כדי להגדיר את המחיר של הממפה:

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

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

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

Java

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

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

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

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

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

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

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