퀵가이드

이 퀵가이드는 NetFUNNEL React Native 에이전트를 처음 적용하는 개발자가 빠르게 시작할 수 있도록 필수 구현 사항을 간략히 안내합니다.

1. 디렉터리 구조

아래는 예제의 기본 디렉터리 구조입니다. 각 파일은 에이전트 초기화, 대기실 컴포넌트 배치, 진입 요청, 진입 완료 처리를 담당합니다. (화면 이동은 React Navigation을 사용하는 예시입니다.)

├── index.js                  // initialize 호출 - 에이전트 초기화
├── App.tsx                   // WebViewComponent 배치 - 대기실 표시
└── screens/
    ├── MainScreen.tsx        // nfStart 호출 - 진입 요청
    └── EventScreen.tsx       // nfStop 호출 - 진입 완료 처리

2. 에이전트 초기화

React Native 에이전트는 안정적인 동작을 위해 앱 실행 시 가장 먼저 초기화되어야 합니다. 따라서 앱 진입점(index.js)에서 초기화 함수를 호출합니다. (패키지 설치와 자세한 초기화 설정은 통합 가이드를 참고하세요.)

import { AppRegistry } from 'react-native';
import Netfunnel from 'netfunnel-rn-agent';
import App from './App';
import { name as appName } from './app.json';

Netfunnel.initialize({ clientId: '{CLIENT_ID}' });

AppRegistry.registerComponent(appName, () => App);

대기실이 표시될 수 있도록 앱 루트에 Netfunnel.WebViewComponent를 NavigationContainer 다음에 배치합니다.

import React from 'react';
import { View } from 'react-native';
import { NavigationContainer } from '@react-navigation/native';
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import Netfunnel from 'netfunnel-rn-agent';
import MainScreen from './screens/MainScreen';
import EventScreen from './screens/EventScreen';

const Stack = createNativeStackNavigator();

export default function App() {
  return (
    <View style={{ flex: 1 }}>
      <NavigationContainer>
        <Stack.Navigator>
          <Stack.Screen name="Main" component={MainScreen} />
          <Stack.Screen name="Event" component={EventScreen} />
        </Stack.Navigator>
      </NavigationContainer>
      <Netfunnel.WebViewComponent />
    </View>
  );
}

3. 콜백 함수

시작 함수(nfStart, nfStartSection)의 세 번째 파라미터인 콜백 함수에서 넷퍼넬 서버의 응답을 받습니다. 응답은 상태값(status), 상태 코드(statusCode), 메시지(message)를 포함하며, 상태값에 따라 분기 처리합니다.

Success: 진입 또는 우회 응답. 화면 이동·함수 실행 등 기존 서비스 로직을 실행합니다.
Error: 시스템 에러. 원활한 이용을 위해 Success와 동일하게 기존 로직을 실행합니다.
NetworkError: 네트워크 장애. 기존 로직을 실행하거나, 악용 방지를 위해 다시 대기하도록 처리할 수 있습니다.

function nfCallback(response) {
  const { status } = response;

  switch (status) {
    case 'Success':
      // 대상 화면으로 이동
      navigation.navigate('Event');
      break;

    case 'Error':
      // 기존 서비스 로직 실행
      callFunction();
      break;

    case 'NetworkError':
      // 네트워크 에러 안내 후 재시도
      Alert.alert('네트워크 요청에 실패했습니다. 다시 시도합니다.');
      Netfunnel.nfStart('{PROJECT_KEY}', '{SEGMENT_KEY}', function (response) {
        nfCallback(response);
      });
      break;

    default:
      console.log(`[NF] ${JSON.stringify(response)}`);
  }
}

4. 시작 함수

nfStart(기본 제어), nfStartSection(구간 제어)는 대기 상태를 감지하고 필요 시 대기실을 띄우는 함수입니다.

Netfunnel.nfStart('{PROJECT_KEY}', '{SEGMENT_KEY}', function (response) {
  nfCallback(response);
});

5. 종료 함수

nfStop(기본 제어), nfStopSection(구간 제어)은 대기 완료 후 서버에 진입 키를 반납하는 함수입니다. 키를 반납해 다음 사용자가 진입할 수 있게 하며, 일반적으로 서비스 진입 직후 실행합니다.

Netfunnel.nfStop('{PROJECT_KEY}', '{SEGMENT_KEY}');

6. 코드 기반 적용 예시

6.1 MainScreen에서 EventScreen으로 이동

MainScreen의 버튼에서 시작 함수를 호출해 대기열을 적용하고, Success 응답을 받으면 EventScreen으로 이동합니다. EventScreen이 표시되면 종료 함수를 호출해 키를 반납합니다. (기본 제어와 구간 제어의 적용 방식은 동일합니다.)

import React from 'react';
import { Button, View } from 'react-native';
import Netfunnel from 'netfunnel-rn-agent';

export default function MainScreen({ navigation }) {
  const onPressEvent = () => {
    Netfunnel.nfStart('{PROJECT_KEY}', '{SEGMENT_KEY}', function (response) {
      switch (response.status) {
        case 'Success':
        case 'Error':
          // 진입·우회·시스템 에러 응답 시 EventScreen으로 이동
          navigation.navigate('Event');
          break;
      }
    });
  };

  return (
    <View>
      <Button title="Go to Event" onPress={onPressEvent} />
    </View>
  );
}

import React, { useEffect } from 'react';
import { Text, View } from 'react-native';
import Netfunnel from 'netfunnel-rn-agent';

export default function EventScreen() {
  useEffect(() => {
    // 화면 진입 후 진입 키 반납
    Netfunnel.nfStop('{PROJECT_KEY}', '{SEGMENT_KEY}');
  }, []);

  return (
    <View>
      <Text>Event</Text>
    </View>
  );
}

6.2 하나의 화면 안에서 함수를 실행

한 화면 안에서 시작 함수 호출 후, Success 응답에서 서비스 로직(예: 주문 요청)을 처리한 뒤 적절한 위치에서 종료 함수를 실행합니다.

const onPressOrder = () => {
  Netfunnel.nfStart('{PROJECT_KEY}', '{SEGMENT_KEY}', async function (response) {
    if (response.status === 'Success' || response.status === 'Error') {
      await requestOrder();
      // 주문 처리가 끝나면 진입 키 반납
      Netfunnel.nfStop('{PROJECT_KEY}', '{SEGMENT_KEY}');
    }
  });
};