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

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

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

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

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

قبل البدء

قبل المتابعة، يُرجى تنفيذ ما يلي:

تحميل إعلان

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

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 برقم تعريف وحدتك الإعلانية.

عرض الإعلان

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

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 حزمة 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());
        }
      });
}

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

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

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

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

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

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