Vercel Flags 날짜 조건 설정: 이벤트 페이지 기간별 노출 방법

이벤트 화면과 신청 처리를 따로 검증하세요

아래는 본문의 공식 조건을 실제 작업으로 연결한 편집부 판단표입니다. 계정에서 확인한 결과가 아니므로 자신의 환경에서 조건과 증거를 기록하세요.

이 글의 실무 점검표 CSV 다운로드 — 설정·기대값·실제 결과·증거·후속 작업을 따로 기록하는 빈 양식입니다. 제품 지원 상태나 시험 성공을 증명하는 자료는 아닙니다.

Vercel Flags 날짜 조건은 예약 작업과 어떻게 다른가요?

Vercel Flags는 timestamp 속성으로 날짜와 시각에 따른 타기팅을 지원합니다. 앱이 전달하는 값과 규칙의 기준 시각을 비교하므로, “예약 시각에 파일을 새로 배포하는 작업”과 다릅니다. 현재 시각 대신 가입 시각을 전달하면 가입일 기준 대상 선정에도 사용할 수 있습니다. 근거: timestamp 속성 공식 발표

기간 노출은 다음 구조로 생각하면 쉽습니다. 서버 요청 → 현재 시각 전달 → 날짜 규칙 평가 → 페이지 표시 또는 대체 안내입니다. 이미 열린 브라우저 화면을 종료 시각에 자동으로 바꾸려면 별도의 새로고침·재조회 설계도 필요합니다.

한국 시간의 시작·종료 시각부터 확정하세요

예시는 2026년 10월 15일 오전 9시부터 10월 21일 하루가 끝날 때까지 노출하는 이벤트입니다. “10월 21일까지”를 23:59:59로 표현하기보다 다음 날 0시를 제외하는 범위로 정하면 밀리초 경계가 명확합니다.

Vercel 대시보드 날짜 선택기는 로컬 시간대를 사용합니다. 운영자의 브라우저 시간대가 한국인지 확인하고, CLI에서는 Z 또는 명시적인 UTC 오프셋으로 시각을 표현하세요. after·before는 경계를 제외하고 at-or-after·at-or-before는 포함합니다. 근거: 날짜 선택기·비교 연산자

대시보드에서 timestamp 속성과 기간 규칙 만들기

1. 대상 프로젝트: Vercel에서 이벤트 앱의 프로젝트를 열고 Flags로 이동합니다.
2. 엔터티: Entities에서 system을 만들거나 기존 엔터티를 선택합니다.
3. 속성: time을 추가하고 타입을 timestamp로 설정합니다.
4. 플래그: Boolean 플래그 event-page를 만들고 적용할 환경을 선택합니다.
5. 한 규칙의 두 조건: system.time에 시작 이상과 종료 미만을 함께 넣고 결과를 On으로 정합니다.
6. 규칙 밖 결과: 기간 조건에 맞지 않을 때의 fallback outcome을 Off로 정합니다.
7. 저장·검토: 시간대·대상 환경·기존 규칙·직접 타기팅을 확인하고 변경 내용을 저장합니다.

Timestamp 속성의 앱 입력값은 Unix epoch 밀리초입니다. Date.now()가 이 단위를 반환하며, 초 단위 값을 그대로 넣으면 의도한 날짜와 다른 값이 됩니다. 엔터티와 속성 이름도 설정과 코드에서 일치해야 합니다. 근거: 엔터티·timestamp 값 형식

CLI에서 같은 날짜 범위 설정하기

다음 명령은 독자의 Vercel 프로젝트 설정을 변경하는 예시입니다. 최신 CLI에서 지원 여부를 확인하고 연결된 팀·프로젝트를 점검한 뒤 사용하세요. 기존 system 엔터티나 event-page 플래그가 있다면 중복 생성하지 않습니다.

vercel flags entities create system --label System --attribute time:timestamp
vercel flags create event-page
vercel flags rules add event-page --environment preview \
  --condition system.time:at-or-after:2026-10-15T00:00:00Z \
  --condition system.time:before:2026-10-21T15:00:00Z \
  --variant on --message "KST event window preview"
vercel flags rules ls event-page --environment preview

반복한 --condition은 두 조건을 모두 만족해야 하는 규칙을 만듭니다. Preview에서 확인한 설정이 Production에 자동으로 동일하게 적용된다고 가정하지 마세요. 운영 적용 때는 환경을 명시하고 규칙 밖 결과와 상위 규칙도 다시 확인합니다. 근거: CLI 생성·복수 조건·환경 옵션

Next.js에서 현재 시각 전달하기

사전 조건은 Vercel에 연결된 Next.js 프로젝트와 Flags SDK입니다. 로컬 프로젝트 연결·인증은 공식 quickstart에 따라 vercel link 후 vercel env pull로 준비할 수 있습니다. 환경 파일에는 자격증명이 들어갈 수 있으므로 저장소에 커밋하지 않습니다. 필요한 패키지는 pnpm add flags @flags-sdk/vercel로 설치합니다. 근거: 프로젝트 연결·로컬 OIDC 준비

다음은 lib/event-flags.ts에 둘 수 있는 구현 예시입니다. 앱의 기존 플래그 정의와 통합하고 event-page 키를 대시보드와 일치시키세요.

import { dedupe, flag } from 'flags/next';
import { vercelAdapter } from '@flags-sdk/vercel';

type EventContext = { system: { time: number } };

const readEventContext = dedupe(async (): Promise<EventContext> => {
  const requestTimeMs = Date.now();
  return { system: { time: requestTimeMs } };
});

export const isEventVisible = flag<boolean, EventContext>({
  key: 'event-page',
  adapter: vercelAdapter(),
  identify: readEventContext,
});

identify가 평가 문맥을 전달하고 dedupe가 같은 요청 안에서 문맥을 한 번 계산하게 합니다. 여러 플래그를 사용할 때 동일한 시각을 공유할 수 있습니다. 서버 현재 시각은 요청마다 계산하고 모듈 최상단 상수나 공유 캐시로 고정하지 마세요. 근거: 어댑터·identify·요청 단위 dedupe

페이지를 요청 시점에 평가하고 기간 밖 안내 표시하기

다음은 app/event/page.tsx의 최소 예시입니다. 이벤트가 진행 중이면 본문을 표시하고, 기간 밖이면 공통 안내를 표시합니다. Boolean 하나로 시작 전과 종료 후를 구분하지는 않습니다.

import { connection } from 'next/server';
import { isEventVisible } from '@/lib/event-flags';

export default async function EventLanding() {
  await connection();
  const visible = await isEventVisible();

  if (!visible) {
    return <main><h1>현재 이벤트 운영 기간이 아닙니다</h1></main>;
  }

  return (
    <main>
      <h1>기간 한정 이벤트</h1>
      <p>이벤트 내용과 신청 조건을 확인하세요.</p>
    </main>
  );
}

Next.js의 connection()은 들어오는 요청을 기다린 뒤 렌더링을 진행하도록 합니다. 여기서는 시각에 따라 달라지는 영역이 빌드 시점의 결과로 고정되는 일을 피하려는 용도입니다. Cache Components 등 프로젝트 설정에 따라 Suspense 경계를 추가해야 할 수 있으므로 실제 프레임워크 버전에서 빌드와 응답을 확인하세요. 근거: 요청 시점 렌더링 API

이벤트 버튼만 숨겨서는 기간 밖 신청을 막을 수 없습니다. 신청·할인 적용을 받는 서버 처리에서도 신뢰할 수 있는 현재 시각과 업무 조건을 검증하세요. 이는 페이지 노출 규칙과 별도로 필요한 구현 판단입니다.

기간 밖인데 이벤트가 보일 때 확인할 것

Vercel Flags는 환경 설정, 직접 타기팅, 위에서 아래로 규칙, fallback outcome 순으로 평가합니다. 한 규칙은 모든 필터가 맞아야 일치하고 처음 일치한 결과를 반환합니다. 속성이 누락된 조건은 일치하지 않습니다. 근거: 평가 순서·누락 문맥

캐시가 이미 생성된 HTML을 반환하면 그 요청에서 날짜 판단이 다시 실행되지 않을 수 있습니다. 따라서 설정 변경 성공과 방문자 화면 변경을 따로 점검하세요. 수동 override를 쓰는 검토 환경도 일반 방문자 결과와 구분합니다.

시작·종료 경계 검증표

다음은 위 가상 일정의 판정 기준입니다. 테스트 환경에서 시각 입력을 통제하거나 가까운 테스트 기간을 만들어 실제 렌더링 결과와 비교하세요. 운영 코드에 공개 query parameter로 시각을 바꾸는 기능을 추가하지 않습니다.

점검 기록에는 시각·시간대, 환경, 서버가 받은 timestamp, 플래그 결과, 페이지 표시, 캐시 여부를 남기세요. 표의 결과는 예시 조건의 기대값이며, 실제 SDK 호출이 성공했다는 시험 결과는 아닙니다.

자주 묻는 질문

시작과 종료를 서로 다른 규칙으로 넣어도 되나요?

기간 안에서만 켜려는 목적이라면 한 규칙에 두 조건을 함께 두는 구성이 명확합니다. 시작 이상을 On으로 반환하는 규칙이 먼저 일치하면 종료 조건을 검사하기 전에 결과가 정해질 수 있습니다.

현재 시각을 브라우저에서 보내도 되나요?

이벤트 운영 기준은 서버 시각으로 정하는 편이 적절합니다. 사용자가 바꿀 수 있는 기기 시계나 query parameter를 신청·할인 자격의 근거로 사용하지 마세요.

종료 후 이벤트 URL을 삭제해야 하나요?

안내 페이지를 유지할지, 다른 페이지로 이동시킬지는 이벤트 운영 목적에 맞춰 정하세요. 예시는 동일 URL에 기간 밖 안내를 표시합니다. 상세 조건·지난 행사 정보가 필요한 독자에게는 종료 사실을 명확하게 보여주는 방식도 고려할 수 있습니다.

확인일은 2026년 10월 9일입니다. SDK·CLI 지원과 프레임워크 캐시 동작은 적용 시점에 공식 문서를 다시 확인하세요. 배포 검증 자동화는 GitHub Actions PR 검증 가이드와 함께 점검할 수 있습니다.