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

پلاتفرم را انتخاب کنید: Android iOS Unity

تصویر در تصویر

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

این راهنما درخواست و نمایش آگهی‌های تصویردرتصویر در برنامه شما را بااستفاده از 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 را با شناسه واحد آگهی‌تان جایگزین کنید.

آبجکتیو-سی

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

آبجکتیو-سی

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

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

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

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

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

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

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