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

בחירת פלטפורמה: Android iOS Android (Legacy)

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

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

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

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

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

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

הבנאי מקבל את הפרמטר 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, אבל 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));

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

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

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

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

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

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

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

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