Nodus SDK

Next.js에서 방문, 활성화, 매출 이벤트를 Nodus 서버로 전송하는 SDK입니다.

설치

npm install @nodus-lib/nodus

환경 변수

NODUS_SITE_KEY=site_xxx

브라우저 클라이언트에서 이벤트를 보낼 때는 Next.js public 환경 변수도 사용할 수 있습니다.

NEXT_PUBLIC_NODUS_SITE_KEY=site_xxx

방문 로그 설정

방문 로그는 Next.js 요청 정보를 사용하므로 서버의 Proxy 또는 Middleware에서 설정합니다.

Next.js 16 이상

Next.js 16부터 middleware.ts는 proxy.ts로 이름이 변경되었습니다.

import { nodus_visit } from "@nodus-lib/nodus/server";
import type { NextRequest } from "next/server";

export function proxy(request: NextRequest) {
  return nodus_visit(request);
}

export const config = {
  matcher: [
    "/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
  ],
};

Next.js 15 이하

Next.js 15 이하에서는 middleware.ts를 사용합니다.

import { nodus_visit } from "@nodus-lib/nodus/server";
import type { NextRequest } from "next/server";

export function middleware(request: NextRequest) {
  return nodus_visit(request);
}

export const config = {
  matcher: [
    "/((?!api|_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
  ],
};

nodus_visit은 nodus_session 쿠키를 생성하거나 재사용하고, 현재 URL과 referer를 방문 이벤트로 전송합니다.

AARRR 퍼널 이벤트

nodus_activation과 nodus_revenue는 AARRR 퍼널 분석에서 참고한 이벤트입니다.

• nodus_activation: 사용자가 핵심 기능을 경험했을 때 기록합니다.
• nodus_revenue: 결제, 구매, 구독 전환처럼 매출과 관련된 행동을 기록합니다.

이 함수들은 브라우저에서 실행되는 클라이언트 전용 함수입니다. React 컴포넌트에서 사용할 때는 "use client"가 필요합니다.

"use client";

import { nodus_activation, nodus_revenue } from "@nodus-lib/nodus/client";

export function PricingActions() {
  return (
    <>
      <button onClick={() => nodus_activation("무료_체험_시작_클릭")}>
        Start
      </button>
      <button onClick={() => nodus_revenue("결제_완료")}>
        Paid
      </button>
    </>
  );
}

세션

• 쿠키 이름: nodus_session
• 쿠키 수명: 1년
• 쿠키 옵션: sameSite: "lax", secure: true, path: "/"
• 서버와 클라이언트는 같은 nodus_session 쿠키를 사용합니다.

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

라이선스

MIT