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

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

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

برای اطلاعات بیشتر، راهنمای آگهی در صفحه باز شدن برنامه را ببینید.

این راهنما نحوه ادغام آگهی‌های باز شدن برنامه را در برنامه Android توضیح می‌دهد.

قبل‌از شروع

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

  • GMA Next-Gen SDK را راه‌اندازی کنید.
  • از شناسه واحد آگهی آزمایشی در صفحه باز شدن برنامه ca-app-pub-3940256099942544/9257395921 استفاده کنید.
    • هنگام ساختن و آزمایش کردن برنامه‌تان، مطمئن شوید که از آگهی‌های آزمایشی به‌جای آگهی‌های زنده و تولیدی استفاده می‌کنید. اگر از شناسه واحد آگهی آزمایشی استفاده نکنید، Google می‌تواند حسابتان را تعلیق کند.
    • قبل‌از انتشار برنامه‌تان، این شناسه را با شناسه واحد آگهی‌تان جایگزین کنید.
    • برای جزئیات درباره آگهی‌های آزمایشی GMA Next-Gen SDK، به فعال کردن آگهی‌های آزمایشی مراجعه کنید.

آشنایی با پیش‌بارگیری آگهی (نسخه بتا)

پیش‌بار کردن آگهی در GMA Next-Gen SDK بار کردن و ذخیره آگهی در حافظه نهان را خودکار می‌کند.

پیش‌بارگیری آگهی مزایای زیر را ارائه می‌دهد:

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

شروع پیش‌بارگیری آگهی

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

مثال زیر نحوه شروع پیش‌بارگیری آگهی‌ها را نشان می‌دهد:

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
AppOpenAdPreloader.start(adUnitId, preloadConfig)

جاوا

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
AppOpenAdPreloader.start(adUnitId, preloadConfig);

AD_UNIT_ID را با شناسه واحد آگهی‌تان جایگزین کنید.

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

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

دریافت و نمایش آگهی پیش‌بارشده

قبل‌از نمایش آگهی، روش pollAd را فراخوانی کنید. شیء آگهی پیش‌بارشده را ذخیره نکنید. وقتی روش pollAd را فراخوانی می‌کنید، GMA Next-Gen SDK آگهی دردسترسی را بازیابی می‌کند و به‌طور خودکار آگهی بعدی را در پس‌زمینه پیش‌بارگیری می‌کند. اگر آگهی‌ای دردسترس نباشد، GMA Next-Gen SDK هیچ آگهی‌ای برنمی‌گرداند.

وقتی شیء آگهی دردسترس دارید، روش show را برای نمایش آگهی فراخوانی کنید. مثال زیر نحوه بازیابی و نمایش آگهی پیش‌بارشده را نشان می‌دهد:

Kotlin

private fun pollAndShowAd(activity: Activity, adUnitId: String) {
  // Polling returns the next available ad and loads another ad in the background.
  val ad = AppOpenAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "App open ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "App open ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : AppOpenAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "App open ad recorded an impression.")
      }
    }
  ad.show(activity)
}

جاوا

private void pollAndShowAd(Activity activity, String adUnitId) {
  // Polling returns the next available ad and loads another ad in the background.
  AppOpenAd ad = AppOpenAdPreloader.pollAd(adUnitId);

  // Interact with the ad object as needed.
  if (ad == null) {
    Log.e(TAG, "App open ad is not available.");
    return;
  }

  Log.d(TAG, "App open ad response info: " + ad.getResponseInfo());
  ad.setAdEventCallback(
      new AppOpenAdEventCallback() {
        @Override
        public void onAdImpression() {
          Log.d(TAG, "App open ad recorded an impression.");
        }
      });

  // Show the ad.
  ad.show(activity);
}

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

گوش دادن به رویدادهای آگهی

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

Kotlin

private fun listenToAdEvents() {
  // Listen for ad events.
  val ad = appOpenAd
  if (ad == null) {
    Log.e(TAG, "App open ad is not ready yet.")
    return
  }

  ad.adEventCallback =
    object : AppOpenAdEventCallback {
      override fun onAdShowedFullScreenContent() {
        // App open ad did show.
      }

      override fun onAdDismissedFullScreenContent() {
        // App open ad did dismiss.
        appOpenAd = null
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError
      ) {
        // App open ad failed to show.
        Log.e(TAG, "App open ad failed to show: ${fullScreenContentError.message}")
      }

      override fun onAdImpression() {
        // App open ad did record an impression.
      }

      override fun onAdClicked() {
        // App open ad did record a click.
      }
    }
}

جاوا

private void listenToAdEvents() {
  // Listen for ad events.
  if (appOpenAd == null) {
    Log.e(TAG, "App open ad is not ready yet.");
    return;
  }

  appOpenAd.setAdEventCallback(
      new AppOpenAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // App open ad did show.
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          // App open ad did dismiss.
          appOpenAd = null;
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            @NonNull FullScreenContentError fullScreenContentError) {
          // App open ad failed to show.
          Log.e(TAG, "App open ad failed to show: " + fullScreenContentError.getMessage());
        }

        @Override
        public void onAdImpression() {
          // App open ad did record an impression.
        }

        @Override
        public void onAdClicked() {
          // App open ad did record a click.
        }
      });
}

اختیاری: گوش دادن به رویدادهای پیش‌بارگیری

وقتی پیش‌بار کردن آگهی‌ها را شروع می‌کنید، برای رویدادهای پیش‌بار کردن ثبت‌نام کنید تا وقتی آگهی‌ها با موفقیت پیش‌بار شدند، پیش‌بار نشدند، یا حافظه نهان آگهی تمام شد، مطلع شوید.

مثال زیر نحوه ثبت‌نام برای رویدادهای پیش‌بارگیری آگهی را نشان می‌دهد:

Kotlin

val preloadCallback =
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(TAG, "App open preload ad $preloadId failed to load with error: ${adError.message}")
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "App open preload ad $preloadId is not available")
    }

    override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo) {
      Log.i(TAG, "App open preload ad $preloadId is available")
    }
  }
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
AppOpenAdPreloader.start(adUnitId, preloadConfig, preloadCallback)

جاوا

PreloadCallback preloadCallback =
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(@NonNull String preloadId, @NonNull LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "App open preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
      }

      @Override
      public void onAdsExhausted(@NonNull String preloadId) {
        Log.i(TAG, String.format("App open preload ad %s is not available", preloadId));
      }

      @Override
      public void onAdPreloaded(@NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
        Log.i(TAG, String.format("App open preload ad %s is available", preloadId));
      }
    };
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
AppOpenAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

وقتی آگهی بار نمی‌شود، GMA Next-Gen SDK به‌طور خودکار آگهی‌ها را پیش‌بار می‌کند و درخواست‌های ناموفق برای پیکربندی‌های پیش‌بارشده را دوباره امتحان می‌کند. درخواست‌های بارگیری دستی را در تماس‌های برگشتی ناموفق فراخوانی نکنید. در روش‌های فراخوانی رویداد پیش‌بارکردن، روش‌های pollAd، destroy، یا start را فراخوانی نکنید. فراخوانی این روش‌ها در فراخوانی‌های برگشتی می‌تواند حلقه‌های بارگذاری بازگشتی را فراخوانی کند.

اختیاری: بررسی دردسترس بودن آگهی

اگر لازم است بدانید آگهی دردسترس است یا نه، دردسترس بودن آگهی را بررسی کنید. مثال زیر بررسی می‌کند که آیا آگهی پیش‌بارشده دردسترس است یا نه:

Kotlin

private fun isAdAvailable(adUnitId: String): Boolean {
  return AppOpenAdPreloader.isAdAvailable(adUnitId)
}

جاوا

private boolean isAdAvailable(String adUnitId) {
  return AppOpenAdPreloader.isAdAvailable(adUnitId);
}

اختیاری: اندازه میان‌گیر را تنظیم کنید

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

مثال زیر نحوه تنظیم اندازه میان‌گیر را نشان می‌دهد:

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
AppOpenAdPreloader.start(adUnitId, preloadConfig)

جاوا

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 2);
AppOpenAdPreloader.start(adUnitId, preloadConfig);

حدود حافظه نهان پیش‌بارکردن

GMA Next-Gen SDK محدودیتی را در سطح برنامه برای تعداد کل آگهی‌های پیش‌بارشده در همه واحدهای آگهی و شناسه‌های پیش‌بارشده اعمال می‌کند:

  • محدودیت پیش‌فرض: Google حداکثر شش آگهی پیش‌بارشده را در حافظه نگه می‌دارد. این محدودیت برای همه قالب‌ها و شناسه‌های پیش‌بارگیری مشترک است.
  • توصیه می‌کنیم اندازه میان‌گیر را برای هر شناسه پیش‌بارگیری روی دو نگه دارید.

اختیاری: توقف پیش‌بارگیری آگهی‌ها

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

مثال زیر نحوه توقف پیش‌بارگیری آگهی‌ها را نشان می‌دهد:

Kotlin

private fun stopPreloading(adUnitId: String) {
  // Stops the preloading and destroy preloaded ads.
  AppOpenAdPreloader.destroy(adUnitId)
}

جاوا

private void stopPreloading(String adUnitId) {
  // Stops the preloading and destroy preloaded ads.
  AppOpenAdPreloader.destroy(adUnitId);
}

اختیاری: اطلاعات پاسخ را بخوانید

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

مثال زیر نحوه خواندن اطلاعات پاسخ آگهی پیش‌بارشده بعدی را نشان می‌دهد:

Kotlin

val responseInfo = AppOpenAdPreloader.peekAdResponseInfo(preloadId)
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.")
  return
}

Log.d(TAG, "Peeked ad response ID: ${responseInfo.responseId}")

جاوا

ResponseInfo responseInfo = AppOpenAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

Log.d(TAG, "Peeked ad response ID: " + responseInfo.getResponseId());

مدیریت شروع سرد و صفحه‌های بار کردن

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

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

توصیه‌ها

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

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