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

اختيار النظام الأساسي: Android iOS Android (الإصدار القديم)

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

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

ملاحظة: تتوفّر ميزة "إعدادات تهيئة المهايئ القابلة للضبط" في الإصدار الأوّلي.

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

• إنشاء إعدادات المحوّل
• تخطّي المحوّلات التي لم يتمّ إعدادها
• تهيئة المحوّلات المتبقية

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

• استيراد الإصدار GMA Next-Gen SDK 0.25.0-beta01 أو إصدار أحدث
• إعداد GMA Next-Gen SDK

• يمكنك تفعيل هذه الميزة من خلال إضافة التعليق التوضيحي @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()
ConfigurableInitSnippets.kt

جافا

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

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

Kotlin

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

جافا

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

تهيئة محوّلات التوسّط المحدّدة

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

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

Kotlin

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

جافا

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

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

Kotlin

ExampleMediationAdapter::class.java.name

جافا

ExampleMediationAdapter.class.getName()

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

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

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

Kotlin

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

جافا

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

ملاحظة: يمكنك إعداد المحوّلات في مجموعات باستخدام طلبات متعدّدة، مثل طلبَين منفصلَين للمحوّلات ذات الصلة، وذلك لمنع المحوّل البطيء من حظر المحوّلات الأخرى أو عمليات رد الاتصال الخاصة بها.

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

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

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

ملاحظة مهمة: بشكلٍ تلقائي، تبدأ 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()
          }
        },
    )
  }
}
ConfigurableInitSnippets.kt

جافا

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();
            }
          });
    });
ConfigurableInitSnippets.java

تهيئة المحوّلات المتبقية

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

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

Kotlin

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

جافا

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