보상형 광고 - Ad Control Help Center

개요

보상형 광고는 사용자가 동영상 광고를 끝까지 시청하면 게임 내 재화, 생명, 힌트 등의 보상을 제공하는 전면 동영상 광고입니다.

주요 특징

전면 화면을 차지하는 동영상 광고
사용자가 광고를 완전히 시청한 경우에만 보상 제공
사용자가 직접 광고 시청을 선택 (예: “동영상 보고 생명 받기” 버튼)
보상 타입과 수량을 설정 가능

개발 환경에서는 테스트 유닛 ID를 사용하세요.

구현 방법

보상형 광고는 두 가지 방식으로 구현할 수 있습니다:

클래스 방식 - AdropRewardedAd 클래스를 직접 사용
Hook 방식 - useAdropRewardedAd Hook을 사용 (권장)

Hook 방식 구현 (권장)

React Hook을 사용하여 더 간결하고 React스러운 방식으로 구현할 수 있습니다.

기본 예제

import React, { useCallback } from 'react';
import { Button, View, Text, StyleSheet } from 'react-native';
import { useAdropRewardedAd } from 'adrop-ads-react-native';

const RewardedAdScreen = () => {
  const unitId = 'YOUR_UNIT_ID'; // 또는 테스트 유닛 ID

  const {
    load,
    show,
    reset,
    isLoaded,
    isOpened,
    isClosed,
    isEarnRewarded,
    reward,
    errorCode,
    isReady
  } = useAdropRewardedAd(unitId);

  // 컴포넌트 마운트 시 광고 로드
  React.useEffect(() => {
    if (isReady) {
      load();
    }
  }, [isReady, load]);

  // 광고가 닫힌 후 다음 광고 로드
  React.useEffect(() => {
    if (isClosed) {
      console.log('광고가 닫혔습니다');
      // 다음 광고 미리 로드
      reset();
      load();
    }
  }, [isClosed, reset, load]);

  // 보상 처리
  React.useEffect(() => {
    if (isEarnRewarded && reward) {
      console.log(`보상 획득 - 타입: ${reward.type}, 수량: ${reward.amount}`);
      grantReward(reward.type, reward.amount);
    }
  }, [isEarnRewarded, reward]);

  const handleShowAd = useCallback(() => {
    if (isLoaded) {
      show();
    } else {
      console.log('광고가 아직 로드되지 않았습니다');
    }
  }, [isLoaded, show]);

  const grantReward = (type: number, amount: number) => {
    // 사용자에게 보상 지급
    console.log(`보상 지급: 타입=${type}, 수량=${amount}`);
    // 실제 보상 지급 로직 구현
  };

  return (
    <View style={styles.container}>
      <Button
        title="광고 로드"
        onPress={load}
        disabled={!isReady}
      />
      <Button
        title="광고 보기"
        onPress={handleShowAd}
        disabled={!isLoaded}
      />
      {errorCode && (
        <Text style={styles.error}>에러: {errorCode}</Text>
      )}
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    gap: 16,
  },
  error: {
    color: 'red',
  },
});

export default RewardedAdScreen;

useAdropRewardedAd Hook

Hook을 사용하면 광고 상태를 자동으로 관리할 수 있습니다.

파라미터

string | null

애드컨트롤 콘솔에서 발급받은 광고 유닛 ID. null을 전달하면 광고 인스턴스가 생성되지 않습니다.

반환값

() => void

광고를 요청합니다.

() => void

광고를 표시합니다.

() => void

광고 상태를 초기화하고 새로운 광고 인스턴스를 생성합니다.

boolean

광고가 로드되어 표시 가능한 상태인지 여부

boolean

광고가 화면에 표시되었는지 여부

boolean

광고가 닫혔는지 여부

boolean

사용자가 보상을 획득했는지 여부

{ type: number, amount: number } | undefined

보상 정보 (타입과 수량)

string | undefined

에러 코드 (에러 발생 시에만 값이 있음)

boolean

광고 인스턴스가 준비되어 사용 가능한 상태인지 여부

boolean

광고가 클릭되었는지 여부

boolean

광고가 표시된 상태에서 뒤로 가기 버튼이 눌렸는지 여부. Android 전용.

BrowserTarget | undefined

로드된 광고의 브라우저 타겟 설정 (BrowserTarget.EXTERNAL 또는 BrowserTarget.INTERNAL).

클래스 방식 구현

AdropRewardedAd 클래스를 직접 사용하여 광고를 구현할 수 있습니다.

기본 예제

import React, { useEffect, useState, useCallback } from 'react';
import { Button, View, Text, StyleSheet } from 'react-native';
import { AdropRewardedAd, AdropListener } from 'adrop-ads-react-native';

const RewardedAdScreen = () => {
  const [rewardedAd, setRewardedAd] = useState<AdropRewardedAd | null>(null);
  const [isLoaded, setIsLoaded] = useState(false);

  useEffect(() => {
    // 1. AdropRewardedAd 인스턴스 생성
    const ad = new AdropRewardedAd('YOUR_UNIT_ID');

    // 2. Listener 설정
    const listener: AdropListener = {
      onAdReceived: (ad) => {
        console.log('광고 수신 완료:', ad.unitId);
        setIsLoaded(true);
      },
      onAdFailedToReceive: (ad, errorCode) => {
        console.log('광고 수신 실패:', errorCode);
        setIsLoaded(false);
      },
      onAdDidPresentFullScreen: (ad) => {
        console.log('광고 화면 표시됨:', ad.unitId);
      },
      onAdDidDismissFullScreen: (ad) => {
        console.log('광고 화면 닫힘:', ad.unitId);
        setIsLoaded(false);
        // 다음 광고 미리 로드
        ad.load();
      },
      onAdEarnRewardHandler: (ad, type, amount) => {
        console.log(`보상 획득 - 타입: ${type}, 수량: ${amount}`);
        grantReward(type, amount);
      },
      onAdClicked: (ad) => {
        console.log('광고 클릭됨:', ad.unitId);
      },
      onAdImpression: (ad) => {
        console.log('광고 노출됨:', ad.unitId);
      },
      onAdFailedToShowFullScreen: (ad, errorCode) => {
        console.log('광고 표시 실패:', errorCode);
      },
    };

    ad.listener = listener;
    setRewardedAd(ad);

    // 3. 광고 로드
    ad.load();

    // 컴포넌트 언마운트 시 정리
    return () => {
      ad.destroy();
    };
  }, []);

  const handleShowAd = useCallback(() => {
    if (rewardedAd && isLoaded) {
      rewardedAd.show();
    } else {
      console.log('광고가 아직 로드되지 않았습니다');
    }
  }, [rewardedAd, isLoaded]);

  const grantReward = (type: number, amount: number) => {
    // 사용자에게 보상 지급
    console.log(`보상 지급: 타입=${type}, 수량=${amount}`);
    // 실제 보상 지급 로직 구현
  };

  return (
    <View style={styles.container}>
      <Button
        title="광고 로드"
        onPress={() => rewardedAd?.load()}
      />
      <Button
        title="광고 보기"
        onPress={handleShowAd}
        disabled={!isLoaded}
      />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    gap: 16,
  },
});

export default RewardedAdScreen;

AdropRewardedAd 클래스

생성자

new AdropRewardedAd(unitId: string)

string

애드컨트롤 콘솔에서 발급받은 광고 유닛 ID

프로퍼티

string

광고 유닛 ID (읽기 전용)

boolean

광고가 로드되어 표시 가능한 상태인지 여부 (읽기 전용)

string

로드된 광고의 크리에이티브 ID (읽기 전용)

string

광고 트랜잭션 ID (읽기 전용)

string

로드된 광고의 캠페인 ID (읽기 전용)

string

로드된 광고의 랜딩 URL (읽기 전용)

BrowserTarget

로드된 광고의 브라우저 타겟 설정 (BrowserTarget.EXTERNAL 또는 BrowserTarget.INTERNAL) (읽기 전용)

AdropListener | undefined

광고 이벤트를 수신할 리스너

메서드

void

광고를 요청합니다. 광고 로드 결과는 리스너의 onAdReceived 또는 onAdFailedToReceive로 전달됩니다.

void

광고를 표시합니다.

void

광고 리소스를 해제합니다. 컴포넌트 언마운트 시 호출해야 합니다.

AdropListener 인터페이스

모든 콜백은 선택 사항입니다. 필요한 콜백만 설정하세요.

콜백

void

광고 수신에 성공했을 때 호출됩니다. 이 시점부터 show() 메서드로 광고를 표시할 수 있습니다.

void

광고 수신에 실패했을 때 호출됩니다. 에러 코드를 통해 실패 원인을 확인할 수 있습니다.

void

광고가 노출되어 노출 기록이 전송되었을 때 호출됩니다.

void

사용자가 광고를 클릭했을 때 호출됩니다.

void

광고 화면이 표시되기 직전에 호출됩니다.

void

광고 화면이 완전히 표시된 후 호출됩니다.

void

광고 화면이 닫히기 직전에 호출됩니다.

void

광고 화면이 완전히 닫힌 후 호출됩니다. 다음 광고를 미리 로드할 수 있습니다.

void

광고 표시에 실패했을 때 호출됩니다. 에러 코드를 통해 실패 원인을 확인할 수 있습니다.

void

광고가 표시된 상태에서 사용자가 뒤로 가기 버튼을 눌렀을 때 호출됩니다. Android 전용.

리워드 전용 콜백

void

사용자가 광고를 끝까지 시청하여 보상을 획득했을 때 호출됩니다.

type: 애드컨트롤 콘솔에서 설정한 보상 타입 (정수 값)
amount: 애드컨트롤 콘솔에서 설정한 보상 수량 (정수 값)

보상 처리

Hook 방식에서 보상 처리

const RewardedAdScreen = () => {
  const { isEarnRewarded, reward } = useAdropRewardedAd('YOUR_UNIT_ID');

  useEffect(() => {
    if (isEarnRewarded && reward) {
      // 보상 지급 처리
      console.log(`보상 획득 - 타입: ${reward.type}, 수량: ${reward.amount}`);
      grantReward(reward.type, reward.amount);
    }
  }, [isEarnRewarded, reward]);

  const grantReward = (type: number, amount: number) => {
    // 사용자에게 보상 지급
    // 예: 게임 재화 추가, 생명 회복 등
  };

  // ...
};

클래스 방식에서 보상 처리

const listener: AdropListener = {
  onAdEarnRewardHandler: (ad, type, amount) => {
    console.log(`보상 획득 - 타입: ${type}, 수량: ${amount}`);
    grantReward(type, amount);
  },
  // 기타 콜백들...
};

const grantReward = (type: number, amount: number) => {
  // 사용자에게 보상 지급
  // 예: 게임 재화 추가, 생명 회복 등
};

서버 측 검증

서버에서 보상 지급을 검증하여 부정 행위를 방지할 수 있습니다. setServerSideVerificationOptions()를 사용하여 서버 측 검증 콜백에 포함될 사용자 및 커스텀 데이터를 전달합니다.

서버에서 SSV 콜백을 수신하려면 콘솔 [관리] > [연동] > 리워드 광고 SSV에서 콜백 URL을 등록해야 해요. 여기서 설정한 userId와 customData는 해당 URL로 전송되는 암호화 페이로드에 포함됩니다. 페이로드 복호화 및 설정 방법은 리워드 광고 SSV 가이드를 참고하세요.

설정

import { AdropRewardedAd } from 'adrop-ads-react-native'

const rewardedAd = new AdropRewardedAd('YOUR_UNIT_ID')

// 광고를 표시하기 전에 서버 측 검증 옵션 설정
rewardedAd.setServerSideVerificationOptions({
  userId: 'user_12345',
  customData: 'extra_info',
})

rewardedAd.listener = {
  onAdReceived: (ad) => {
    ad.show()
  },
  onAdEarnRewardHandler: (ad, type, amount) => {
    // 클라이언트 측 콜백 (선택사항)
    // 서버 측 검증 콜백도 전송됩니다
    console.log(`보상 획득: type=${type}, amount=${amount}`)
  },
}

rewardedAd.load()

ServerSideVerificationOptions

type ServerSideVerificationOptions = {
  userId?: string
  customData?: string
}

속성:

userId (string, optional): 서버 콜백에 전송되는 사용자 식별자
customData (string, optional): 서버 콜백에 전송되는 커스텀 데이터

백필 폴백 경로에서는 customData가 base64url로 sanitize되어 전달됩니다(+→-, /→_, = 제거, 백필 1.12.1+). customData에 base64 페이로드를 담는 경우 서버에서 base64url로 디코딩하세요.

setServerSideVerificationOptions()는 load() 전에 호출해야 합니다. 옵션은 사용자가 보상을 획득할 때 서버로 전송됩니다.

테스트

테스트 유닛 ID

개발 중에는 항상 테스트 유닛 ID를 사용하세요. 실제 유닛 ID로 테스트하면 무효 트래픽으로 간주되어 계정이 정지될 수 있습니다.

// Hook 방식
const unitId = __DEV__ ? 'TEST_UNIT_ID' : 'YOUR_PRODUCTION_UNIT_ID';
const rewardedAd = useAdropRewardedAd(unitId);

// 클래스 방식
const unitId = __DEV__ ? 'TEST_UNIT_ID' : 'YOUR_PRODUCTION_UNIT_ID';
const ad = new AdropRewardedAd(unitId);

에러 처리

Hook 방식에서 에러 처리

const RewardedAdScreen = () => {
  const { load, errorCode, reset } = useAdropRewardedAd('YOUR_UNIT_ID');

  useEffect(() => {
    if (errorCode) {
      console.log('광고 에러:', errorCode);
      // 에러 타입에 따른 처리
      if (errorCode === AdropErrorCode.network) {
        // 네트워크 에러: 재시도
        setTimeout(() => {
          reset();
          load();
        }, 3000);
      }
    }
  }, [errorCode, reset, load]);

  // ...
};

클래스 방식에서 에러 처리

const listener: AdropListener = {
  onAdFailedToReceive: (ad, errorCode) => {
    console.log('광고 수신 실패:', errorCode);
    if (errorCode === AdropErrorCode.network) {
      // 네트워크 에러: 3초 후 재시도
      setTimeout(() => {
        ad.load();
      }, 3000);
    }
  },
  onAdFailedToShowFullScreen: (ad, errorCode) => {
    console.log('광고 표시 실패:', errorCode);
    Alert.alert('알림', '광고를 표시할 수 없습니다. 나중에 다시 시도해주세요.');
  },
  // 기타 콜백들...
};

모범 사례

1. 광고 미리 로드하기

사용자 경험을 위해 광고를 미리 로드해두는 것이 좋습니다.

// Hook 방식
const RewardedAdScreen = () => {
  const { load, isClosed, reset, isReady } = useAdropRewardedAd('YOUR_UNIT_ID');

  // 컴포넌트 마운트 시 광고 로드
  useEffect(() => {
    if (isReady) {
      load();
    }
  }, [isReady, load]);

  // 광고가 닫힌 후 다음 광고 미리 로드
  useEffect(() => {
    if (isClosed) {
      reset();
      load();
    }
  }, [isClosed, reset, load]);

  // ...
};

2. 광고 준비 상태 확인

광고가 로드되었는지 확인하고 UI를 업데이트합니다.

const RewardedAdScreen = () => {
  const { isLoaded, show } = useAdropRewardedAd('YOUR_UNIT_ID');

  return (
    <View>
      <Button
        title={isLoaded ? "동영상 보고 생명 받기" : "광고 로딩중..."}
        onPress={show}
        disabled={!isLoaded}
      />
    </View>
  );
};

3. 메모리 관리

컴포넌트 언마운트 시 광고 리소스를 정리합니다.

// Hook 방식은 자동으로 정리됨
const { ... } = useAdropRewardedAd('YOUR_UNIT_ID');

// 클래스 방식은 수동으로 정리 필요
useEffect(() => {
  const ad = new AdropRewardedAd('YOUR_UNIT_ID');
  // ...

  return () => {
    ad.destroy();
  };
}, []);

4. 에러 핸들링

적절한 에러 처리로 사용자 경험을 개선합니다.

const RewardedAdScreen = () => {
  const { errorCode, reset, load } = useAdropRewardedAd('YOUR_UNIT_ID');

  useEffect(() => {
    if (errorCode) {
      // 사용자에게 에러 알림
      Alert.alert('알림', '광고를 불러올 수 없습니다.');

      // 네트워크 에러인 경우 재시도
      if (errorCode === AdropErrorCode.network) {
        setTimeout(() => {
          reset();
          load();
        }, 3000);
      }
    }
  }, [errorCode, reset, load]);

  // ...
};

완전한 예제

Hook 방식 완전한 예제

import React, { useEffect, useCallback } from 'react';
import {
  Button,
  View,
  Text,
  StyleSheet,
  Alert,
  ActivityIndicator
} from 'react-native';
import { useAdropRewardedAd } from 'adrop-ads-react-native';

const RewardedAdScreen = () => {
  const unitId = __DEV__ ? 'TEST_UNIT_ID' : 'YOUR_PRODUCTION_UNIT_ID';

  const {
    load,
    show,
    reset,
    isLoaded,
    isOpened,
    isClosed,
    isEarnRewarded,
    reward,
    errorCode,
    isReady
  } = useAdropRewardedAd(unitId);

  // 컴포넌트 마운트 시 광고 로드
  useEffect(() => {
    if (isReady) {
      console.log('광고 인스턴스 준비 완료, 광고 로드 시작');
      load();
    }
  }, [isReady, load]);

  // 광고가 표시될 때
  useEffect(() => {
    if (isOpened) {
      console.log('광고가 표시되었습니다');
      // 배경 음악 일시정지 등
    }
  }, [isOpened]);

  // 광고가 닫힌 후 다음 광고 미리 로드
  useEffect(() => {
    if (isClosed) {
      console.log('광고가 닫혔습니다');
      // 배경 음악 재개 등

      // 다음 광고 미리 로드
      reset();
      load();
    }
  }, [isClosed, reset, load]);

  // 보상 처리
  useEffect(() => {
    if (isEarnRewarded && reward) {
      console.log(`보상 획득 - 타입: ${reward.type}, 수량: ${reward.amount}`);
      grantReward(reward.type, reward.amount);
    }
  }, [isEarnRewarded, reward]);

  // 에러 처리
  useEffect(() => {
    if (errorCode) {
      console.log('광고 에러:', errorCode);

      // 네트워크 에러인 경우 재시도
      if (errorCode === AdropErrorCode.network) {
        Alert.alert(
          '네트워크 오류',
          '광고를 불러올 수 없습니다. 3초 후 재시도합니다.',
          [{ text: '확인' }]
        );

        setTimeout(() => {
          reset();
          load();
        }, 3000);
      } else {
        Alert.alert('오류', `광고 오류: ${errorCode}`);
      }
    }
  }, [errorCode, reset, load]);

  const handleShowAd = useCallback(() => {
    if (isLoaded) {
      show();
    } else {
      Alert.alert('알림', '광고가 아직 로드되지 않았습니다.');
    }
  }, [isLoaded, show]);

  const grantReward = (type: number, amount: number) => {
    // 사용자에게 보상 지급
    Alert.alert(
      '보상 획득!',
      `타입: ${type}, 수량: ${amount}`,
      [{ text: '확인' }]
    );

    // 실제 보상 지급 로직 구현
    // 예: 게임 재화 추가, 생명 회복 등
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>보상형 광고</Text>

      {!isReady && (
        <View style={styles.loadingContainer}>
          <ActivityIndicator size="large" color="#0000ff" />
          <Text style={styles.loadingText}>광고 초기화 중...</Text>
        </View>
      )}

      <View style={styles.buttonContainer}>
        <Button
          title="광고 로드"
          onPress={load}
          disabled={!isReady}
        />
      </View>

      <View style={styles.buttonContainer}>
        <Button
          title={isLoaded ? "동영상 보고 생명 받기" : "광고 로딩중..."}
          onPress={handleShowAd}
          disabled={!isLoaded}
        />
      </View>

      <View style={styles.statusContainer}>
        <Text style={styles.statusText}>
          상태: {isLoaded ? '준비됨' : '로딩중'}
        </Text>
        {errorCode && (
          <Text style={styles.errorText}>에러: {errorCode}</Text>
        )}
      </View>
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    padding: 20,
    backgroundColor: '#f5f5f5',
  },
  title: {
    fontSize: 24,
    fontWeight: 'bold',
    marginBottom: 30,
  },
  loadingContainer: {
    alignItems: 'center',
    marginBottom: 20,
  },
  loadingText: {
    marginTop: 10,
    color: '#666',
  },
  buttonContainer: {
    width: '100%',
    marginVertical: 8,
  },
  statusContainer: {
    marginTop: 30,
    alignItems: 'center',
  },
  statusText: {
    fontSize: 16,
    color: '#333',
  },
  errorText: {
    fontSize: 14,
    color: 'red',
    marginTop: 8,
  },
});

export default RewardedAdScreen;

백필 광고

백필 광고를 사용하려면 네이티브 플랫폼(Android/iOS)에 백필 의존성이 추가되어 있어야 합니다.

백필 광고가 활성화되면 직광고를 사용할 수 없을 때 SDK가 자동으로 백필 광고로 폴백합니다. 리스너에서 백필 관련 에러 코드를 처리할 수 있습니다.

rewardedAd.listener = {
  onAdReceived: (ad) => {
    console.log('광고 로드됨:', ad.creativeId)
  },
  onAdFailedToReceive: (ad, errorCode) => {
    switch (errorCode) {
      case AdropErrorCode.adNoFill:
        console.log('직광고 없음, 백필 광고 요청 중...')
        break
      case AdropErrorCode.backfillNoFill:
        console.log('백필 광고도 없습니다')
        break
      default:
        console.log('광고 로드 실패:', errorCode)
    }
  },
}

전면 광고

전면 광고 구현 가이드

팝업 광고

팝업 광고 구현 가이드

네이티브 광고

네이티브 광고 구현 가이드

에러 코드

에러 코드 레퍼런스

개요

주요 특징

구현 방법

Hook 방식 구현 (권장)

기본 예제

useAdropRewardedAd Hook

파라미터

반환값

클래스 방식 구현

기본 예제

AdropRewardedAd 클래스

생성자

프로퍼티

메서드

AdropListener 인터페이스

콜백

리워드 전용 콜백

보상 처리

Hook 방식에서 보상 처리

클래스 방식에서 보상 처리

서버 측 검증

설정

ServerSideVerificationOptions

테스트

테스트 유닛 ID

에러 처리

Hook 방식에서 에러 처리

클래스 방식에서 에러 처리

모범 사례

1. 광고 미리 로드하기

2. 광고 준비 상태 확인

3. 메모리 관리

4. 에러 핸들링

완전한 예제

Hook 방식 완전한 예제

백필 광고

관련 문서

전면 광고

팝업 광고

네이티브 광고

에러 코드