راه‌اندازی آگهی‌های برنمایی

پلاتفرم را انتخاب کنید: Android iOS Unity Flutter Android (Legacy)

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

این راهنما بار کردن آگهی برنمای تطبیقی لنگرشده در برنامه Android را پوشش می‌دهد.

پیش‌نیازها

همیشه با آگهی‌های آزمایشی آزمایش کنید

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

آسان‌ترین راه برای بار کردن آگهی‌های آزمایشی استفاده از شناسه واحد آگهی آزمایشی اختصاصی ما برای برنمای Android است:

/21775744923/example/adaptive-banner

این واحد تبلیغات به‌طور ویژه پیکربندی شده است تا برای هر درخواست، آگهی‌های آزمایشی برگرداند و می‌توانید از آن در برنامه‌های خودتان هنگام کدنویسی، آزمایش، و اشکال‌زدایی استفاده کنید. فقط مطمئن شوید که قبل‌از انتشار برنامه، آن را با شناسه واحد آگهی خودتان جایگزین کنید.

برای اطلاعات بیشتر درباره نحوه عملکرد آگهی‌های آزمایشی Google Mobile Ads SDK (Legacy)، به فعال کردن آگهی‌های آزمایشی مراجعه کنید.

تعریف نمای آگهی

چیدمان XML

نمایی به فایل XML چیدمانتان اضافه کنید تا به‌عنوان محفظه برای آگهی برنمای تطبیقی لنگرانداخته شما عمل کند:

<!-- Ad view container that fills the width of the screen and adjusts its
    height to the content of the ad. -->
<FrameLayout
        android:id="@+id/ad_view_container"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_centerInParent="true"
        android:layout_alignParentBottom="true" />

Jetpack Compose

  1. پوشه JetpackCompose Utilities را اضافه کنید. این پوشه شامل کمک‌کننده‌هایی برای ترکیب‌بندی دارایی‌ها و شیء AdView است.

  2. نوشتن AdView:


// Place the ad view at the bottom of the screen.
Column(modifier = modifier.fillMaxSize(), verticalArrangement = Arrangement.Bottom) {
  Box(modifier = modifier.fillMaxWidth()) { AdManagerBannerAd(adView, modifier) }
}

اندازه آگهی را تنظیم کنید

برنماهای تطبیقی بزرگ قالب بزرگ‌تری را ارائه می‌کنند که برای چیدمان‌های بدون پیمایش طراحی شده است. در مقایسه با برنماهای تطبیقی ثابت استاندارد، این برنماها اجازه می‌دهند حداکثر ارتفاع بلندتری داشته باشند، تا ۲۰٪ ارتفاع صفحه، و بین ۵۰ تا ۱۵۰dp. این فضای افزایش‌یافته برای محتوای ویدیویی بهینه‌سازی شده است.

AdSize را روی نوع برنمای تطبیقی لنگرانداخته با عرض مشخص تنظیم کنید:

جاوا


// Request an anchored adaptive banner with a width of 360.
adView.setAdSize(AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(this, 360));

Kotlin


// Request a large anchored adaptive banner with a width of 360.
adView.setAdSize(AdSize.getLargeAnchoredAdaptiveBannerAdSize(this, 360))

Jetpack Compose


// Set a large anchored adaptive banner ad size with a given width.
val adSize = AdSize.getLargeAnchoredAdaptiveBannerAdSize(LocalContext.current, 360)
adView.setAdSize(adSize)

اندازه آگهی را کوچک‌تر یا مساوی اندازه صفحه‌نمایش دستگاه تنظیم کنید. برای تعیین حداکثر اندازه صفحه‌نمایش، از Resources.getDisplayMetrics روش استفاده کنید. ابعاد شیء AdSize از پیکسل‌های مستقل از تراکم (dp) استفاده می‌کند. هنگام مقایسه، اندازه صفحه را از پیکسل به dp تبدیل کنید. برای جزئیات مربوط به محدودیت‌های اندازه، به عیب‌یابی ظهورهای پرنشده در Ad Manager مراجعه کنید.

‫AdManagerAdView را به چیدمان اضافه کنید

بااستفاده از اندازه آگهی، AdManagerAdView ایجاد کنید تا به چیدمان برنامه‌تان اضافه شود:

جاوا


// Create a new ad view.
adView = new AdManagerAdView(this);
adView.setAdUnitId(AD_UNIT);
// Request an anchored adaptive banner with a width of 360.
adView.setAdSize(AdSize.getCurrentOrientationAnchoredAdaptiveBannerAdSize(this, 360));

// Replace ad container with new ad view.
adContainerView.removeAllViews();
adContainerView.addView(adView);

Kotlin


// Create a new ad view.
val adView = AdManagerAdView(this)
adView.adUnitId = AD_UNIT_ID
// Request a large anchored adaptive banner with a width of 360.
adView.setAdSize(AdSize.getLargeAnchoredAdaptiveBannerAdSize(this, 360))
this.adView = adView

// Replace ad container with new ad view.
binding.adViewContainer.removeAllViews()
binding.adViewContainer.addView(adView)

Jetpack Compose


val adView = remember { AdManagerAdView(context) }

// Setup and load the adview.
// Set the unique ID for this specific ad unit.
adView.adUnitId = ADMANAGER_ADAPTIVE_BANNER_AD_UNIT_ID

// Set a large anchored adaptive banner ad size with a given width.
val adSize = AdSize.getLargeAnchoredAdaptiveBannerAdSize(LocalContext.current, 360)
adView.setAdSize(adSize)

// Place the ad view at the bottom of the screen.
Column(modifier = modifier.fillMaxSize(), verticalArrangement = Arrangement.Bottom) {
  Box(modifier = modifier.fillMaxWidth()) { AdManagerBannerAd(adView, modifier) }
}

بار کردن آگهی

مثال زیر یک آگهی برنمای تطبیقی لنگرانداخته با عرض ۳۶۰ را در یک شیء AdManagerAdView بار می‌کند:

جاوا

AdManagerAdRequest adRequest = new AdManagerAdRequest.Builder().build();
adView.loadAd(adRequest);

Kotlin

val adRequest = AdManagerAdRequest.Builder().build()
adView.loadAd(adRequest)

بازآوری آگهی

اگر واحد آگهی‌تان را برای بازآوری پیکربندی کرده‌اید، وقتی آگهی بار نمی‌شود، لازم نیست آگهی دیگری درخواست کنید. ‫Google Mobile Ads SDK (Legacy) از هر نرخ بازآوری که در واسط کاربر Ad Manager مشخص کرده‌اید پیروی می‌کند. اگر بازآوری را فعال نکرده‌اید، درخواست جدیدی صادر کنید. برای جزئیات بیشتر درباره بازآوری واحد آگهی، مانند تنظیم نرخ بازآوری، به نرخ بازآوری برای آگهی‌ها در برنامه‌های تلفن همراه مراجعه کنید.

واگذار کردن منبع آگهی

وقتی استفاده از آگهی برنمایی تمام شد، می‌توانید منابع آگهی برنمایی را آزاد کنید.

برای آزاد کردن منبع آگهی، آگهی را از سلسله‌مراتب نما بردارید و همه ارجاع‌های آن را رها کنید:

جاوا

public void destroyBanner() {
  // Remove banner from view hierarchy.
  if (adView != null) {
    View parentView = (View) adView.getParent();
    if (parentView instanceof ViewGroup) {
      ((ViewGroup) parentView).removeView(adView);
    }

    // Destroy the banner ad resources.
    adView.destroy();
  }

  // Drop reference to the banner ad.
  adView = null;
}

Kotlin

fun destroyBanner() {
  // Remove banner from view hierarchy.
  val parentView = adView?.parent
  if (parentView is ViewGroup) {
    parentView.removeView(adView)
  }

  // Destroy the banner ad resources.
  adView?.destroy()

  // Drop reference to the banner ad.
  adView = null
}

Jetpack Compose

DisposableEffect(Unit) {
  // Destroy the AdView to prevent memory leaks when the screen is disposed.
  onDispose { adView.destroy() }
}

رویدادهای آگهی

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

جاوا

if (adView != null) {
  adView.setAdListener(
      new AdListener() {
        @Override
        public void onAdClicked() {
          // Code to be executed when the user clicks on an ad.
        }

        @Override
        public void onAdClosed() {
          // Code to be executed when the user is about to return
          // to the app after tapping on an ad.
        }

        @Override
        public void onAdFailedToLoad(@NonNull LoadAdError adError) {
          // Code to be executed when an ad request fails.
        }

        @Override
        public void onAdImpression() {
          // Code to be executed when an impression is recorded
          // for an ad.
        }

        @Override
        public void onAdLoaded() {
          // Code to be executed when an ad finishes loading.
        }

        @Override
        public void onAdOpened() {
          // Code to be executed when an ad opens an overlay that
          // covers the screen.
        }
      });
}

Kotlin

adView?.adListener =
  object : AdListener() {
    override fun onAdClicked() {
      // Code to be executed when the user clicks on an ad.
    }

    override fun onAdClosed() {
      // Code to be executed when the user is about to return
      // to the app after tapping on an ad.
    }

    override fun onAdFailedToLoad(adError: LoadAdError) {
      // Code to be executed when an ad request fails.
    }

    override fun onAdImpression() {
      // Code to be executed when an impression is recorded
      // for an ad.
    }

    override fun onAdLoaded() {
      // Code to be executed when an ad finishes loading.
    }

    override fun onAdOpened() {
      // Code to be executed when an ad opens an overlay that
      // covers the screen.
    }
  }

هریک از روش‌های قابل‌لغو در AdListener با رویدادی در چرخه عمر آگهی مطابقت دارد.

روش‌های قابل‌لغو
onAdClicked() وقتی کلیکی برای آگهی ثبت می‌شود، روش onAdClicked() فراخوانی می‌شود.
onAdClosed() وقتی کاربر پس‌از مشاهده نشانی وب مقصد آگهی به برنامه برمی‌گردد، روش onAdClosed() فراخوانی می‌شود. برنامه شما می‌تواند از آن برای ازسر گرفتن فعالیت‌های تعلیق‌شده یا انجام هر کار دیگری که برای آماده شدن برای تعامل لازم است استفاده کند.
onAdFailedToLoad() روش onAdFailedToLoad() تنها روشی است که شامل پارامتر می‌شود. پارامتر خطای نوع LoadAdError خطای رخ‌داده را شرح می‌دهد. برای اطلاعات بیشتر، به مستندات اشکال‌زدایی خطاهای بار کردن آگهی مراجعه کنید.
onAdImpression() وقتی ظهوری برای آگهی ثبت می‌شود، روش onAdImpression() فراخوانی می‌شود.
onAdLoaded() وقتی بار کردن آگهی تمام می‌شود، روش onAdLoaded() اجرا می‌شود. اگر می‌خواهید افزودن AdManagerAdView به فعالیت یا قطعه را تا زمانی که مطمئن شوید آگهی بار خواهد شد به‌تأخیر بیندازید، برای مثال، می‌توانید این کار را در اینجا انجام دهید.
onAdOpened() وقتی آگهی هم‌پوشانی‌ای را باز می‌کند که صفحه‌نمایش را می‌پوشاند، روش onAdOpened() فراخوانده می‌شود.

شتاب سخت‌افزاری برای آگهی‌های ویدیویی

برای اینکه آگهی‌های ویدیویی با موفقیت در نماهای آگهی برنمای شما نشان داده شوند، شتاب‌دهی سخت‌افزاری باید فعال باشد.

شتاب سخت‌افزاری به‌طور پیش‌فرض فعال است، اما برخی‌از برنامه‌ها ممکن است آن را غیرفعال کنند. اگر این مورد درباره برنامه‌تان صدق می‌کند، توصیه می‌کنیم شتاب سخت‌افزاری را برای کلاس‌های Activity که از آگهی استفاده می‌کنند فعال کنید.

فعال کردن شتاب سخت‌افزاری

اگر برنامه‌تان با روشن بودن شتاب سخت‌افزاری به‌طور سراسری به‌درستی رفتار نمی‌کند، می‌توانید آن را برای فعالیت‌های جداگانه نیز کنترل کنید. برای فعال یا غیرفعال کردن شتاب سخت‌افزاری، می‌توانید از ویژگی android:hardwareAccelerated برای عناصر <application> و <activity> در AndroidManifest.xml استفاده کنید. مثال زیر شتاب سخت‌افزاری را برای کل برنامه فعال می‌کند اما آن را برای یک فعالیت غیرفعال می‌کند:

<application android:hardwareAccelerated="true">
    <!-- For activities that use ads, hardwareAcceleration should be true. -->
    <activity android:hardwareAccelerated="true" />
    <!-- For activities that don't use ads, hardwareAcceleration can be false. -->
    <activity android:hardwareAccelerated="false" />
</application>

برای کسب اطلاعات بیشتر درباره گزینه‌های کنترل شتاب سخت‌افزاری، به راهنمای شتاب سخت‌افزاری مراجعه کنید. توجه داشته باشید که اگر فعالیت غیرفعال باشد، بازدیدهای آگهی فردی نمی‌تواند برای شتاب سخت‌افزاری فعال شود، بنابراین خود فعالیت باید شتاب سخت‌افزاری فعال داشته باشد.

شمارش دستی ظهور

شمارش دستی ظهور فقط با پویش‌های داخلی و فروش مستقیم که دارای طرح‌آگهی‌های ترافیک‌گرفته مستقیم در Ad Manager هستند سازگار است. نباید برای آگهی‌های شبکه‌های طرف سوم یا جای خالی استفاده شود. برای جزئیات بیشتر، شمارش ظهورها و کلیک‌ها را ببینید.

اگر شرایط ویژه‌ای برای زمان ثبت ظهور دارید، می‌توانید پینگ‌های ظهور را به‌صورت دستی به Ad Manager ارسال کنید:

جاوا

if (adManagerAdView != null) {
  adManagerAdView.setManualImpressionsEnabled(true);
}

Kotlin

adManagerAdView?.setManualImpressionsEnabled(true)

وقتی تشخیص دادید که آگهی باموفقیت برگردانده شده و روی صفحه است، می‌توانید ظهور را به‌صورت دستی ثبت کنید:

جاوا

if (adManagerAdView != null) {
  adManagerAdView.recordManualImpression();
}

Kotlin

adManagerAdView?.recordManualImpression()

رویدادهای برنامه

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

می‌توانید بااستفاده از AppEventListener به رویدادهای خاص برنامه Ad Manager گوش دهید. این رویدادها ممکن است در هر زمانی درطول چرخه حیات آگهی رخ دهند، حتی قبل‌از اینکه onAdLoaded() فراخوانی شود.

‫AppEventListener را در AdManagerAdView تنظیم کنید:

جاوا

if (adManagerAdView != null) {
  adManagerAdView.setAppEventListener(this);
}

Kotlin

adManagerAdView?.appEventListener = this

در اینجا مثالی آورده شده است که نشان می‌دهد چگونه رنگ پس‌زمینه برنامه خود را بسته به رویداد برنامه با نام رنگ تغییر دهید:

جاوا

@Override
public void onAppEvent(@NonNull String name, @NonNull String info) {
  if (name.equals("color")) {
    switch (info) {
      case "green":
        // Set background color to green.
        break;
      case "blue":
        // Set background color to blue.
        break;
      default:
        // Set background color to black.
        break;
    }
  }
}

Kotlin

override fun onAppEvent(name: String, info: String) {
  if (name == "color") {
    when (info) {
      "green" -> {
        // Set background color to green.
      }
      "blue" -> {
        // Set background color to blue.
      }
      else -> {
        // Set background color to black.
      }
    }
  }
}

و در اینجا طرح آگهی مربوطه را می‌بینید که پیام‌های رویداد برنامه رنگ را به «شنونده» ارسال می‌کند:

<html>
<head>
  <script src="//www.gstatic.com/afma/api/v1/google_mobile_app_ads.js"></script>
  <script>
    document.addEventListener("DOMContentLoaded", function() {
      // Send a color=green event when ad loads.
      admob.events.dispatchAppEvent("color", "green");

      document.getElementById("ad").addEventListener("click", function() {
        // Send a color=blue event when ad is clicked.
        admob.events.dispatchAppEvent("color", "blue");
      });
    });
  </script>
  <style>
    #ad {
      width: 320px;
      height: 50px;
      top: 0px;
      left: 0px;
      font-size: 24pt;
      font-weight: bold;
      position: absolute;
      background: black;
      color: white;
      text-align: center;
    }
  </style>
</head>
<body>
  <div id="ad">Carpe diem!</div>
</body>
</html>

برای پیاده‌سازی رویدادهای برنامه در برنامه نمایشی API، به نمونه «رویدادهای برنامه Ad Manager» مراجعه کنید.

Java Kotlin JetpackCompose

مراحل بعدی

برنماهای جمع‌شدنی

آگهی‌های برنمای جمع‌شدنی آگهی‌های برنمایی هستند که در ابتدا به‌عنوان رونهاد بزرگ‌تری ارائه می‌شوند و دکمه‌ای برای جمع کردن آگهی به اندازه کوچک‌تر دارند. برای بهینه‌سازی بیشتر عملکردتان، از آن استفاده کنید. برای جزئیات بیشتر، آگهی‌های برنمای جمع‌شدنی را ببینید.

برنماهای تطبیقی درون‌خطی

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

کاوش کردن موضوعات دیگر