보상형 전면 광고 설정

Next-Gen SDK.

플랫폼 선택: Android iOS Unity Flutter Android (레거시)

보상형 전면 광고는 자연스러운 앱 전환 중에 자동으로 게재되는 광고에 대해 보상을 제공하는 형식입니다. 보상형 광고와 달리 사용자는 수신 동의하지 않고도 보상형 전면 광고를 볼 수 있습니다.

이 가이드에서는 보상형 전면 광고를 Android 앱에 통합하는 방법을 설명합니다.

시작하기 전에

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

  • 설정 GMA Next-Gen SDK.
  • 테스트 보상형 전면 광고 단위 ID /21775744923/example/rewarded-interstitial을 사용합니다.
    • 앱을 제작하고 테스트할 때 운영 중인 실제 광고 대신 테스트 광고를 사용하세요. 그렇지 않을 경우 계정이 정지될 수 있습니다.
    • 앱을 게시하기 전에 이 ID를 광고 단위 ID로 바꿉니다.
    • GMA Next-Gen SDK 테스트 광고에 관한 자세한 내용은 테스트 광고 사용 설정을 참고하세요.

광고 미리 로드 이해하기

GMA Next-Gen SDK의 광고 미리 로드는 광고 로드 및 캐싱을 자동화합니다.

광고 미리 로드는 다음과 같은 이점을 제공합니다.

  • 참조 관리: 광고가 게재될 때까지 참조를 유지합니다.
  • 자동 다시 로드: 캐시에서 광고가 검색되면 새 광고를 로드합니다.
  • 관리되는 재시도: 광고 로드에 실패하면 새 광고를 로드합니다.
  • 만료 처리: 만료되기 전에 광고를 새로고침합니다.
  • 캐시 최적화: 캐시 순서를 최적화하여 우선순위가 가장 높은 광고를 게재합니다.

광고 미리 로드 시작

광고 미리 로드를 시작하려면 앱 시작 시 start 메서드를 한 번 호출합니다. start 메서드를 호출하면 GMA Next-Gen SDK가 자동으로 광고를 미리 로드하고 미리 로드된 구성에 대한 실패한 요청을 재시도합니다.

다음 예는 광고 미리 로드를 시작하는 방법을 보여줍니다.

Kotlin

// Call start() once after SDK initialization.
// Preload only one ad unit per format to optimize performance.
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)

Java

// Call start() once after SDK initialization.
// Preload only one ad unit per format to optimize performance.
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig);

AD_UNIT_ID를 광고 단위 ID로 바꿉니다.

이전 예는 광고 단위 ID를 미리 로드 ID로 사용하는 방법을 보여줍니다. 미리 로드 ID는 광고 미리 로드 구성을 식별하기 위해 만드는 문자열 식별자입니다. 앱에 동일한 광고 단위 ID에 대한 여러 타겟팅 구성이 필요한 경우 맞춤 문자열 식별자를 전달합니다.

미리 로드된 광고 가져오기 및 게재

광고를 게재하려면 pollAd 메서드를 호출합니다. GMA Next-Gen SDK는 사용 가능한 광고를 가져오고 백그라운드에서 다음 광고를 자동으로 미리 로드합니다. 사용 가능한 광고가 없으면 GMA Next-Gen SDK는 광고를 반환하지 않습니다.

사용 가능한 광고 객체가 있으면 show 메서드를 호출하여 광고를 표시합니다. 보상 리스너를 사용하여 보상 이벤트를 처리합니다. 다음 예는 미리 로드된 광고를 가져오고 게재하는 방법을 보여줍니다.

Kotlin

private fun pollAndShowAd(activity: Activity, adUnitId: String) {
  // Polling returns the next available ad and loads another ad in the background.
  val ad = RewardedInterstitialAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Rewarded interstitial ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : RewardedInterstitialAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Rewarded interstitial ad recorded an impression.")
      }
    }
  ad.show(activity) { rewardItem -> Log.d(TAG, "User earned reward: ${rewardItem.amount}") }
}

Java

private void pollAndShowAd(Activity activity, String adUnitId) {
  // Polling returns the next available ad and loads another ad in the background.
  final RewardedInterstitialAd ad = RewardedInterstitialAdPreloader.pollAd(adUnitId);

  // Interact with the ad object as needed.
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not available.");
    return;
  }

  Log.d(TAG, "Rewarded interstitial ad response info: " + ad.getResponseInfo());
  ad.setAdEventCallback(
      new RewardedInterstitialAdEventCallback() {
        @Override
        public void onAdImpression() {
          Log.d(TAG, "Rewarded interstitial ad recorded an impression.");
        }
      });

  // Show the ad.
  ad.show(
      activity,
      rewardItem -> {
        Log.d(TAG, "User earned reward: " + rewardItem.getAmount());
      });
}

광고를 게재할 준비가 될 때까지 pollAd 메서드를 호출하지 마세요. 광고를 게재하지 않고 광고 응답 정보를 읽으려면 응답 정보 읽기를 참고하세요.

광고 이벤트 수신 대기

광고를 게재하기 전에 광고 이벤트를 수신 대기합니다. 다음 예는 광고 이벤트의 콜백을 등록하는 방법을 보여줍니다.

Kotlin

private fun listenToAdEvents() {
  // Listen for ad events.
  val ad = rewardedInterstitialAd
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not ready yet.")
    return
  }

  ad.adEventCallback =
    object : RewardedInterstitialAdEventCallback {
      override fun onAdShowedFullScreenContent() {
        // Rewarded interstitial ad did show.
      }

      override fun onAdDismissedFullScreenContent() {
        // Rewarded interstitial ad did dismiss.
        rewardedInterstitialAd = null
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError
      ) {
        // Rewarded interstitial ad failed to show.
        Log.e(TAG, "Rewarded interstitial ad failed to show: ${fullScreenContentError.message}")
      }

      override fun onAdImpression() {
        // Rewarded interstitial ad did record an impression.
      }

      override fun onAdClicked() {
        // Rewarded interstitial ad did record a click.
      }
    }
}

Java

private void listenToAdEvents() {
  // Listen for ad events.
  if (rewardedInterstitialAd == null) {
    Log.e(TAG, "Rewarded interstitial ad is not ready yet.");
    return;
  }

  rewardedInterstitialAd.setAdEventCallback(
      new RewardedInterstitialAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded interstitial ad did show.
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          // Rewarded interstitial ad did dismiss.
          rewardedInterstitialAd = null;
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            @NonNull FullScreenContentError fullScreenContentError) {
          // Rewarded interstitial ad failed to show.
          Log.e(
              TAG,
              "Rewarded interstitial ad failed to show: " + fullScreenContentError.getMessage());
        }

        @Override
        public void onAdImpression() {
          // Rewarded interstitial ad did record an impression.
        }

        @Override
        public void onAdClicked() {
          // Rewarded interstitial ad did record a click.
        }
      });
}

선택사항: 서버 측 확인 (SSV) 콜백 검사

앱에 서버 측 확인 콜백에서 추가 데이터가 필요한 경우 보상형 전면 광고의 맞춤 데이터 기능을 사용합니다. 보상형 전면 광고 객체에 설정된 모든 문자열 값은 SSV 콜백의 custom_data 쿼리 매개변수에 전달됩니다. 맞춤 데이터 값이 설정되지 않은 경우 custom_data 쿼리 매개변수 값이 SSV 콜백에 표시되지 않습니다.

다음 코드 샘플은 광고를 게재하기 전에 보상형 전면 광고 객체에 맞춤 데이터를 설정하는 방법을 보여줍니다.

Kotlin

RewardedInterstitialAd.load(
  context,
  AD_UNIT_ID,
  AdRequest.Builder().build(),
  object : RewardedInterstitialAdLoadCallback() {
    override fun onAdLoaded(ad: RewardedInterstitialAd) {
      rewardedInterstitialAd = ad
      val options =
        ServerSideVerificationOptions.Builder().setCustomData("SAMPLE_CUSTOM_DATA_STRING").build()
      rewardedInterstitialAd?.setServerSideVerificationOptions(options)
    }
  },
)

Java

RewardedInterstitialAd.load(
    context,
    AD_UNIT_ID,
    new AdRequest.Builder().build(),
    new RewardedInterstitialAdLoadCallback() {
      @Override
      public void onAdLoaded(RewardedInterstitialAd ad) {
        rewardedInterstitialAd = ad;
        ServerSideVerificationOptions options =
            new ServerSideVerificationOptions.Builder()
                .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
                .build();
        rewardedInterstitialAd.setServerSideVerificationOptions(options);
      }
    });

SAMPLE_CUSTOM_DATA_STRING을 맞춤 데이터로 바꿉니다.

선택사항: 미리 로드 이벤트 수신 대기

광고 미리 로드를 시작할 때 미리 로드 이벤트를 등록하여 광고가 미리 로드되거나, 미리 로드에 실패하거나, 광고 캐시가 소진될 때 알림을 받습니다.

다음 예는 미리 로드 광고 이벤트를 등록하는 방법을 보여줍니다.

Kotlin

val preloadCallback =
  // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(
        TAG,
        "Rewarded interstitial preload ad $preloadId failed to load with error: ${adError.message}",
      )
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Rewarded interstitial preload ad $preloadId is not available")
      // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
    }

    override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo) {
      Log.i(TAG, "Rewarded interstitial preload ad $preloadId is available")
    }
  }
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback)

Java

PreloadCallback preloadCallback =
    // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(@NonNull String preloadId, @NonNull LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Rewarded interstitial preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
        // [Optional] Get the error response info for additional details.
        // ResponseInfo responseInfo = adError.getResponseInfo();
      }

      @Override
      public void onAdsExhausted(@NonNull String preloadId) {
        Log.i(TAG, "Rewarded interstitial preload ad " + preloadId + " is not available");
        // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
      }

      @Override
      public void onAdPreloaded(@NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
        Log.i(TAG, "Rewarded interstitial preload ad " + preloadId + " is available");
      }
    };
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

광고 로드에 실패하면 GMA Next-Gen SDK 자동으로 광고를 미리 로드하고 미리 로드된 구성에 대한 실패한 요청을 재시도합니다.

선택사항: 광고 사용 가능 여부 확인

광고가 사용 가능한지 확인해야 하는 경우 광고 사용 가능 여부를 확인합니다. 다음 예는 미리 로드된 광고가 사용 가능한지 확인하는 방법을 보여줍니다.

Kotlin

private fun isAdAvailable(adUnitId: String): Boolean {
  return RewardedInterstitialAdPreloader.isAdAvailable(adUnitId)
}

Java

private boolean isAdAvailable(String adUnitId) {
  return RewardedInterstitialAdPreloader.isAdAvailable(adUnitId);
}

선택사항: 버퍼 크기 설정

버퍼 사이즈는 메모리에 보관되는 미리 로드된 광고 수를 제어합니다. 기본적으로 Google은 메모리 사용량과 광고 게재 지연 시간을 균형 있게 조정하도록 버퍼 크기를 최적화합니다. 맞춤 버퍼 크기를 설정하여 메모리에 보관되는 광고 수를 늘릴 수 있습니다. 최대 버퍼 사이즈는 4로 설정하는 것이 좋습니다.

다음 예는 미리 로드된 광고의 버퍼 사이즈를 4로 설정하는 방법을 보여줍니다.

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
// Maintain small or default buffer size unless rapid transitions are expected.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 4)
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)

Java

// Maintain small or default buffer size unless rapid transitions are expected.
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 4);
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig);

미리 로드 캐시 한도

GMA Next-Gen SDK는 모든 광고 단위 및 미리 로드 ID에서 미리 로드된 광고의 총 수에 앱 전체 한도를 적용합니다.

  • 기본 한도: Google은 메모리에 미리 로드된 광고를 최대 6개까지 보관합니다. 이 한도는 모든 형식과 미리 로드 ID에서 공유됩니다.
  • 미리 로드 ID당 버퍼 사이즈를 2 또는 3으로 유지하는 것이 좋습니다.

선택사항: 광고 미리 로드 중지

세션에서 특정 미리 로드 ID의 광고를 다시 게재할 필요가 없는 경우 광고 미리 로드를 중지할 수 있습니다. 특정 미리 로드 ID의 광고 로드를 중지하려면 미리 로드 ID와 함께 destroy 메서드를 호출합니다. destroy 메서드를 호출하면 미리 로드 ID와 연결된 모든 미리 로드된 광고가 캐시에서 삭제됩니다.

다음 예는 광고 미리 로드를 중지하는 방법을 보여줍니다.

Kotlin

private fun stopPreloading(adUnitId: String) {
  // Stops the preloading and destroy preloaded ads.
  RewardedInterstitialAdPreloader.destroy(adUnitId)
}

Java

private void stopPreloading(String adUnitId) {
  // Stops the preloading and destroy preloaded ads.
  RewardedInterstitialAdPreloader.destroy(adUnitId);
}

선택사항: 응답 정보 읽기

캐시에서 광고를 삭제하지 않고 다음 미리 로드된 광고의 응답 정보를 읽습니다.

다음 예는 다음 미리 로드된 광고 응답 정보를 읽는 방법을 보여줍니다.

Kotlin

val responseInfo = RewardedInterstitialAdPreloader.peekAdResponseInfo(preloadId)
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.")
  return
}

Log.d(TAG, "Peeked ad response ID: ${responseInfo.responseId}")

Java

ResponseInfo responseInfo = RewardedInterstitialAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

Log.d(TAG, "Peeked ad response ID: " + responseInfo.getResponseId());