빠른 시작

이 빠른 시작 가이드로 5-10분 안에 NetFUNNEL 4 Node.js Agent를 시작하세요.

이 가이드에서 할 수 있는 것

• URL-Triggered 통합: 트리거 규칙 기반 자동 대기열 제어

통합 방법 선택

통합 방법에 대한 자세한 설명은 통합 방법 개요를 참조하세요.

---

사전 요구사항

• NetFUNNEL 콘솔 액세스
• Node.js 프로젝트 (Node.js 18 이상)
• Express 또는 Nuxt 프레임워크

---

1단계: Client ID 및 Secret Key 가져오기

1. NetFUNNEL 콘솔로 이동
2. 우측 상단의 프로필 아이콘 클릭
3. 통합 자격 증명 (Integration Credentials) 메뉴 선택
4. Client ID 및 Secret Key 복사

---

2단계: 패키지 설치

의존성 추가

package.json에 다음 의존성을 추가합니다. 정확한 주소는 콘솔의 에이전트 탭에서 확인 가능합니다.

{
  "dependencies": {
    "netfunnel-node-agent": "{{AGENT_URL}}"
  }
}

패키지 설치

프로젝트 루트 경로에서 다음 명령어를 실행합니다:

npm install

---

3단계: 미들웨어 적용

프로젝트 구조에 맞게 Express 또는 Nuxt 중 하나를 선택하여 적용합니다.

Express 방식

1. 미들웨어 생성

middleware/netfunnel-middleware.ts 파일을 생성합니다:

import { Netfunnel } from 'netfunnel-node-agent';

export function netfunnelMiddleware(req, res, next) {
  Netfunnel.run(req, res).then(allowed => {
    if (!allowed) {
      return res.redirect(302, req._nfRedirect || '/');
    }
    next();
  });
}

2. 앱에 미들웨어 등록

app.ts에서 NetFUNNEL을 초기화하고 미들웨어를 등록합니다:

import express from 'express';
import { router } from './routes.js';
import { netfunnelMiddleware } from './middleware/netfunnel-middleware.js';
import { Netfunnel } from 'netfunnel-node-agent';

const app = express();
const PORT = 3000;

/* NetFUNNEL 전역 초기화 */
Netfunnel.initialize({
  clientId: '{{CLIENT_ID}}',  // 1단계에서 가져온 Client ID
  secretKey: '{{SECRET_KEY}}'  // 1단계에서 가져온 Secret Key
});

app.use(netfunnelMiddleware);
app.use('/', router);

app.listen(PORT, () => {
  console.log(`[APP] listening on ${PORT} (NetFUNNEL ${Netfunnel.getVersion()})`);
});

Nuxt 방식

1. 미들웨어 생성

server/middleware/netfunnelAgent.ts 파일을 생성합니다:

import { sendRedirect } from 'h3';
import { Netfunnel } from 'netfunnel-node-agent';

export default defineEventHandler(async event => {
  Netfunnel.initialize({
    clientId: '{{CLIENT_ID}}',  // 1단계에서 가져온 Client ID
    secretKey: '{{SECRET_KEY}}'  // 1단계에서 가져온 Secret Key
  });
  
  console.log('[APP] NetFUNNEL Version:', Netfunnel.getVersion());
  
  const allowed = await Netfunnel.run(event.node.req, event.node.res);
  
  if (!allowed) {
    const redirectUrl = (event.node.req as any)._nfRedirect || '/';
    console.log(`Redirecting now to: ${redirectUrl}`);
    return sendRedirect(event, redirectUrl);
  }
});

---

4단계: 트리거 규칙 설정

1. 콘솔에서 세그먼트 생성:

   • NetFUNNEL 콘솔 → Projects → Segment → Create Segment로 이동
   • 세그먼트 이름 입력
   • 진입 상태를 Waiting으로 설정
   • 진입 허용수를 0으로 설정 (테스트용)

2. 트리거 규칙 설정:

   • Trigger Rules 섹션에서 규칙 추가
   • Validator: URL
   • Component: Path 또는 URL
   • Match: Equals, Contains, StartsWith, EndsWith 등
   • Value: 적용할 URL 경로 입력 (예: /checkout, /login)

---

5단계: 테스트

1. 트리거 규칙 테스트: 콘솔의 트리거 규칙 테스트 기능으로 URL이 규칙에 부합하는지 확인
2. 대기실 확인: 규칙에 부합하는 URL로 접속 시 대기실이 표시되는지 확인
3. 진입 확인: 진입 허용수를 증가시켜 정상적으로 진입되는지 확인

---

도움이 필요하신가요?

• 문제 해결: 일반적인 문제 및 해결 방법
• API 참조: 완전한 함수 사양
• 콘솔의 프로젝트/세그먼트 키가 정확히 일치하는지 확인