React Native

1. Plugin Integration

적용할 최신 버전은 CHANGELOG.md 파일을 참고해주세요.

1.1 Plugin 설치

개발하시는 React Native 프로젝트의 폴더로 이동하시어 아래의 명령을 수행하여 plugin 을 설치합니다.

npm install react-native-s2offerwall

iOS 폴더로 이동해 pod install 을 실행합니다. 이때 만약 오류가 발생한다면 Podfile 을 열어서 아래 부분을 수정해주세요.

cd ios
pod install

// 오류 발생시 Podfile 을 열어서 아래의 내용을 수정합니다.
platform :ios, min_ios_version_supported  
--> platform :ios, '16.0' # 하드코딩 값으로 설정합니다.

Plugin 을 사용하기 위해서는 해당 소스 파일에서 아래의 import 문을 넣어주세요.

import { S2Offerwall } from 'react-native-s2offerwall';

1.2 APP ID 설정하기

Android 의 경우에는 AndroidMenifest.xml 파일에 설정하며, iOS 의 경우에는 info.plist 파일에 설정할 수 있습니다. 하지만 이 경우 Native 쪽 파일을 수정해야하므로 그보다는 plugin 이 제공하는 API 를 사용하여 설정하는 것을 권장합니다.

  S2Offerwall.setAppId('YOUR_APP_ID');
  
  // Android 와 iOS 의 APP_ID 를 다르게 설정해야한다면 아래의 함수를 사용하세요.
  S2Offerwall.setAppIdForAndroid('YOUR_APP_ID_FOR_ANDROID');
  S2Offerwall.setAppIdForIOS('YOUR_APP_ID_FOR_IOS');

1.3 SDK 초기화

APP_ID 를 설정한 후 SDK 초기화 함수를 호출합니다.

S2Offerwall.initSdk();

SDK 초기화 성공 또는 실패 여부는 EventListener 를 등록하여 확인할 수 있습니다. initSDK() 호출 전에 설정해야합니다.

// flag : 초기화 성공시 true
S2Offerwall.onInitCompleted((flag) => {
  console.log('S2Offerwall SDK initialized with flag:', flag);
});

// EventListner 를 등록한 후 초기화 함수를 호출합니다.
S2Offerwall.initSdk();

1.4 사용자 식별값 설정하기

광고 참여를 위해서는 사용자 식별값이 설정되어야합니다. 일반적으로 매체의 로그인 ID 가 사용되며 아래의 API 를 호출하여 SDK 에 사용자 식별값을 설정합니다. 이렇게 설정된 식별값은 이후 사용자가 광고 참여를 완료하는 시점에 매체의 서버로 callback 이 호출되는데 그때 pub_user_nm 파라메터로 전달됩니다.

사용자 식별값의 경우 로그인 ID 를 바로 사용하지 마시고 개인 정보 이슈가 없도록 가급적 Hash 또는 암호화된 값으로 전달해주시기 바랍니다.

// 사용자 식별값 설정하기
S2Offerwall.setUserName('USER_IDENTIFIER' [,'화면 표시용 명칭']);

// 사용자 식별값 초기화
S2Offerwall.resetUserName();

SDK v1.0.19 부터 setUserName() 에 displayName 파라메터가 추가되었습니다. 해당 파라메터는 오퍼월내 이벤트에서 랭킹 등을 표시할 때 사용되며 유저의 앱 내 닉네임 등으로 전달해주시면 됩니다. Snap 오퍼월의 다양한 이벤트들을 100% 활용하기 위하여 displayName 파라메터가 필요하므로 가급적 적용해주시기 바랍니다.

유저의 닉네임등이 노출되면 안되는 경우에는 원하시는 형태로 마스킹 처리 후 (예: 우리****) 전달해주시기 바랍니다.

사용자가 광고를 참여하는 시점에 아직 사용자 식별값이 설정되지 않았다면 onLoginRequested() 이벤트가 호출됩니다. 이 이벤트에서 사용자 식별값을 설정하도록 구현해주세요. (3. Sample Code 참고)

2. 오퍼월 띄우기

아래의 함수를 호출하여 오퍼월을 띄웁니다. Android 에서는 S2OfferwallActivity 를 사용하여 오퍼월을 보여주며, iOS 에서는 S2OfferwallViewController 를 modal 창으로 띄워서 오퍼월을 표시합니다.

S2Offerwall.showOfferwall("PLACEMENT_NAME");

플레이스먼트는 Snapplay 사이트에서 설정할 수 있습니다. 그리고 추가적으로 "main" 이라는 특별한 플레이스먼트가 있습니다. 메인 오퍼월은 여러개의 플레이스먼트 오퍼월을 조합하여 하나의 화면에 표시해주는 오퍼월입니다. 메인 오퍼월을 띄우고자 할 때에는 플레이스먼트 이름 대신에 'main' 을 사용합니다.

앱 추적 동의 설정

iOS 의 경우에는 IDFA 수집을 위한 추적 허용을 명시적으로 사용자에게 동의받아야합니다. 앱 추척(App Tracking Transparency, ATT) 동의 창을 띄우기 위해서는 우선 info.plist 파일에 Tracking Usage Description 항목을 작성해야합니다. (iOS의 2.2 APP_ID 설정하기 참고).

이후 앱 추적 동의 창을 띄우기 위한 아래의 함수를 호출합니다. 앱 추적 동의 창은 앱이 시작되는 시점에 띄우는 것을 권장합니다. 아래 함수 호출시 Android 의 경우에는 아무런 동작을 하지 않습니다.

S2Offerwall.presentATTPopup();

3. Sample Code

아래는 버튼을 클릭하면 Offerwall 을 띄우는 가장 간단한 구현 코드입니다.

import { useEffect } from 'react';
import { View, StyleSheet, Button } from 'react-native';
import { S2Offerwall } from 'react-native-s2offerwall';

export default function App() {
  const handleShowOfferwall = async () => {
    try {
      await S2Offerwall.showOfferwall('main');
    } catch (error) {
      console.error(error);
    }
  };

  useEffect(() => {
    S2Offerwall.presentATTPopup();
    
    S2Offerwall.setAppIdForAndroid(
      'ANDROID_APP_ID'
    );
    S2Offerwall.setAppIdForIOS(
      'IOS_APP_ID'
    );

    S2Offerwall.onInitCompleted((flag) => {
      console.log('S2Offerwall SDK initialized with flag:', flag);
    });

    // 이벤트 구독
    S2Offerwall.onLoginRequested((event) => {
      if (event.name === 'onLoginRequested') {
        S2Offerwall.setUserName('USER_LOGIN_ID_HASHED_IF_POSSIBLE','화면 표시용 이름');
        S2Offerwall.resetUserName();
      }
    });

    S2Offerwall.initSdk();

    // 컴포넌트 언마운트 시 구독 해제
    return () => {
      S2Offerwall.removeAllListeners();
    };
  }, []);

  return (
    <View style={styles.container}>
      <Button title="Offerwall" onPress={handleShowOfferwall} />
    </View>
  );
}

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