پیاده‌سازی آگهی‌های تصویردرتصویر (نسخه بتا)

انتخاب پلاتفرم: Android iOS

آگهی‌های تصویردرتصویر (PiP) در پنجره‌ای شناور نمایش داده می‌شوند که در بالای محتوای روی صفحه، مانند مقالات، فیدها یا گیم‌پلی، باقی می‌ماند. این قالب به کاربران امکان می‌دهد درحالی‌که آگهی قابل‌مشاهده است با برنامه شما تعامل داشته باشند. برای نمایش آگهی‌هایی که کل صفحه‌نمایش را اشغال نمی‌کنند، این قالب را انتخاب کنید.

این راهنما درخواست و نمایش آگهی‌های تصویردرتصویر در برنامه شما بااستفاده از Google Mobile Ads SDK را پوشش می‌دهد.

قبل‌از شروع

قبل‌از ادامه دادن، موارد زیر را انجام دهید:

• ‫Google Mobile Ads SDK را راه‌اندازی کنید.

• نسخه Google Mobile Ads SDK ‏13.10.0 یا جدیدتر را نصب کنید.

• فعال کردن آگهی‌های آزمایشی و استفاده از شناسه واحد آگهی آزمایشی زیر: /21775744923/example/picture-in-picture

بار کردن آگهی

برای بار کردن شیء GADPictureInPictureAd، درخواست آگهی ایجاد کنید و متد load را فراخوانی کنید:

Swift

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

‫adUnitID را با شناسه واحد آگهی‌تان جایگزین کنید.

آبجکتیو-سی

- (void)loadAdManagerPictureInPictureAd {
  GAMRequest *request = [GAMRequest 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 را با شناسه واحد آگهی‌تان جایگزین کنید.

نمایش آگهی

برای نمایش آگهی تصویردرتصویر روی صفحه، گزینه‌های تصویردرتصویر را پیکربندی کنید و روش show را فراخوانی کنید. مثال زیر جایگاه پیش‌فرض آگهی و محدوده ارائه را روی صفحه تنظیم می‌کند:

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

آبجکتیو-سی

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

آبجکتیو-سی

- (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 آگهی را می‌بندد. برای اینکه آگهی پس‌از برداشته شدن صفحه میزبان از حافظه قابل‌مشاهده بماند، دامنه ارائه را روی برنامه تنظیم کنید:

Swift

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

آبجکتیو-سی

- (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.")
}

آبجکتیو-سی

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

پنهان کردن آگهی

برای برداشتن آگهی شناور از صفحه، روش hide را فراخوانی کنید. این روش فراخوانی رویداد پنهان شدن آگهی را فرا می‌خواند:

Swift

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

آبجکتیو-سی

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

آبجکتیو-سی

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

آگهی در صفحه‌نمایش‌های مختلف قابل‌مشاهده بماند

وقتی محدوده ارائه را روی برنامه تنظیم می‌کنید، آگهی تصویردرتصویر حتی وقتی برنامه شما صفحه میزبانی را از حافظه برمی‌دارد قابل‌مشاهده باقی می‌ماند. برای تعامل با آگهی یا بستن آن وقتی کاربر از صفحه میزبان خارج می‌شود، برنامه شما باید دسترسی به آگهی تصویردرتصویر را حفظ کند. توصیه می‌کنیم آگهی را در یک تک‌عضوی سطح برنامه یا مدیر وضعیت مشترک نگه دارید نه در متغیر نمونه یک صفحه.

برای نمونه‌هایی از نحوه قابل‌مشاهده نگه داشتن آگهی در سراسر صفحه‌ها، برنامه‌های نمونه زیر را ببینید:

• Swift
• Objective-C