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

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

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

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

پیش‌نیازها

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

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

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

ca-app-pub-3940256099942544/9214589741

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

برای اطلاعات بیشتر درباره نحوه عملکرد آگهی‌های آزمایشی GMA Next-Gen SDK، به فعال کردن آگهی‌های آزمایشی مراجعه کنید.

ایجاد شیء AdView

برای نمایش برنماها، کارهای زیر را انجام دهید:

Kotlin

  1. شیء AdView ایجاد کنید.
  2. شیء AdView را به چیدمان برنامه‌تان اضافه کنید.

مثال زیر شیء AdView را ایجاد می‌کند و به چیدمان برنامه اضافه می‌کند:

private fun createAdView(adViewContainer: FrameLayout, activity: Activity) {
  val adView = AdView(activity)
  adViewContainer.addView(adView)
}

جاوا

  1. شیء AdView ایجاد کنید.
  2. شیء AdView را به چیدمان برنامه‌تان اضافه کنید.

مثال زیر شیء AdView را ایجاد می‌کند و به چیدمان برنامه اضافه می‌کند:

private void createAdView(FrameLayout adViewContainer, Activity activity) {
  AdView adView = new AdView(activity);
  adViewContainer.addView(adView);
}

چیدمان XML

عنصر AdView را به فایل XML چیدمانتان اضافه کنید:

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

  <com.google.android.libraries.ads.mobile.sdk.banner.AdView
      android:id="@+id/adView"
      android:layout_width="wrap_content"
      android:layout_height="wrap_content"
      app:layout_constraintBottom_toBottomOf="parent"
      app:layout_constraintEnd_toEndOf="parent"
      app:layout_constraintStart_toStartOf="parent" />
</androidx.constraintlayout.widget.ConstraintLayout>

Jetpack Compose

  1. یک شیء AdView در داخل بلوک remember ایجاد کنید.
  2. یک عنصر AndroidView را در Compose UI اضافه کنید تا شیء AdView را نمایش دهد:
val context = LocalContext.current
val adView = remember { AdView(context) }

// The AdView is placed at the bottom of the screen.
Column(modifier = modifier.fillMaxSize(), verticalArrangement = Arrangement.Bottom) {
  Box(modifier = modifier.fillMaxWidth()) {
    // Display the ad within an AndroidView.
    AndroidView(modifier = modifier.wrapContentSize(), factory = { adView })
  }
}

بار کردن آگهی

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

Kotlin

private fun loadBannerAd(adView: AdView, activity: Activity) {
  // Get a BannerAdRequest for a 360 wide large anchored adaptive banner ad.
  val adSize = AdSize.getLargeAnchoredAdaptiveBannerAdSize(activity, 360)
  val adRequest = BannerAdRequest.Builder(AD_UNIT_ID, adSize).build()

  adView.loadAd(
    adRequest,
    object : AdLoadCallback<BannerAd> {
      override fun onAdLoaded(ad: BannerAd) {
        Log.d(TAG, "Banner ad loaded.")
      }

      override fun onAdFailedToLoad(adError: LoadAdError) {
        Log.d(TAG, "Banner ad failed to load: $adError")
      }
    },
  )
}

جاوا

private void loadBannerAd(AdView adView, Activity activity) {
  // Get a BannerAdRequest for a 360 wide large anchored adaptive banner ad.
  AdSize adSize = AdSize.getLargeAnchoredAdaptiveBannerAdSize(activity, 360);
  BannerAdRequest adRequest = new BannerAdRequest.Builder(AD_UNIT_ID, adSize).build();

  adView.loadAd(
      adRequest,
      new AdLoadCallback<BannerAd>() {
        @Override
        public void onAdLoaded(@NonNull BannerAd bannerAd) {
          Log.d(TAG, "Banner ad loaded.");
        }

        @Override
        public void onAdFailedToLoad(@NonNull LoadAdError adError) {
          Log.d(TAG, "Banner ad failed to load: " + adError);
        }
      });
}

Jetpack Compose

// Request a large anchored adaptive banner with a width of 360.
val adSize = AdSize.getLargeAnchoredAdaptiveBannerAdSize(context, 360)

// Load the ad when the screen is active.
val isPreviewMode = LocalInspectionMode.current
LaunchedEffect(adSize) {
  if (!isPreviewMode) {
    val adRequest = BannerAdRequest.Builder(AD_UNIT_ID, adSize).build()
    adView.loadAd(
      adRequest,
      object : AdLoadCallback<BannerAd> {
        override fun onAdLoaded(ad: BannerAd) {
          Log.d(Constant.TAG, "Banner ad loaded.")
        }

        override fun onAdFailedToLoad(adError: LoadAdError) {
          Log.w(Constant.TAG, "Banner ad failed to load: $adError")
        }
      },
    )
  }
}

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

بازآوری آگهی

اگر واحد آگهی‌تان را برای بازآوری پیکربندی کرده‌اید، وقتی آگهی بار نمی‌شود، لازم نیست آگهی دیگری درخواست کنید. GMA Next-Gen SDK به هر نرخ بازآوری که در AdMob UI مشخص کرده‌اید احترام می‌گذارد. اگر بازآوری را فعال نکرده‌اید، درخواست جدیدی صادر کنید. برای جزئیات بیشتر درباره بازآوری واحد آگهی، مانند تنظیم نرخ بازآوری، به استفاده از بازآوری خودکار برای آگهی‌های برنمایی مراجعه کنید.

انتشار منبع آگهی

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

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

Kotlin

private 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
}

جاوا

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

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

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

Jetpack Compose

// Destroy the ad when the screen is disposed.
DisposableEffect(Unit) { onDispose { adView.destroy() } }

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

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

Kotlin

override fun onAdLoaded(ad: BannerAd) {
  ad.adEventCallback =
    object : BannerAdEventCallback {
      override fun onAdImpression() {
        // Banner ad recorded an impression.
        Log.d(TAG, "Banner ad recorded an impression.")
      }

      override fun onAdClicked() {
        // Banner ad recorded a click.
        Log.d(TAG, "Banner ad clicked.")
      }

      override fun onAdShowedFullScreenContent() {
        // Banner ad showed.
        Log.d(TAG, "Banner ad showed full screen content.")
      }

      override fun onAdDismissedFullScreenContent() {
        // Banner ad dismissed.
        Log.d(TAG, "Banner ad dismissed full screen content.")
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError
      ) {
        // Banner ad failed to show.
        Log.w(TAG, "Banner ad failed to show full screen content: $fullScreenContentError")
      }
    }
}

جاوا

@Override
public void onAdLoaded(@NonNull BannerAd bannerAd) {
  bannerAd.setAdEventCallback(
      new BannerAdEventCallback() {
        @Override
        public void onAdImpression() {
          // Banner ad recorded an impression.
          Log.d(TAG, "Banner ad recorded an impression.");
        }

        @Override
        public void onAdClicked() {
          // Banner ad recorded a click.
          Log.d(TAG, "Banner ad clicked.");
        }

        @Override
        public void onAdShowedFullScreenContent() {
          // Banner ad showed.
          Log.d(TAG, "Banner ad showed full screen content.");
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          // Banner ad dismissed.
          Log.d(TAG, "Banner ad dismissed full screen content.");
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            @NonNull FullScreenContentError fullScreenContentError) {
          // Banner ad failed to show.
          Log.w(
              TAG,
              "Banner ad failed to show full screen content: " + fullScreenContentError);
        }
      });
}

میانای BannerAdEventCallback رویدادهای محتوای تمام‌صفحه را به‌صورت زیر مدیریت می‌کند:

  • هم‌پوشانی‌های درون‌برنامه: GMA Next-Gen SDK تماس می‌گیرد onAdShowedFullScreenContent و onAdDismissedFullScreenContent فقط وقتی آگهی برنمایی هم‌پوشانی‌ای را در برنامه‌تان ارائه یا رد می‌کند، مثل آگهی گسترش‌یافته «تعاریف میانای آگهی رسانه‌ای غنی تلفن همراه» (MRAID) یا هم‌پوشانی AdChoices.

  • پیمایش خارجی: وقتی کلیک آگهی به خارج از برنامه‌تان پیمایش می‌کند، مثلاً به مرورگر خارجی یا بازار برنامه، GMA Next-Gen SDK این روش‌ها را فراخوانی نمی‌کند. برای تشخیص اینکه کاربر چه زمانی پس‌از کلیک کردن روی آگهی، برنامه شما را ترک می‌کند یا به آن بازمی‌گردد، رویدادهای چرخه حیات برنامه را در کنار روش onAdClicked گوش دهید.

فراخوانی بازآوری آگهی

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

Kotlin

adView.loadAd(
  adRequest,
  object : AdLoadCallback<BannerAd> {
    override fun onAdLoaded(ad: BannerAd) {
      ad.bannerAdRefreshCallback =
        object : BannerAdRefreshCallback {
          override fun onAdRefreshed() {
            // Banner ad refreshed.
            Log.d(TAG, "Banner ad refreshed.")
          }

          override fun onAdFailedToRefresh(adError: LoadAdError) {
            // Banner ad failed to refresh.
            Log.w(TAG, "Banner ad failed to refresh: $adError")
          }
        }
    }

    override fun onAdFailedToLoad(adError: LoadAdError) {
      // Banner ad failed to load.
      Log.w(TAG, "Banner ad failed to load: $adError")
    }
  },
)

جاوا

adView.loadAd(
    adRequest,
    new AdLoadCallback<BannerAd>() {
      @Override
      public void onAdLoaded(@NonNull BannerAd bannerAd) {
        bannerAd.setBannerAdRefreshCallback(
            new BannerAdRefreshCallback() {
              @Override
              public void onAdRefreshed() {
                // Banner ad refreshed.
                Log.d(TAG, "Banner ad refreshed.");
              }

              @Override
              public void onAdFailedToRefresh(@NonNull LoadAdError adError) {
                // Banner ad failed to refresh.
                Log.w(TAG, "Banner ad failed to refresh: " + adError);
              }
            });
      }

      @Override
      public void onAdFailedToLoad(@NonNull LoadAdError adError) {
        // Banner ad failed to load.
        Log.w(TAG, "Banner ad failed to load: " + adError);
      }
    });

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

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

شتاب سخت‌افزاری به‌طور پیش‌فرض فعال است، اما برخی‌از برنامه‌ها ممکن است آن را غیرفعال کنند. اگر این مورد درباره برنامه‌تان صدق می‌کند، توصیه می‌کنیم شتاب سخت‌افزاری را برای کلاس‌های 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>

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

برنامه نمونه را که نحوه استفاده از GMA Next-Gen SDK را نشان می‌دهد بارگیری و اجرا کنید.