보상형 전면 광고 설정

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

보상형 전면 광고는 화면 또는 게임 레벨 사이에 표시되는 광고에 대해 인앱 상품을 제공하는 전체 화면 광고 형식입니다. 보상형 광고와 달리 사용자는 광고를 보기 위해 수신 동의를 하지 않아도 됩니다. 자세한 내용은 AdMob 우수사례 및 보상형 전면 광고 단위 개요(베타)를 참고하세요.

Google Mobile Ads SDK for React Native는 광고 사전 로드를 사용하여 백그라운드 로드, 캐싱, 버퍼 보충을 관리함으로써 표시 지연 시간을 없애고 전환이 발생할 때 광고를 사용할 수 있도록 합니다.

이 가이드에서는 React Native 앱에서 광고 사전 로드를 사용하여 보상형 전면 광고를 통합하는 방법을 보여줍니다.

기본 요건

계속하기 전에 다음을 수행하세요.

• Google Mobile Ads SDK for React Native를 설정합니다.
• 테스트 광고를 사용 설정하고 다음 테스트 광고 단위를 사용합니다.

Android

ca-app-pub-3940256099942544/5354046379

iOS

ca-app-pub-3940256099942544/6978759866

광고 사전 로드 이해하기

Google Mobile Ads SDK for React Native의 광고 사전 로드는 광고 로드 및 캐싱을 자동화합니다.

광고 사전 로드의 이점은 다음과 같습니다.

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

광고를 수동으로 로드하려면 단일 보상형 전면 광고 로드를 참고하세요.

미리 로드 시작

광고 미리 로드를 시작하려면 RewardedInterstitialAdPreloader.start 메서드를 호출하고 preloadId 값, 구성 설정, 이벤트 콜백을 전달하여 버퍼 상태 변경을 모니터링합니다.

export function startRewardedInterstitialAdPreloader(
  adUnitId: string,
  preloadId: string,
  customPreloadCallback?: PreloadCallback,
): boolean {
  const started = RewardedInterstitialAdPreloader.start(
    preloadId,
    {
      request: {adUnitId},
      bufferSize: 2,
    },
    {
      // Called when an ad is preloaded into the buffer.
      onAdPreloaded: (event) => {
        console.log(
          `Rewarded interstitial ad preloaded for ${event.preloadId}`,
        );
        customPreloadCallback?.onAdPreloaded?.(event);
      },
      // Called when an ad fails to preload.
      onAdFailedToPreload: (error: LoadAdError) => {
        console.error(
          'Failed to preload rewarded interstitial ad:',
          error.message,
        );
        customPreloadCallback?.onAdFailedToPreload?.(error);
      },
      // Called when all preloaded ads in the buffer have been shown.
      onAdsExhausted: () => {
        console.log('Rewarded interstitial ad buffer exhausted.');
        customPreloadCallback?.onAdsExhausted?.();
      },
    },
  );
  return started;
}

preloadId는 광고 사전 로드 구성을 고유하게 식별하는 문자열입니다. 앱에서 단일 미리 로드 구성에 광고 단위 ID를 사용하는 경우 해당 광고 단위 ID를 미리 로드 ID로 사용합니다. 앱에서 동일한 광고 단위 ID에 여러 미리 로드 도구가 필요한 경우 각 미리 로드 ID에 고유한 문자열을 전달하세요.

앱이 버퍼에서 미리 로드된 광고를 폴링하면 Google Mobile Ads SDK for React Native가 백그라운드에서 대체 광고를 요청하여 버퍼를 다시 채웁니다. 버퍼에 미리 로드된 광고가 남아 있지 않으면 Google Mobile Ads SDK for React Native에서 onAdsExhausted 콜백을 호출합니다.

미리 로드 캐시 한도

Google Mobile Ads SDK for React Native는 미리 로드된 광고의 총 개수에 앱 전체 한도를 적용합니다.

• 기본 한도: Google은 메모리에 최대 6개의 미리 로드된 광고를 보관합니다. 이 한도는 모든 형식과 미리 로드 ID에 공유됩니다.
• 권장 버퍼: 각 미리 로드 ID에 대해 미리 로드된 광고 2개

앱이 앱 전체 한도에 도달하면 기존 광고가 캐시에서 폴링되거나 소멸될 때까지 미리 로드된 광고에 대한 백그라운드 요청이 일시중지됩니다. 전체 화면 광고가 화면에 활발하게 표시되는 동안에도 미리 로드가 일시적으로 일시중지됩니다.

폴링 및 광고 표시

광고를 표시하기 전에 RewardedInterstitialAdPreloader.isAdAvailable 메서드를 호출하여 광고를 사용할 수 있는지 확인합니다. 광고를 가져오려면 RewardedInterstitialAdPreloader.pollAd 메서드를 호출합니다.

광고를 표시하려면 사용자가 광고 시청을 완료할 때 보상을 부여하는 onUserEarnedReward 콜백과 함께 show 메서드를 호출합니다. 광고 닫기 또는 표시 실패와 같은 표시 이벤트를 수신하려면 show 메서드를 호출하기 전에 광고 인스턴스에서 adEventCallback 속성을 설정하세요.

다음 예에서는 광고를 표시하기 전에 광고 사용 가능 여부를 확인하고 전체 화면 표시 이벤트를 수신 대기합니다.

export function showPreloadedRewardedInterstitialAd(
  preloadId: string,
  onRewardEarned: (reward: Reward) => void,
  customAdEventCallback?: FullScreenAdEventCallback,
) {
  if (!RewardedInterstitialAdPreloader.isAdAvailable(preloadId)) {
    console.log('No preloaded rewarded interstitial ad available right now.');
    return;
  }

  const ad = RewardedInterstitialAdPreloader.pollAd(preloadId);
  if (!ad) {
    return;
  }

  ad.adEventCallback = {
    // Called when the ad is presented on screen.
    onAdShowedFullScreenContent: () => {
      console.log(
        'Preloaded rewarded interstitial ad showed full screen content.',
      );
      customAdEventCallback?.onAdShowedFullScreenContent?.();
    },
    // Called when the ad is closed by the user.
    onAdDismissedFullScreenContent: () => {
      console.log(
        'Preloaded rewarded interstitial ad dismissed full screen content.',
      );
      customAdEventCallback?.onAdDismissedFullScreenContent?.();
      ad.destroy();
    },
    // Called when presentation fails.
    onAdFailedToShowFullScreenContent: (error) => {
      console.error(
        'Failed to show preloaded rewarded interstitial ad:',
        error,
      );
      customAdEventCallback?.onAdFailedToShowFullScreenContent?.(error);
      ad.destroy();
    },
    // Called when an impression is recorded.
    onAdImpression: () => {
      console.log('Preloaded rewarded interstitial ad recorded an impression.');
      customAdEventCallback?.onAdImpression?.();
    },
    // Called when the user taps the ad.
    onAdClicked: () => {
      console.log('Preloaded rewarded interstitial ad was clicked.');
      customAdEventCallback?.onAdClicked?.();
    },
    // Called when the ad is estimated to have earned money.
    onAdPaid: (adValue) => {
      console.log(
        `Preloaded rewarded interstitial ad paid: ${adValue.amountMicros}` +
          ` ${adValue.currencyCode}`,
      );
      customAdEventCallback?.onAdPaid?.(adValue);
    },
  };

  ad.show(onRewardEarned);
}

메모리와 리소스를 해제하려면 onAdDismissedFullScreenContent 및 onAdFailedToShowFullScreenContent 콜백에서 ad.destroy 메서드를 호출합니다.

대답 정보 읽기

캐시에서 광고를 삭제하지 않고 미리 로드된 다음 광고의 응답 정보를 검사하려면 RewardedInterstitialAdPreloader.peekAdResponseInfo 메서드를 호출합니다.

export function peekRewardedInterstitialAdResponseInfo(
  preloadId: string,
): ResponseInfo | null {
  const responseInfo =
    RewardedInterstitialAdPreloader.peekAdResponseInfo(preloadId);
  if (responseInfo) {
    console.log(
      'Next preloaded rewarded interstitial ad response info:',
      responseInfo,
    );
  }
  return responseInfo;
}

광고가 있으면 peekAdResponseInfo 메서드는 로드된 광고 소스 및 네트워크 어댑터에 관한 정보가 포함된 ResponseInfo 객체를 반환합니다.

선택사항: SSV 콜백 검사

서버 측 확인(SSV) 콜백에서 앱에 사용자 ID 또는 맞춤 리워드 메타데이터와 같은 맞춤 확인 매개변수가 필요한 경우 show 메서드를 호출하기 전에 폴링된 광고 인스턴스에서 serverSideVerificationOptions 속성을 설정하세요.

설정한 값은 SSV 콜백 쿼리 매개변수에 전달됩니다.

• userId: 사용자를 식별하기 위해 user_id 쿼리 매개변수에 전달됩니다.
• customData: custom_data 쿼리 매개변수에 전달하여 커스텀 메타데이터를 전달합니다.

다음 예에서는 광고를 표시하기 전에 보상형 전면 광고 객체에 ServerSideVerificationOptions(customData 및 userId)를 설정합니다.

export function setServerSideVerificationRewardedInterstitial(
  ad: RewardedInterstitialAd,
) {
  ad.serverSideVerificationOptions = {
    userId: 'user_123',
    customData: 'sample_custom_data',
  };
}

핵심 사항: custom_data 쿼리 매개변수 값은 이스케이프된 비율 또는 URL로 인코딩됩니다. 서버에서 SSV 콜백을 처리할 때 이 문자열을 URL 디코딩한 후 처리하세요.

리소스 삭제

세션의 나머지 부분에서 특정 미리 로드 ID에 대한 광고를 더 이상 표시할 필요가 없는 경우 RewardedInterstitialAdPreloader.destroy 메서드를 호출합니다. 이 프로세스는 해당 미리 로드 ID의 미리 로드를 중지하고 사용되지 않은 미리 로드된 광고를 메모리에서 해제합니다.

다음 예에서는 미리 로드를 중지합니다.

export function destroyRewardedInterstitialAdPreloader(preloadId: string) {
  RewardedInterstitialAdPreloader.destroy(preloadId);
}

사용자가 광고를 닫거나 광고가 표시되지 않으면 개별 폴링된 광고 인스턴스를 소멸시킵니다. 자세한 내용은 광고 폴링 및 표시를 참고하세요.

전체 예시 보기

이 섹션에서는 광고 사전 로드의 전체 구현을 다룹니다.

다음 예시 구성요소는 마운트 시 미리 로드를 시작하고, 사용 가능한 광고 수를 추적하며, 미리 로드된 보상형 전면 광고를 표시하는 컨트롤을 제공합니다.

export function RewardedInterstitialScreen() {
  const [numAdsAvailable, setNumAdsAvailable] = useState<number>(0);
  const [status, setStatus] = useState<string>('Preloader idle.');
  const [reward, setReward] = useState<string | null>(null);

  const refreshAdCount = () => {
    const count =
      RewardedInterstitialAdPreloader.getNumAdsAvailable(PRELOAD_ID);
    setNumAdsAvailable(count);
  };

  useEffect(() => {
    // Start preloading ads on component mount
    const started = startRewardedInterstitialAdPreloader(
      REWARDED_INTERSTITIAL_AD_UNIT_ID,
      PRELOAD_ID,
      {
        onAdPreloaded: () => {
          refreshAdCount();
          setStatus('Rewarded interstitial ad preloaded into buffer.');
        },
        onAdFailedToPreload: (error) => {
          setStatus(
            `Failed to preload rewarded interstitial ad: ${error.message}`,
          );
        },
        onAdsExhausted: () => {
          refreshAdCount();
          setStatus('Preload buffer exhausted for rewarded interstitial ads.');
        },
      },
    );
    if (started) {
      setStatus('Preloader started.');
    }

    // Clean up preloader resources on component unmount
    return () => {
      destroyRewardedInterstitialAdPreloader(PRELOAD_ID);
    };
  }, []);

  const handleShowAd = () => {
    setReward(null);
    setStatus('Showing preloaded ad...');
    showPreloadedRewardedInterstitialAd(
      PRELOAD_ID,
      (userReward) => {
        setReward(`${userReward.amount} ${userReward.type}`);
      },
      {
        onAdDismissedFullScreenContent: () => {
          setStatus('Ad dismissed.');
        },
        onAdFailedToShowFullScreenContent: (error) => {
          setStatus(`Failed to show preloaded ad: ${error.message}`);
        },
      },
    );
    refreshAdCount();
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Preload Rewarded Interstitial Ads</Text>
      <Text style={styles.status}>Status: {status}</Text>
      <Text style={styles.status}>Ads Available: {numAdsAvailable}</Text>
      {reward && <Text style={styles.rewardText}>Earned: {reward}</Text>}
      <View style={styles.buttonGroup}>
        <Button
          title="Show Preloaded Ad"
          onPress={handleShowAd}
          disabled={numAdsAvailable === 0}
        />
      </View>
    </View>
  );
}

다음 단계

보상형 전면 광고를 통합한 후 다음 주제를 살펴보세요.

• 노출 수준 광고 수익
• 사용자 개인 정보 보호 및 동의