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

پلاتفرم را انتخاب کنید: 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) }
}

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

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

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

مراحل بعدی

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

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

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

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

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