این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

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

پیش نیازها

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

درخواست آگهی بومی

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

برای درخواست یک تبلیغ بومی، کلاسی را ایجاد یا تغییر دهید که 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 .
دریافت و گزارش تماس‌های رویداد تبلیغاتی به Google Mobile Ads SDK.

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

UnifiedNativeAdMapper مسئول تطبیق این تفاوت‌ها و انطباق شیء تبلیغاتی بومی SDK با واسطه برای مطابقت با رابط مورد انتظار Google Mobile Ads 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 ذخیره می کند، در حالی که Ad Manager از یک String برای همان دارایی استفاده می کند. نقشه‌بردار مسئول رسیدگی به این نوع تبدیل‌ها است.

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

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

برای کمک به مدیریت این جزئیات، Google Mobile Ads 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 های واسطه دارایی های اضافی فراتر از دارایی های موجود در قالب تبلیغات بومی Ad Manager هستند. کلاس UnifiedNativeAdMapper شامل یک متد setExtras() است که برای ارسال این دارایی ها به ناشران استفاده می شود. SampleNativeAdMapper از این برای دارایی "درجه عالی" Sample SDK استفاده می کند:

جاوا

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

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

AdChoices

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

جاوا

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() که رویدادهای سفارشی می توانند برای فراخوانی متد مربوطه در شیء تبلیغات داخلی واسطه ای پیاده سازی کنند:

جاوا

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

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

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

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

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

جاوا

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

برای گزارش رویدادهای onAdClicked() و onAdImpression() به Google Mobile Ads 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() متناظر را ارائه می‌کند که رویدادهای سفارشی می‌توانند آن را لغو کنند تا هر گونه ارجاع به view را آزاد کند و آن را از شیء تبلیغاتی اصلی جدا کند.

رویدادهای میانجی را به Google Mobile Ads SDK بازارسال کنید

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

مهم است که رویداد سفارشی شما تا آنجایی که ممکن است این تماس‌های پاسخگو را فوروارد کند تا برنامه شما این رویدادهای مشابه را از Google Mobile Ads SDK دریافت کند. در اینجا مثالی از استفاده از callback آورده شده است:

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