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

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

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

این راهنما بار کردن آگهی برنمای تطبیقی لنگرشده در برنامه 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 را اضافه کنید. این پوشه شامل کمک‌کننده‌هایی برای ترکیب‌بندی دارایی‌ها و شیء 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)

‫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

مراحل بعدی

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

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

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

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

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