Flow Point Next.js SDK 가이드

Next.js 앱에서 방문, 유입 경로, activation, revenue 이벤트를 Flow Point 서버로 전송하는 방법을 안내합니다.

Flow Point Next.js SDK는 Next.js 앱에서 방문, 유입 경로, activation, revenue 이벤트를 Flow Point 서버로 전송하는 클라이언트 SDK입니다.

1. SDK 설치

프로젝트에 @flow-point/nextjs를 추가합니다.

npm install @flow-point/nextjs

GitHub 저장소 npm 패키지

2. 환경 변수

브라우저에서 이벤트를 전송하려면 Next.js public 환경 변수에 사이트 키를 설정합니다. SDK를 사용하려면 NEXT_PUBLIC_FLOW_SITE_KEY가 필요합니다.

NEXT_PUBLIC_FLOW_SITE_KEY=site_xxx

3. 방문 기록

앱에 FlowVisit컴포넌트를 한 번 렌더링하면 방문 이벤트가 자동으로 전송됩니다. App Router에서는 app/layout.tsx또는 공통 클라이언트 프로바이더에 추가하는 방식을 권장합니다.

import { FlowVisit } from "@flow-point/nextjs";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="ko">
      <body>
        <FlowVisit />
        {children}
      </body>
    </html>
  );
}

FlowVisit은 클라이언트 컴포넌트이며 내부에서 다음 작업을 수행합니다.

flow_session 쿠키가 없으면 새 세션을 생성합니다.
새 세션이면 UTM, referrer, click id 정보를 traffic-source 이벤트로 전송합니다.
현재 페이지 URL을 visit 이벤트로 전송합니다.

4. Activation / Revenue 이벤트

flow.activation()과 flow.revenue()는 브라우저에서 실행되는 클라이언트 함수입니다. React 컴포넌트에서 사용할 때는 "use client"가 필요합니다.

"use client";

import { flow } from "@flow-point/nextjs";

export function PricingActions() {
  return (
    <>
      <button onClick={() => void flow.activation("feature_used")}>
        기능 사용
      </button>
      <button onClick={() => void flow.revenue("checkout_completed")}>
        결제 완료
      </button>
    </>
  );
}

flow.activation(feature)는 사용자가 핵심 기능을 경험했을 때 호출합니다.
flow.revenue(tag)는 결제, 구매, 구독 전환처럼 매출과 관련된 행동이 발생했을 때 호출합니다.
각 이벤트에는 현재 flow_session과 window.location.href가 함께 전송됩니다.

5. 세션 쿠키

클라이언트 이벤트가 같은 세션을 읽어야 하므로 flow_session 쿠키는 httpOnly로 설정되지 않습니다.

쿠키 이름: flow_session
만료 기간: 1년
쿠키 옵션: sameSite=lax, path=/, max-age=31536000
secure: HTTPS 환경에서는 secure 옵션이 자동으로 추가됩니다.

라이선스: MIT