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

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

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

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

يغطّي هذا الدليل طلب "الإعلانات في الوضع نافذة ضمن النافذة" وعرضها في تطبيقك باستخدام Google Mobile Ads SDK.

قبل البدء

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

تحميل إعلان

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

Swift

private func loadPictureInPictureAd() async {
  do {
    // Capture the PictureInPictureAd reference for later use.
    pipAd = try await PictureInPictureAd.load(
      with: adUnitID, request: Request())
    // Set the delegate to be notified of ad events.
    pipAd?.delegate = self
  } catch {
    print(
      "Picture-in-Picture ad failed to load: \(error.localizedDescription)")
  }
}

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

Objective-C

- (void)loadPictureInPictureAd {
  GADRequest *request = [GADRequest request];

  [GADPictureInPictureAd
       loadWithAdUnitID:kAdUnitID
                request:request
      completionHandler:^(GADPictureInPictureAd *_Nullable ad, NSError *_Nullable error) {
        if (error) {
          NSLog(@"Picture-in-Picture ad failed to load: %@", error);
          return;
        }
        // Capture the PictureInPictureAd reference for later use.
        self.pipAd = ad;
        // Set the delegate to be notified of ad events.
        self.pipAd.delegate = self;
      }];
}

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

عرض الإعلان

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

Swift

private func showPictureInPictureAd() {
  // Use the loaded PictureInPictureAd instance.
  guard let pipAd else {
    print("No ad to show.")
    return
  }
  let options = PictureInPictureAdOptions()
  // Uses the Google Mobile Ads SDK's default screen position.
  options.position = .default
  // Binds the ad lifecycle to the host screen.
  options.presentationScope = .screen

  pipAd.show(with: options)
}

Objective-C

- (void)showPictureInPictureAd {
  // Use the loaded PictureInPictureAd instance.
  if (!self.pipAd) {
    NSLog(@"No ad to show.");
    return;
  }
  GADPictureInPictureAdOptions *options =
      [[GADPictureInPictureAdOptions alloc] init];
  // Uses the Google Mobile Ads SDK's default screen position.
  options.position = GADPictureInPictureAdPositionDefault;
  // Binds the ad lifecycle to the host screen.
  options.presentationScope = GADPictureInPictureAdPresentationScopeScreen;

  [self.pipAd showWithOptions:options];
}

ضبط الموضع

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

Swift

private func createTopLeftPositionOptions() -> PictureInPictureAdOptions {
  let options = PictureInPictureAdOptions()
  // Sets the ad position to the top-left corner of the screen.
  options.position = .topLeft
  return options
}

Objective-C

- (GADPictureInPictureAdOptions *)createTopLeftPositionOptions {
  GADPictureInPictureAdOptions *options =
      [[GADPictureInPictureAdOptions alloc] init];
  // Sets the ad position to the top-left corner of the screen.
  options.position = GADPictureInPictureAdPositionTopLeft;
  return options;
}

للاطّلاع على جميع المواضع المتاحة، يُرجى الانتقال إلى GADPictureInPictureAdPosition.

ضبط نطاق العرض

تربط حزمة Google Mobile Ads SDK تلقائيًا Google Mobile Ads SDK "إعلانًا في الوضع نافذة ضمن النافذة" بشاشة المضيف الحالية. Google Mobile Ads SDK تتجاهل الإعلان عندما لا تعود هيكلية طرق عرض شاشة المضيف في الذاكرة. لإبقاء الإعلان مرئيًا بعد إزالة شاشة المضيف من الذاكرة، اضبط نطاق العرض على التطبيق:

Swift

private func createApplicationScopedOptions() -> PictureInPictureAdOptions {
  let options = PictureInPictureAdOptions()
  // Keeps the ad visible beyond the host screen's lifecycle.
  options.presentationScope = .application
  return options
}

Objective-C

- (GADPictureInPictureAdOptions *)createApplicationScopedOptions {
  GADPictureInPictureAdOptions *options =
      [[GADPictureInPictureAdOptions alloc] init];
  // Keeps the ad visible beyond the host screen's lifecycle.
  options.presentationScope = GADPictureInPictureAdPresentationScopeApplication;
  return options;
}

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

الاستماع إلى أحداث الإعلانات

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

Swift

func pictureInPictureAdDidShow(_ pictureInPictureAd: PictureInPictureAd) {
  print("Picture-in-Picture ad shown.")
}

func pictureInPictureAdDidHide(_ pictureInPictureAd: PictureInPictureAd) {
  print("Picture-in-Picture ad hidden.")
}

func pictureInPictureAdDidFailToShow(
  _ pictureInPictureAd: PictureInPictureAd, error: Error
) {
  print("Picture-in-Picture ad failed to show: \(error.localizedDescription)")
}

func pictureInPictureAdDidRecordImpression(
  _ pictureInPictureAd: PictureInPictureAd
) {
  print("Picture-in-Picture ad recorded an impression.")
}

func pictureInPictureAdDidRecordClick(
  _ pictureInPictureAd: PictureInPictureAd
) {
  print("Picture-in-Picture ad recorded a click.")
}

func pictureInPictureAdWillPresentScreen(
  _ pictureInPictureAd: PictureInPictureAd
) {
  print("Picture-in-Picture ad will present screen.")
}

func pictureInPictureAdWillDismissScreen(
  _ pictureInPictureAd: PictureInPictureAd
) {
  print("Picture-in-Picture ad will dismiss screen.")
}

func pictureInPictureAdDidDismissScreen(
  _ pictureInPictureAd: PictureInPictureAd
) {
  print("Picture-in-Picture ad dismissed screen.")
}

Objective-C

- (void)pictureInPictureAdDidShow:(GADPictureInPictureAd *)pictureInPictureAd {
  NSLog(@"Picture-in-Picture ad shown.");
}

- (void)pictureInPictureAdDidHide:(GADPictureInPictureAd *)pictureInPictureAd {
  NSLog(@"Picture-in-Picture ad hidden.");
}

- (void)pictureInPictureAdDidFailToShow:(GADPictureInPictureAd *)pictureInPictureAd
                              withError:(NSError *)error {
  NSLog(@"Picture-in-Picture ad failed to show: %@", error);
}

- (void)pictureInPictureAdDidRecordImpression:(GADPictureInPictureAd *)pictureInPictureAd {
  NSLog(@"Picture-in-Picture ad recorded an impression.");
}

- (void)pictureInPictureAdDidRecordClick:(GADPictureInPictureAd *)pictureInPictureAd {
  NSLog(@"Picture-in-Picture ad recorded a click.");
}

- (void)pictureInPictureAdWillPresentScreen:(GADPictureInPictureAd *)pictureInPictureAd {
  NSLog(@"Picture-in-Picture ad will present screen.");
}

- (void)pictureInPictureAdWillDismissScreen:(GADPictureInPictureAd *)pictureInPictureAd {
  NSLog(@"Picture-in-Picture ad will dismiss screen.");
}

- (void)pictureInPictureAdDidDismissScreen:(GADPictureInPictureAd *)pictureInPictureAd {
  NSLog(@"Picture-in-Picture ad dismissed screen.");
}

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

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

Swift

private func hidePictureInPictureAd() {
  // Use the loaded PictureInPictureAd instance.
  guard let pipAd else {
    print("No ad to hide.")
    return
  }
  pipAd.hide()
}

Objective-C

- (void)hidePictureInPictureAd {
  // Use the loaded PictureInPictureAd instance.
  if (!self.pipAd) {
    NSLog(@"No ad to hide.");
    return;
  }
  [self.pipAd hide];
}

تنظيف موارد الإعلانات

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

Swift

private func cleanUpPictureInPictureAd() {
  pipAd?.hide()
  pipAd = nil
}

Objective-C

- (void)cleanUpPictureInPictureAd {
  [self.pipAd hide];
  self.pipAd = nil;
}

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

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

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