PIP 모드 광고 구현 (베타)

PIP 모드

PIP 모드 광고는 기사, 피드 또는 게임플레이와 같이 화면의 콘텐츠 위에 표시되는 플로팅 창에 게재됩니다. 이 형식을 사용하면 광고가 계속 표시되는 동안 사용자가 앱과 상호작용할 수 있습니다. 전체 화면을 차지하지 않는 광고를 표시하려면 이 형식을 선택하세요.

이 가이드에서는 앱에서 PIP 모드 광고를 요청하고 표시하는 방법을 설명합니다 GMA Next-Gen SDK를 사용하여.

시작하기 전에

계속하기 전에 다음 작업을 실행하세요.

광고 로드하기

PictureInPictureAd를 로드하려면 광고 요청을 만들고 load 메서드를 호출합니다.

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를 광고 단위 ID로 바꿉니다.

광고 게재

화면에 PIP 모드 광고를 표시하려면 PIP 모드 옵션을 구성하고 show 메서드를 호출합니다. 다음 예에서는 광고의 기본 위치와 프레젠테이션 범위를 화면으로 설정합니다.

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는 처음 표시될 때 화면의 오른쪽 하단 에 또는 이전에 표시된 경우 마지막으로 알려진 위치에 PIP 모드 광고를 표시합니다. 광고가 표시되는 위치를 맞춤설정하려면 PIP 모드 옵션에서 위치를 설정하세요. 다음 예에서는 화면의 왼쪽 상단에 있는 콘텐츠 위에 위치를 설정합니다.

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는 PIP 모드 광고를 현재 호스트 화면에 바인딩합니다. 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();
}

자세한 내용은 여러 화면에서 광고를 계속 표시를 참고하세요.

광고 이벤트 콜백 설정

PIP 모드 광고 수명 주기 이벤트를 처리하려면 광고를 표시하기 전에 광고에 이벤트 콜백을 설정하세요. 이 콜백은 클릭 및 노출과 같은 표준 이벤트를 보고합니다. 이 콜백은 광고가 표시되거나 숨겨지는 경우와 같은 PIP 모드 관련 이벤트도 보고합니다.

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

광고 숨기기

화면에서 플로팅 광고를 삭제하려면 hide 메서드를 호출하세요. 이 메서드는 광고 숨김 이벤트 콜백을 호출합니다.

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

여러 화면에서 광고를 계속 표시

프레젠테이션 범위를 애플리케이션으로 설정하면 앱에서 메모리에서 호스팅 화면을 삭제하더라도 PIP 모드 광고가 계속 표시됩니다. 사용자가 호스트 화면에서 벗어날 때 광고와 상호작용하거나 광고를 닫으려면 앱에서 PIP 모드 광고에 계속 액세스할 수 있어야 합니다. 단일 화면의 인스턴스 변수가 아닌 앱 수준 싱글톤 또는 공유 상태 관리자에 광고를 보관하는 것이 좋습니다.

여러 화면에서 광고를 계속 표시하는 방법의 예는 샘플 앱을 참고하세요.