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

انتخاب پلاتفرم: 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.

  • دریافت و گزارش کردن فراخوانی‌های رویداد آگهی به Google Mobile Ads SDK (Legacy).

پارامتر اختیاری تعریف‌شده در AdMob UI در پیکربندی آگهی گنجانده شده است. ازطریق 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 مسئول تطبیق این تفاوت‌ها و سازگار کردن شیء آگهی بومی کیت توسعه نرم‌افزار میانجی‌شده برای مطابقت با رابط موردانتظار Google Mobile Ads SDK (Legacy) است. رویدادهای سفارشی باید این کلاس را گسترش دهند تا نقشه‌برهای خاص خود را برای کیت توسعه نرم‌افزار واسطه‌گری‌شده خود ایجاد کنند. در اینجا یک نگاشت‌گر آگهی نمونه از پروژه رویداد سفارشی نمونه ما آورده شده است:

جاوا

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 ذخیره می‌کند، درحالی‌که AdMob از String برای همان دارایی استفاده می‌کند. نگاشت‌گر مسئول رسیدگی به این نوع تبدیل‌ها است.

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

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

برای کمک به شما در مدیریت این جزئیات، Google Mobile Ads SDK (Legacy) کلاس 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));

افزودن فیلدها به Bundle موارد اضافی

برخی‌از کیت‌های توسعه نرم‌افزار واسطه‌ای دارایی‌های بیشتری فراتر از دارایی‌های موجود در قالب آگهی بومی AdMob ارائه می‌دهند. کلاس 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());
}

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

هم Google Mobile Ads SDK (Legacy) و هم «کیت توسعه نرم‌افزار میانجی‌گری‌شده» باید بدانند که ظهور یا کلیک چه زمانی اتفاق می‌افتد، اما فقط یکی از کیت‌های توسعه نرم‌افزار باید این رویدادها را پیگیری کند. دو رویکرد متفاوت وجود دارد که رویدادهای سفارشی می‌توانند استفاده کنند، بسته به اینکه آیا کیت توسعه نرم‌افزار واسطه از ردیابی ظهورها و کلیک‌ها به‌تنهایی پشتیبانی می‌کند یا نه.

پیگیری کلیک‌ها و ظهورها با Google Mobile Ads SDK (Legacy)

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

جاوا

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

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

چون SampleNativeAdMapper مرجعی به شیء آگهی بومی Sample SDK دارد، می‌تواند روش مناسب را در آن شیء برای گزارش کلیک یا ظهور فراخوانی کند. توجه داشته باشید که روش 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() متناظری را ارائه می‌دهد که رویدادهای سفارشی می‌توانند آن را لغو کنند تا هرگونه ارجاع به نما را منتشر کنند و آن را از شیء آگهی بومی جدا کنند.

رویدادهای واسطه‌گری را به Google Mobile Ads SDK (Legacy) بازارسال کنید

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

مهم است که رویداد سفارشی شما تا حد امکان این پاسخ‌های برگشتی را بازارسال کند تا برنامه شما این رویدادهای معادل را از Google Mobile Ads SDK (Legacy) دریافت کند. در اینجا نمونه‌ای از استفاده از «بازخوان‌ها» آورده شده است:

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