تضمين إعلانات في وضع "نافذة ضمن النافذة" (إصدار تجريبي)

اختيار النظام الأساسي: Android iOS

نافذة ضمن النافذة

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

يتناول هذا الدليل كيفية طلب إعلانات في وضع "نافذة ضمن النافذة" وعرضها في تطبيقك باستخدام GMA Next-Gen SDK.

قبل البدء

قبل المتابعة، يُرجى اتّباع الخطوات التالية:

تحميل إعلان

لتحميل كائن PictureInPictureAd، أنشئ طلب عرض الإعلان واستدعِ الطريقة load:

Kotlin

private fun loadPictureInPictureAd() {
  val request = PictureInPictureAdRequest.Builder(AD_UNIT_ID).build()

  PictureInPictureAd.load(
    request,
    object : AdLoadCallback<PictureInPictureAd> {
      override fun onAdFailedToLoad(adError: LoadAdError) {
        Log.w(TAG, "Picture-in-Picture ad failed to load: $adError")
      }

      override fun onAdLoaded(ad: PictureInPictureAd) {
        Log.d(TAG, "Picture-in-Picture ad loaded.")

        // Capture the PictureInPictureAd reference for later use.
        pipAd = ad
        setAdEventCallback(ad)
      }
    },
  )
}

جافا

private void loadPictureInPictureAd() {
  PictureInPictureAdRequest request = new PictureInPictureAdRequest.Builder(AD_UNIT_ID).build();

  PictureInPictureAd.load(
      request,
      new AdLoadCallback<PictureInPictureAd>() {
        @Override
        public void onAdFailedToLoad(@NonNull LoadAdError adError) {
          Log.w(TAG, "Picture-in-Picture ad failed to load: " + adError);
        }

        @Override
        public void onAdLoaded(@NonNull PictureInPictureAd ad) {
          Log.d(TAG, "Picture-in-Picture ad loaded.");

          // Capture the PictureInPictureAd reference for later use.
          pipAd = ad;
          setAdEventCallback(ad);
        }
      });
}

استبدِل AD_UNIT_ID برقم تعريف وحدتك الإعلانية.

عرض الإعلان

لعرض الإعلان في وضع "نافذة ضمن النافذة" على الشاشة، اضبط خيارات وضع "نافذة ضمن النافذة" واستدعِ الطريقة show. يوضّح المثال التالي كيفية ضبط الموضع التلقائي للإعلان ونطاق العرض على الشاشة:

Kotlin

private fun showPictureInPictureAd(activity: Activity) {
  // Capture the ad reference saved from the onAdLoaded callback.
  val ad = pipAd
  if (ad != null) {
    val options =
      PictureInPictureAdOptions.Builder()
        // Uses the Google Mobile Ads SDK's default screen position.
        .setPosition(PictureInPictureAdPosition.DEFAULT)
        // Binds the ad lifecycle to the host screen.
        .setPresentationScope(PictureInPictureAdPresentationScope.SCREEN)
        .build()
    ad.show(activity, options)
  } else {
    Log.d(TAG, "No ad to show.")
  }
}

جافا

private void showPictureInPictureAd(@NonNull Activity activity) {
  // Use the ad reference saved from the onAdLoaded callback.
  if (pipAd != null) {
    PictureInPictureAdOptions options =
        new PictureInPictureAdOptions.Builder()
            // Uses the Google Mobile Ads SDK's default screen position.
            .setPosition(PictureInPictureAdPosition.DEFAULT)
            // Binds the ad lifecycle to the host screen.
            .setPresentationScope(PictureInPictureAdPresentationScope.SCREEN)
            .build();
    pipAd.show(activity, options);
  } else {
    Log.d(TAG, "No ad to show.");
  }
}

ضبط الموضع

تعرض GMA Next-Gen SDK تلقائيًا إعلانًا في وضع "نافذة ضمن النافذة" في أسفل يسار الشاشة عند عرضه للمرة الأولى، أو في آخر موضع معروف إذا تم عرضه سابقًا. لتخصيص موضع ظهور الإعلان، اضبط الموضع في خيارات "نافذة ضمن النافذة". يضبط المثال التالي الموضع في أعلى المحتوى في أعلى يمين الشاشة:

Kotlin

private fun createTopLeftPositionOptions(): PictureInPictureAdOptions {
  return PictureInPictureAdOptions.Builder()
    // Sets the ad position to the top-left corner of the screen.
    .setPosition(PictureInPictureAdPosition.TOP_LEFT)
    .build()
}

جافا

private PictureInPictureAdOptions createTopLeftPositionOptions() {
  return new PictureInPictureAdOptions.Builder()
      // Sets the ad position to the top-left corner of the screen.
      .setPosition(PictureInPictureAdPosition.TOP_LEFT)
      .build();
}

للاطّلاع على جميع الوظائف الشاغرة، يُرجى الانتقال إلى PictureInPictureAdPosition.

ضبط نطاق العرض التقديمي

بشكلٍ تلقائي، يربط GMA Next-Gen SDK إعلانًا في وضع "نافذة ضمن النافذة" بشاشة التطبيق المضيف الحالية. GMA Next-Gen SDK يرفض الإعلان عندما لا تعود هيكلية طرق عرض شاشة المضيف متوفّرة في الذاكرة. لإبقاء الإعلان مرئيًا بعد إزالة شاشة المضيف من الذاكرة، اضبط نطاق العرض على التطبيق:

Kotlin

private fun createApplicationScopedOptions(): PictureInPictureAdOptions {
  return PictureInPictureAdOptions.Builder()
    // Keeps the ad visible beyond the host screen's lifecycle.
    .setPresentationScope(PictureInPictureAdPresentationScope.APPLICATION)
    .build()
}

جافا

private PictureInPictureAdOptions createApplicationScopedOptions() {
  return new PictureInPictureAdOptions.Builder()
      // Keeps the ad visible beyond the host screen's lifecycle.
      .setPresentationScope(PictureInPictureAdPresentationScope.APPLICATION)
      .build();
}

لمزيد من المعلومات، اطّلِع على مقالة إبقاء الإعلان مرئيًا على جميع الشاشات.

ضبط معاودة الاتصال بحدث الإعلان

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

Kotlin

private fun setAdEventCallback(pipAd: PictureInPictureAd) {
  pipAd.adEventCallback =
    object : PictureInPictureAdEventCallback {
      override fun onAdShown() {
        Log.d(TAG, "Picture-in-Picture ad shown.")
      }

      override fun onAdHidden() {
        Log.d(TAG, "Picture-in-Picture ad hidden.")
      }

      override fun onAdImpression() {
        Log.d(TAG, "Picture-in-Picture ad recorded an impression.")
      }

      override fun onAdClicked() {
        Log.d(TAG, "Picture-in-Picture ad recorded a click.")
      }

      override fun onAdShowedFullScreenContent() {
        Log.d(TAG, "Picture-in-Picture ad showed full screen content.")
      }

      override fun onAdDismissedFullScreenContent() {
        Log.d(TAG, "Picture-in-Picture ad dismissed full screen content.")
      }

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

      override fun onAdPaid(value: AdValue) {
        Log.d(TAG, "Picture-in-Picture ad paid: ${value.valueMicros} ${value.currencyCode}")
      }
    }
}

جافا

private void setAdEventCallback(@NonNull PictureInPictureAd pipAd) {
  pipAd.setAdEventCallback(
      new PictureInPictureAdEventCallback() {
        @Override
        public void onAdShown() {
          Log.d(TAG, "Picture-in-Picture ad shown.");
        }

        @Override
        public void onAdHidden() {
          Log.d(TAG, "Picture-in-Picture ad hidden.");
        }

        @Override
        public void onAdImpression() {
          Log.d(TAG, "Picture-in-Picture ad recorded an impression.");
        }

        @Override
        public void onAdClicked() {
          Log.d(TAG, "Picture-in-Picture ad recorded a click.");
        }

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

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

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

        @Override
        public void onAdPaid(@NonNull AdValue value) {
          Log.d(
              TAG,
              "Picture-in-Picture ad paid: "
                  + value.getValueMicros()
                  + " "
                  + value.getCurrencyCode());
        }
      });
}

إخفاء الإعلان

لإزالة الإعلان العائم من الشاشة، استدعِ طريقة hide. تستدعي هذه الطريقة دالة ردّ الاتصال الخاصة بحدث إخفاء الإعلان:

Kotlin

private fun hidePictureInPictureAd() {
  // Capture the ad reference saved from the onAdLoaded callback.
  val ad = pipAd
  if (ad != null) {
    ad.hide()
  } else {
    Log.d(TAG, "No ad to hide.")
  }
}

جافا

private void hidePictureInPictureAd() {
  // Use the ad reference saved from the onAdLoaded callback.
  if (pipAd != null) {
    pipAd.hide();
  } else {
    Log.d(TAG, "No ad to hide.");
  }
}

تنظيف مراجع الإعلانات

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

Kotlin

private fun cleanUpPictureInPictureAd() {
  pipAd?.destroy()
  pipAd = null
}

جافا

private void cleanUpPictureInPictureAd() {
  // Use the ad reference saved from the onAdLoaded callback.
  if (pipAd != null) {
    pipAd.destroy();
    pipAd = null;
  }
}

إبقاء الإعلان مرئيًا على جميع الشاشات

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

للاطّلاع على أمثلة حول كيفية إبقاء الإعلان مرئيًا على جميع الشاشات، راجِع التطبيقات النموذجية التالية: