رویدادهای سفارشی تبلیغات بومی

پیش‌نیازها

تنظیمات رویدادهای سفارشی را تکمیل کنید.

درخواست تبلیغ بومی

وقتی به ردیف رویداد سفارشی در زنجیره میانجی آبشاری (waterfall mediation chain) می‌رسید، متد loadNativeAd() بر اساس نام کلاسی که هنگام ایجاد یک رویداد سفارشی ارائه کرده‌اید، فراخوانی می‌شود. در این حالت، آن متد در SampleCustomEvent قرار دارد که سپس متد loadNativeAd() را در SampleNativeCustomEventLoader فراخوانی می‌کند.

برای درخواست یک تبلیغ native، کلاسی ایجاد یا اصلاح کنید که Adapter برای پیاده‌سازی loadNativeAd() به ارث می‌برد. اگر کلاسی که Adapter به ارث می‌برد از قبل وجود دارد، loadNativeAd() در آنجا پیاده‌سازی کنید. علاوه بر این، یک کلاس جدید برای پیاده‌سازی UnifiedNativeAdMapper ایجاد کنید.

در مثال رویداد سفارشی ما، SampleCustomEvent کلاس Adapter ارث‌بری می‌کند و سپس آن را به SampleNativeCustomEventLoader واگذار می‌کند.

جاوا

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 .

• دریافت و گزارش فراخوانی‌های رویداد تبلیغاتی به GMA Next Gen SDK.

پارامتر اختیاری تعریف شده در رابط کاربری AdMob در پیکربندی تبلیغات گنجانده شده است. این پارامتر از طریق adConfiguration.getServerParameters().getString(MediationConfiguration.CUSTOM_EVENT_SERVER_PARAMETER_FIELD) قابل دسترسی است. این پارامتر معمولاً یک شناسه واحد تبلیغاتی است که یک SDK شبکه تبلیغاتی هنگام نمونه‌سازی یک شیء تبلیغاتی به آن نیاز دارد.

جاوا

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 شخص ثالثی که آداپتور شما پیاده‌سازی می‌کند، پیاده‌سازی می‌شوند. برای این مثال، Sample SDK دارای یک SampleAdListener با فراخوانی‌های مربوطه است:

جاوا

@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 های مختلف فرمت های منحصر به فرد خود را برای تبلیغات بومی دارند. به عنوان مثال، ممکن است یکی از آنها اشیاء حاوی فیلد "عنوان" را برگرداند، در حالی که دیگری ممکن است "عنوان" داشته باشد. علاوه بر این، روش های مورد استفاده برای ردیابی نمایش ها و پردازش کلیک ها می تواند از یک SDK به SDK دیگر متفاوت باشد.

UnifiedNativeAdMapper مسئول تطبیق این تفاوت‌ها و تطبیق شیء تبلیغ بومی SDK واسطه‌ای برای مطابقت با رابط کاربری مورد انتظار GMA Next Gen SDK است. رویدادهای سفارشی باید این کلاس را گسترش دهند تا نگاشتگرهای خاص خود را متناسب با SDK واسطه‌ای خود ایجاد کنند. در اینجا یک نگاشتگر تبلیغ نمونه از پروژه رویداد سفارشی نمونه ما آمده است:

جاوا

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.
  }
}

اکنون نگاهی دقیق‌تر به کد سازنده می‌اندازیم.

ارجاعی به شیء تبلیغ بومی واسطه‌شده را نگه دارید

سازنده پارامتر SampleNativeAd ، کلاس تبلیغات بومی که توسط Sample SDK برای تبلیغات بومی خود استفاده می‌شود را می‌پذیرد. نگاشت‌کننده به یک مرجع به تبلیغ واسطه نیاز دارد تا بتواند رویدادهای کلیک و نمایش را ارسال کند. SampleNativeAd به عنوان یک متغیر محلی ذخیره می‌شود.

تنظیم ویژگی‌های دارایی نگاشت شده

سازنده از شیء SampleNativeAd برای پر کردن دارایی‌ها در UnifiedNativeAdMapper استفاده می‌کند.

این قطعه کد، داده‌های قیمت تبلیغ واسطه‌ای را دریافت کرده و از آن برای تنظیم قیمت نقشه‌کش استفاده می‌کند:

جاوا

if (sampleAd.getPrice() != null) {
    NumberFormat formatter = NumberFormat.getCurrencyInstance();
    String priceString = formatter.format(sampleAd.getPrice());
    setPrice(priceString);
}

در این مثال، تبلیغ واسطه‌ای قیمت را به صورت double ذخیره می‌کند، در حالی که AdMob از یک String برای همان دارایی استفاده می‌کند. نگاشت‌کننده مسئول مدیریت این نوع تبدیل‌ها است.

دارایی‌های تصویر نقشه

نگاشت دارایی‌های تصویری پیچیده‌تر از نگاشت انواع داده مانند double یا String است. تصاویر ممکن است به صورت خودکار دانلود شوند یا به عنوان مقادیر URL بازگردانده شوند. مقیاس پیکسل به dpi آنها نیز می‌تواند متفاوت باشد.

برای کمک به شما در مدیریت این جزئیات، GMA Next Gen SDK کلاس NativeAd.Image را ارائه می‌دهد. تقریباً همانطور که برای نگاشت یک تبلیغ بومی واسطه‌ای نیاز به ایجاد یک زیرکلاس از UnifiedNativeAdMapper دارید، هنگام نگاشت دارایی‌های تصویری نیز باید یک زیرکلاس از NativeAd.Image ایجاد کنید.

در اینجا مثالی برای کلاس SampleNativeMappedImage مربوط به رویداد سفارشی آورده شده است:

جاوا

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 از کلاس تصویر نگاشت‌شده‌ی خود در این خط برای تنظیم تصویر آیکون نگاشت‌کننده استفاده می‌کند:

جاوا

setIcon(new SampleNativeMappedImage(ad.getAppIcon(), ad.getAppIconUri(),
    SampleCustomEvent.SAMPLE_SDK_IMAGE_SCALE));

فیلدها را به بسته اضافی اضافه کنید

برخی از SDK های واسطه، دارایی‌های اضافی فراتر از آنچه در قالب تبلیغات بومی AdMob وجود دارد، ارائه می‌دهند. کلاس UnifiedNativeAdMapper شامل یک متد setExtras() است که برای انتقال این دارایی‌ها به ناشران استفاده می‌شود. SampleNativeAdMapper از این برای دارایی "درجه جذابیت" Sample SDK استفاده می‌کند:

جاوا

Bundle extras = new Bundle();
extras.putString(SampleCustomEvent.DEGREE_OF_AWESOMENESS, ad.getDegreeOfAwesomeness());
this.setExtras(extras);

ناشران می‌توانند داده‌ها را با استفاده از متد getExtras() از کلاس NativeAd بازیابی کنند.

انتخاب‌های تبلیغاتی

رویداد سفارشی شما مسئول ارائه یک آیکون AdChoices با استفاده از متد setAdChoicesContent() در UnifiedNativeAdMapper است. در اینجا قطعه کدی از SampleNativeAdMapper آمده است که نحوه ارائه آیکون AdChoices را نشان می‌دهد:

جاوا

public SampleNativeAdMapper(SampleNativeAd ad) {
    ...
    setAdChoicesContent(sampleAd.getInformationIcon());
}

رویدادهای نمایش و کلیک

هم GMA Next Gen SDK و هم SDK واسطه‌ای باید بدانند که چه زمانی یک نمایش یا کلیک رخ می‌دهد، اما فقط یک SDK باید این رویدادها را ردیابی کند. بسته به اینکه SDK واسطه‌ای از ردیابی نمایش‌ها و کلیک‌ها به تنهایی پشتیبانی می‌کند یا خیر، دو رویکرد متفاوت وجود دارد که رویدادهای سفارشی می‌توانند از آنها استفاده کنند.

پیگیری کلیک‌ها و نمایش‌ها با GMA Next Gen SDK

اگر SDK واسطه، ردیابی نمایش و کلیک خود را انجام ندهد، اما متدهایی برای ثبت کلیک‌ها و نمایش‌ها ارائه دهد، GMA Next Gen SDK می‌تواند این رویدادها را ردیابی کرده و به آداپتور اطلاع دهد. کلاس UnifiedNativeAdMapper شامل دو متد است: recordImpression() و handleClick() که رویدادهای سفارشی می‌توانند برای فراخوانی متد مربوطه در شیء تبلیغ بومی واسطه، پیاده‌سازی کنند:

جاوا

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

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

از آنجا که SampleNativeAdMapper ارجاعی به شیء تبلیغ بومی Sample SDK دارد، می‌تواند متد مناسب را روی آن شیء فراخوانی کند تا یک کلیک یا نمایش را گزارش دهد. توجه داشته باشید که متد handleClick() یک پارامتر واحد می‌گیرد: شیء View مربوط به دارایی تبلیغ بومی که کلیک را دریافت کرده است.

کلیک‌ها و نمایش‌ها را با SDK واسطه ردیابی کنید

برخی از SDK های واسطه ممکن است ترجیح دهند کلیک‌ها و نمایش‌ها را به تنهایی ردیابی کنند. در این صورت، شما باید با انجام دو فراخوانی زیر در سازنده‌ی UnifiedNativeAdMapper خود، ردیابی پیش‌فرض کلیک و نمایش را لغو کنید:

جاوا

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

رویدادهای سفارشی که ردیابی کلیک و نمایش را لغو می‌کنند، ملزم به گزارش رویدادهای onAdClicked() و onAdImpression() به SDK تبلیغات موبایلی گوگل هستند.

برای ردیابی نمایش‌ها و کلیک‌ها، SDK واسطه احتمالاً برای فعال کردن ردیابی نیاز به دسترسی به نماها دارد. رویداد سفارشی باید متد trackViews() را نادیده بگیرد و از آن برای ارسال نمای تبلیغ بومی به SDK واسطه برای ردیابی استفاده کند. SDK نمونه از پروژه نمونه رویداد سفارشی ما (که قطعه کدهای این راهنما از آن گرفته شده است) از این رویکرد استفاده نمی‌کند؛ اما اگر استفاده می‌کرد، کد رویداد سفارشی چیزی شبیه به این می‌بود:

جاوا

@Override
public void trackViews(View containerView,
    Map<String, View> clickableAssetViews,
    Map<String, View> nonClickableAssetViews) {
  sampleAd.setNativeAdViewForTracking(containerView);
}

اگر SDK واسطه از ردیابی دارایی‌های منفرد پشتیبانی کند، می‌تواند درون clickableAssetViews بررسی کند تا ببیند کدام نماها باید قابل کلیک شوند. این نقشه با نام یک دارایی در NativeAdAssetNames کلیدگذاری شده است. UnifiedNativeAdMapper یک متد untrackView() متناظر ارائه می‌دهد که رویدادهای سفارشی می‌توانند آن را لغو کنند تا هرگونه ارجاع به نما را آزاد کرده و آن را از شیء تبلیغ بومی جدا کنند.

رویدادهای میانجیگری را به GMA Next Gen SDK ارسال کنید

شما می‌توانید تمام فراخوانی‌های برگشتی که میانجیگری پشتیبانی می‌کند را در مستندات MediationNativeAdCallback بیابید.

مهم است که رویداد سفارشی شما تا حد امکان این فراخوانی‌های برگشتی را ارسال کند، به طوری که برنامه شما این رویدادهای معادل را از GMA Next Gen SDK دریافت کند. در اینجا مثالی از استفاده از فراخوانی‌های برگشتی آورده شده است:

این پیاده‌سازی رویدادهای سفارشی برای تبلیغات بومی را تکمیل می‌کند. مثال کامل در GitHub موجود است.