PIP 모드 광고 구현 (베타)

플랫폼 선택: Android iOS Unity

PIP 모드

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

이 가이드에서는 앱에서 PIP 모드 광고를 요청하고 표시하는 방법을 설명합니다 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를 광고 단위 ID로 바꿉니다.

광고 게재

화면에 PIP 모드 광고를 표시하려면 표시 메서드를 호출합니다. 다음 예에서는 광고를 기본 위치에 표시하고 표시 범위를 화면으로 설정합니다.

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

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

광고 숨기기

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

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 모드 광고에 대한 액세스 권한을 유지해야 합니다. 광고를 단일 화면의 인스턴스 변수가 아닌 앱 수준 싱글톤 또는 공유 상태 관리자에 보관하는 것이 좋습니다.

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