استخدام عملية تهيئة قابلة للإعداد للمحوّل (إصدار أوّلي)

تُهيئ GMA Next-Gen SDK تلقائيًا جميع محوّلات التوسّط المرتبطة بتطبيقك أثناء عملية التهيئة. قد تستغرق عملية إعداد كل محوّل أكثر من 30 ثانية، ما يؤدي إلى وقت استجابة كبير قبل تحميل إعلانك الأول.

لحلّ هذه المشكلة، توفّر AdMob ميزة "إعداد المحوِّل القابل للضبط". تتيح لك هذه الميزة التحكّم في المحوّلات التي يتم إعدادها لمرة الظهور الأولى للإعلان، كما تقلّل من وقت الاستجابة لمرة الظهور هذه.

يتناول هذا الدليل الجوانب التالية من عملية إعداد المحوّلات القابلة للضبط:

المتطلبات الأساسية

  • يمكنك الموافقة على هذه الميزة من خلال إضافة التعليق التوضيحي @ExperimentalApi إلى صفك:

    Kotlin

    @OptIn(ExperimentalApi::class)
    

    جافا

    import androidx.annotation.OptIn;
    // ...
    @OptIn(markerClass = ExperimentalApi.class)
    

إنشاء إعدادات المحوّل

توجّه إعدادات بدء المحوِّل GMA Next-Gen SDK لبدء المحوّلات المطلوبة فقط. يمنع ذلك المحوّلات غير الضرورية من حظر طلب عرض الإعلان الأول، ما يحافظ على موارد الحوسبة ويقلّل بشكل كبير من وقت الاستجابة لظهور الإعلان الأول.

لتحسين أداء تطبيقك، ننصحك باتّباع الاستراتيجيات التالية عند إنشاء إعدادات لإعداد المحوّل:

إعطاء الأولوية لشكل إعلان أو وحدة إعلانية معيّنة

يمكنك تحسين أداء التطبيقات التي تعرض إعلانًا فور تشغيلها، مثل "الإعلانات على شاشة فتح التطبيق"، من خلال تحديد شكل الإعلان أو الوحدة الإعلانية في إعدادات إعداد المحوّل.

ينشئ المثال التالي إعدادات تهيئة المحوّل التي تُعدّ محوّلات التوسّط المطلوبة فقط لوحدة إعلانية على شاشة فتح التطبيق معيّنة مع مهلة خمس ثوانٍ:

Kotlin

val adapterConfig =
  AdapterInitializationConfig.Builder()
    .setAllowedAdUnitIds(setOf(AD_UNIT_ID))
    .setInitializationTimeoutMs(5000)
    .build()

جافا

AdapterInitializationConfig adapterConfig =
    new AdapterInitializationConfig.Builder()
        .setAllowedAdUnitIds(Set.of(AD_UNIT_ID))
        .setInitializationTimeoutMs(5000)
        .build();

ينشئ المثال التالي إعدادات لإعداد المحوّلات، بحيث يتم إعداد محوّلات التوسّط المطلوبة فقط لجميع "الإعلانات على شاشة فتح التطبيق"، ويضبط مهلة مدتها خمس ثوانٍ:

Kotlin

val adapterConfig =
  AdapterInitializationConfig.Builder()
    .setAllowedAdFormats(setOf(AdFormat.APP_OPEN_AD))
    .setInitializationTimeoutMs(5000)
    .build()

جافا

AdapterInitializationConfig adapterConfig =
    new AdapterInitializationConfig.Builder()
        .setAllowedAdFormats(Set.of(AdFormat.APP_OPEN_AD))
        .setInitializationTimeoutMs(5000)
        .build();

بدء محوّلات توسّط معيّنة

إذا كنت تعرف بالضبط شركاء التوسط الذين يملأون عادةً أول ظهور للإعلان، يمكنك تهيئة هذا المحوّل المحدد فقط من خلال توفير اسم فئة المحوّل في إعدادات تهيئة المحوّل. يمكنك الجمع بين هذا الإجراء وتخطّي المحوّلات غير المُهيأة بشكل صريح وضبط مهلة لـ GMA Next-Gen SDK من أجل عدم انتظار المحوّلات غير المُهيأة المتبقية أثناء المزاد.

ينشئ المثال التالي إعدادات لإعداد المحوّل، بحيث يتم إعداد محوّل توسّط معيّن وضبط مهلة مدتها خمس ثوانٍ:

Kotlin

val adapterConfig =
  AdapterInitializationConfig.Builder()
    .setAllowedAdapterClasses(setOf(ADAPTER_JAVA_CLASS_NAME))
    .setInitializationTimeoutMs(5000)
    .build()

جافا

AdapterInitializationConfig adapterConfig =
    new AdapterInitializationConfig.Builder()
        .setAllowedAdapterClasses(Set.of(ADAPTER_JAVA_CLASS_NAME))
        .setInitializationTimeoutMs(5000)
        .build();

يمكنك جلب أسماء فئات المحوِّل آليًا. يستخرج المثال التالي أسماء فئات المحوِّل برمجيًا:

Kotlin

ExampleMediationAdapter::class.java.name

جافا

ExampleMediationAdapter.class.getName()

استبعاد محوّلات توسّط معيّنة

إذا لاحظت أنّ بعض محوّلات التوسّط تتّسم بوقت استجابة مرتفع باستمرار، يمكنك استبعاد هذه المحوّلات وإعدادها في وقت لاحق.

ينشئ المثال التالي إعدادات لإعداد المحوّلات تستثني محوّلات معيّنة من الإعداد، وتضبط مهلة مدتها خمس ثوانٍ:

Kotlin

val adapterConfig =
  AdapterInitializationConfig.Builder()
    .setExcludedAdapterClasses(setOf(ADAPTER_JAVA_CLASS_NAME))
    .setInitializationTimeoutMs(5000)
    .build()

جافا

AdapterInitializationConfig adapterConfig =
    new AdapterInitializationConfig.Builder()
        .setExcludedAdapterClasses(Set.of(ADAPTER_JAVA_CLASS_NAME))
        .setInitializationTimeoutMs(5000)
        .build();

تخطّي المحوّلات غير المُهيأة

إذا كنت تخطّط لإعداد أو استبعاد محوّلات توسّط معيّنة، يمكنك ضبط طلب عرض الإعلان لتخطّي المحوّلات غير المُعدّة التي لا تزال متوفّرة في العرض الانحداري لطلبات الشبكة.

إذا لم تنشئ إعدادات المحوّل، سيظل بإمكانك ضبط طلب عرض الإعلان لتخطّي المحوّلات التي لم تتم تهيئتها. GMA Next-Gen SDK بإصدار طلب عرض إعلان بدون انتظار انتهاء مهلة المحوّلات أو تعذُّر إعدادها.

يُهيئ المثال التالي حزمة تطوير البرامج (SDK) باستخدام إعدادات تهيئة المحوّل وينشئ طلب عرض إعلان على شاشة فتح التطبيق يتخطّى المحوّلات غير المهيأة:

Kotlin

val initConfig =
  InitializationConfig.Builder(appId)
    .setAdapterInitializationConfig(adapterInitializationConfig)
    .build()

// Initialize the GMA Next-Gen SDK with a config containing your adapter initialization
// settings.
val backgroundScope = CoroutineScope(Dispatchers.IO)
backgroundScope.launch {
  MobileAds.initialize(context = context, initConfig) {

    // Make your ad request after adapter initialization completes.
    AppOpenAd.load(
      AdRequest.Builder(adUnitId = adUnitId)
        // Set this to guarantee that the ad request
        // doesn't wait for any other uninitialized adapters.
        .skipUninitializedAdapters()
        .build(),
      adLoadCallback =
        object : AdLoadCallback<AppOpenAd> {

          override fun onAdLoaded(ad: AppOpenAd) {
            // TODO: Your ad logic here
            // ....

            // Execute non-time-sensitive tasks after ad load completes.
            performPostLaunchSetup()
          }

          override fun onAdFailedToLoad(adError: LoadAdError) {
            // TODO: Handle load error.
            // ....

            // Ensure non-time-sensitive post-launch tasks execute even if ad load fails.
            performPostLaunchSetup()
          }
        },
    )
  }
}

جافا

InitializationConfig initConfig =
    new InitializationConfig.Builder(appId)
        .setAdapterInitializationConfig(adapterInitializationConfig)
        .build();

// Initialize the GMA Next-Gen SDK with a config containing your adapter initialization
// settings.
MobileAds.initialize(
    context,
    initConfig,
    initializationStatus -> {
      // Make your ad request after adapter initialization completes.
      AppOpenAd.load(
          new AdRequest.Builder(adUnitId)
              // Set this to guarantee that the ad request
              // doesn't wait for any other uninitialized adapters.
              .skipUninitializedAdapters()
              .build(),
          new AdLoadCallback<AppOpenAd>() {
            @Override
            public void onAdLoaded(@NonNull AppOpenAd ad) {
              // TODO: Your ad logic here
              // ....

              // Execute non-time-sensitive tasks after ad load completes.
              performPostLaunchSetup();
            }

            @Override
            public void onAdFailedToLoad(@NonNull LoadAdError error) {
              // TODO: Handle load error.
              // ....

              // Ensure non-time-sensitive post-launch tasks execute even if ad load fails.
              performPostLaunchSetup();
            }
          });
    });

بدء المحوّلات المتبقية

بعد تحميل فرص الإعلانات الحسّاسة للوقت، ابدأ تشغيل المحوّلات المتبقية لضمان تغطية كاملة لتوسّط الشركاء لبقية جلسة التطبيق.

يُهيئ المثال التالي بقية المحوّلات من خلال توفير إعدادات فارغة:

Kotlin


// Provide initializeAdapters with an empty configuration to initialize
// any adapters not initialized with configurable initialization.
MobileAds.initializeAdapters(AdapterInitializationConfig.Builder().build())

جافا

// Provide initializeAdapters with an empty configuration to initialize
// any adapters not initialized with configurable initialization.
MobileAds.initializeAdapters(new AdapterInitializationConfig.Builder().build());