این راهنما بار کردن آگهی برنمای تطبیقی لنگرشده در برنامه Android را پوشش میدهد.
پیشنیازها
- Google Mobile Ads SDK (Legacy) را راهاندازی کنید.
- اختیاری: برای نمونه پیادهسازی آگهیهای برنمای، یکی از برنامههای نمونه زیر را انتخاب کنید:
- نمونه آگهیهای برنمای تطبیقی لنگرانداخته Java، Kotlin، یا Jetpack Compose.
- نمونه نمایشی ویژگیهای پیشرفته Java یا Kotlin.
همیشه با آگهیهای آزمایشی آزمایش کنید
هنگام ساختن و آزمایش کردن برنامههایتان، حتماً از آگهیهای آزمایشی استفاده کنید نه آگهیهای زنده و تولیدی. انجام ندادن این کار میتواند منجر به تعلیق حساب شما شود.
آسانترین راه برای بار کردن آگهیهای آزمایشی استفاده از شناسه واحد آگهی آزمایشی اختصاصی ما برای برنمای 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
پوشه JetpackCompose Utilities را اضافه کنید. این پوشه شامل کمککنندههایی برای ترکیببندی داراییها و شیء
AdViewاست.نوشتن
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» مراجعه کنید.
مراحل بعدی
برنماهای جمعشدنی
آگهیهای برنمای جمعشدنی آگهیهای برنمایی هستند که در ابتدا بهعنوان رونهاد بزرگتری ارائه میشوند و دکمهای برای جمع کردن آگهی به اندازه کوچکتر دارند. برای بهینهسازی بیشتر عملکردتان، از آن استفاده کنید. برای جزئیات بیشتر، آگهیهای برنمای جمعشدنی را ببینید.
برنماهای تطبیقی درونخطی
برنماهای تطبیقی درونخطی نسبتبه برنماهای تطبیقی لنگردار بزرگتر و بلندتر هستند. ارتفاع آنها متغیر است و میتواند به اندازه ارتفاع صفحهنمایش دستگاه باشد. برنماهای تطبیقی درونخطی نسبتبه آگهیهای برنمای تطبیقی لنگردار برای برنامههایی که آگهیهای برنما را در محتوای پیمایشی قرار میدهند توصیه میشود. برای جزئیات بیشتر، برنمای تطبیقی درونخط را ببینید.