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

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

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

پیش‌نیازها

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

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

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

/21775744923/example/adaptive-banner

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

برای اطلاعات بیشتر درباره نحوه عملکرد آگهی‌های آزمایشی 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 را در «واسط کاربر نوشتن» بگنجانید تا 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")
        }
      },
    )
  }
}

بازآوری آگهی

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

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

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

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

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() } }

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

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

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);
        }
      });
}

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

اگر از بازآوری خودکار برای آگهی‌های برنمایی استفاده می‌کنید، 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 را نشان می‌دهد بارگیری و اجرا کنید.