보상형 광고 설정

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

보상형 광고는 동영상 광고, 플레이어블 광고, 설문조사와 상호작용하는 사용자에게 인앱 상품을 리워드로 제공합니다. 자세한 내용은 보상형 광고 단위 개요를 참고하세요.

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

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

기본 요건

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

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

Android

ca-app-pub-3940256099942544/5224354917

iOS

ca-app-pub-3940256099942544/1712485313

광고 사전 로드 이해하기

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

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

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

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

미리 로드 시작

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

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

사전 로드 ID는 광고 사전 로드 구성을 고유하게 식별하는 문자열입니다. 앱에서 단일 미리 로드 구성에 광고 단위 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는 모든 광고 단위 및 미리 로드 ID에서 미리 로드된 총 광고 수에 앱 전체 한도를 적용합니다.

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

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

폴링 및 광고 표시

광고를 표시하기 전에 RewardedAdPreloader.isAdAvailable 메서드를 호출하여 광고가 사용 가능한지 확인합니다. 광고를 가져오려면 RewardedAdPreloader.pollAd 메서드를 호출합니다.

광고 닫기 또는 표시 실패와 같은 표시 이벤트를 수신 대기하려면 show 메서드를 호출하기 전에 광고 인스턴스에서 adEventCallback 속성을 설정하세요.

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

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

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

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

  ad.show(onRewardEarned);
}

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

대답 정보 읽기

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

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

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

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

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

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

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

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

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

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

리소스 삭제

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

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

export function destroyRewardedAdPreloader(preloadId: string) {
  RewardedAdPreloader.destroy(preloadId);
}

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

전체 예시 보기

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

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

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

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

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

  const handleShowAd = () => {
    setReward(null);
    setStatus('Showing preloaded ad...');
    showPreloadedRewardedAd(
      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 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>
  );
}

다음을 바꿉니다.

• REWARDED_AD_UNIT_ID를 광고 단위 ID로 교체
• PRELOAD_ID를 미리 로드 도구 ID로 바꿉니다.

다음 단계

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

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