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

اختيار النظام الأساسي: 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 تلقائيًا إعلانًا في "نافذة ضمن النافذة" في أسفل يسار الشاشة عند عرضه لأول مرة، أو في آخر موضع معروف إذا سبق عرضه. لتخصيص مكان ظهور الإعلان، حدِّد موضعًا عند عرض الإعلان. يضبط المثال التالي الموضع في أعلى المحتوى في أعلى يمين الشاشة:

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

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

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

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