‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

رویدادهای سفارشی آگهی‌های بومی

انتخاب پلاتفرم: Android iOS Android (قدیمی)

پیش‌نیازها

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

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

وقتی ردیف رویداد سفارشی در زنجیره واسطه‌گری آبشاری فراخوانی می‌شود، متد 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.
درحال دریافت و گزارش کردن برگشتی‌های رویداد آگهی به GMA Next-Gen SDK.

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

جاوا

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 را پیاده‌سازی می‌کند فراخوانده می‌شود.

معمولاً این روش‌ها در داخل برگشت تماس از کیت توسعه نرم‌افزار طرف سوم که آداپتور شما پیاده‌سازی می‌کند، پیاده‌سازی می‌شوند. برای این مثال، «کیت توسعه نرم‌افزار نمونه» دارای 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));
}

آگهی‌های بومی Maps

کیت‌های توسعه نرم‌افزار مختلف قالب‌های منحصربه‌فرد خود را برای آگهی‌های بومی دارند. یکی ممکن است اشیایی را برگرداند که حاوی فیلد «عنوان» هستند، برای مثال، درحالی‌که دیگری ممکن است «عنوان» داشته باشد. علاوه‌براین، روش‌های استفاده‌شده برای پیگیری ظهورها و پردازش کلیک‌ها می‌تواند از یک کیت توسعه نرم‌افزار به کیت توسعه نرم‌افزار دیگر متفاوت باشد.

‫UnifiedNativeAdMapper مسئول تطبیق این تفاوت‌ها و تبدیل کردن شیء آگهی بومی کیت توسعه نرم‌افزار واسطه‌ای برای مطابقت با میانایی است که GMA Next-Gen 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 را می‌پذیرد، کلاس آگهی بومی که «کیت توسعه نرم‌افزار نمونه» برای آگهی‌های بومی خود استفاده می‌کند. نقشه‌بردار به مرجعی برای آگهی واسطه‌ای نیاز دارد تا بتواند رویدادهای کلیک و ظهور را منتقل کند. ‫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 است. تصاویر ممکن است به‌طور خودکار بارگیری شوند یا به‌صورت مقادیر نشانی وب برگردانده شوند. مقیاس‌های پیکسل به نقطه در اینچ آن‌ها نیز می‌تواند متفاوت باشد.

برای کمک به شما در مدیریت این جزئیات، 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));

افزودن فیلدها به «بسته» اضافی

برخی‌از کیت‌های توسعه نرم‌افزار واسطه‌ای دارایی‌های بیشتری فراتر از دارایی‌های موجود در قالب آگهی بومی Ad Manager ارائه می‌دهند. کلاس UnifiedNativeAdMapper شامل روش setExtras() است که برای انتقال این دارایی‌ها به ناشران استفاده می‌شود. ‫SampleNativeAdMapper از این برای دارایی «درجه شگفت‌انگیزی» کیت توسعه نرم‌افزار نمونه استفاده می‌کند:

جاوا

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

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

AdChoices

رویداد سفارشی شما مسئول ارائه نماد «انتخاب‌های تبلیغاتی» بااستفاده از روش setAdChoicesContent() در UnifiedNativeAdMapper است. در اینجا گزیده‌ای از SampleNativeAdMapper نشان داده شده است که نحوه ارائه نماد «انتخاب‌های آگهی» را نشان می‌دهد:

جاوا

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

رویدادهای ظهور و کلیک

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

پیگیری کلیک‌ها و ظهورها با GMA Next-Gen SDK

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

جاوا

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

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

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

پیگیری کلیک‌ها و ظهورها با «کیت توسعه نرم‌افزار میانجی‌گری‌شده»

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

جاوا

setOverrideClickHandling(true);
setOverrideImpressionRecording(true);

رویدادهای سفارشی که ردیابی کلیک و ظهور را ملغی می‌کنند برای گزارش رویدادهای onAdClicked() و onAdImpression() به «کیت توسعه نرم‌افزار تبلیغات Google Mobile» الزامی هستند.

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

جاوا

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

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

رویدادهای واسطه‌گری را به GMA Next-Gen SDK بازارسال کنید

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

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

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

رویدادهای سفارشی آگهی‌های بومی با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

پیش‌نیازها

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

جاوا

جاوا

جاوا

آگهی‌های بومی Maps

جاوا

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

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

جاوا

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

جاوا

جاوا

افزودن فیلدها به «بسته» اضافی

جاوا

AdChoices

جاوا

رویدادهای ظهور و کلیک

پیگیری کلیک‌ها و ظهورها با GMA Next-Gen SDK

جاوا

پیگیری کلیک‌ها و ظهورها با «کیت توسعه نرم‌افزار میانجی‌گری‌شده»

جاوا

جاوا

رویدادهای واسطه‌گری را به GMA Next-Gen SDK بازارسال کنید

رویدادهای سفارشی آگهی‌های بومی