کیت توسعه نرم‌افزاری تبلیغات موبایلی گوگل (Google Mobile Ads SDK) در حالت تعمیر و نگهداری است. برای دریافت آخرین به‌روزرسانی‌ها و ویژگی‌ها، کیت توسعه نرم‌افزاری نسل بعدی GMA را منتقل و راه‌اندازی کنید.

‫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.
دریافت و گزارش کردن فراخوانی‌های رویداد آگهی به 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 را ارائه می‌دهد. In much the same way that you need to create a subclass of UnifiedNativeAdMapper to map a mediated native ad, you should also create a subclass of NativeAd.Image when mapping image assets.

در اینجا مثالی برای کلاس 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

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

جاوا

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 Ads SDK گزارش دهند.

برای ردیابی ظهورها و کلیک‌ها، کیت توسعه نرم‌افزار میانجی احتمالاً برای فعال کردن ردیابی به دسترسی به نماها نیاز دارد. رویداد سفارشی باید روش 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 دردسترس است.

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

پیش‌نیازها

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

جاوا

جاوا

جاوا

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

جاوا

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

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

جاوا

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

جاوا

جاوا

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

جاوا

AdChoices

جاوا

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

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

جاوا

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

جاوا

جاوا

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

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