방문 분석

스토어프론트에 방문 분석을 붙이면 페이지뷰, 상품 조회, 목록 노출, 검색, 체류 시간이 수집돼요. 장바구니 담기, 결제 시작, 구매는 브라우저가 보내지 않아요. 스토어프론트 API가 요청을 처리하면서 서버에서 기록하므로 매출과 전환은 조작이나 누락이 없어요.

브라우저에서 시작하기

@sayren/storefront-sdk/analytics의 createAnalytics를 브라우저에서 한 번 호출해요. 서버 렌더 중에 호출하면 아무것도 하지 않는 객체를 돌려줘요.

import { createAnalytics } from "@sayren/storefront-sdk/analytics";

const analytics = createAnalytics({
  baseUrl: "https://api.sayren.app/storefront/v1",
  storeCode: "mystore",
  consent: "granted",
});

페이지뷰는 자동으로 세요. 첫 페이지와 History API 이동(pushState·replaceState·뒤로 가기)이 새 페이지뷰이고, 해시만 바뀐 이동은 세지 않아요. 페이지를 떠나거나 탭을 숨기면 그 페이지가 화면에 보인 시간을 체류 시간으로 보내요.

MCP로 만든 스토어프런트 템플릿은 consent: "granted"로 시작해요. 개인정보를 저장하지 않는 1st-party 쿠키라 국내 쇼핑몰 기준으로 정한 값이에요. EU처럼 분석 쿠키에 사전 동의가 필요한 지역의 구매자를 받는다면 동의 배너를 붙이고 pending으로 바꿔 주세요.

쿠키 동의 배너를 쓰면 consent: "pending"으로 시작하고 배너에서 analytics.setConsent("granted") 또는 "denied"를 호출해요. denied면 모아 둔 이벤트를 버리고 이후에도 보내지 않아요.

행동 이벤트

analytics.track({ name: "product_view", productId: "prod_001" });
analytics.track({ name: "product_list_view", listId: "category:cat_12", productIds: ["prod_001", "prod_002"] });
analytics.track({ name: "search", query: "린넨 셔츠", resultCount: 12 });

같은 페이지뷰 안에서 같은 행동은 한 번만 보내요. 호출할 때마다 요청하지 않고 모아서 5초마다(50개가 차거나 탭을 숨기거나 페이지를 떠나면 바로) 보내요. 컴포넌트가 다시 렌더되거나 effect가 두 번 실행돼도 괜찮아요. 서버도 같은 행동을 일정 시간 안에 다시 받으면 한 번으로 기록해요.

구매와 방문 잇기

브라우저 SDK는 방문자 쿠키 sy_vid(1년)와 세션 쿠키 sy_sid(30분 비활동)를 만들어요. 스토어프론트 API를 부를 때 이 두 값을 x-sayren-visitor·x-sayren-session 헤더로 실으면 장바구니 담기·빼기, 결제 시작, 구매가 그 방문에 이어져요. 헤더가 없으면 거래 이벤트는 기록하지 않아요.

서버에서 API를 부르는 스토어프론트(SSR)는 요청 쿠키에서 값을 읽어 클라이언트에 넘겨요.

import { analyticsIdsFromCookie, createStorefrontClient } from "@sayren/storefront-sdk";

const api = createStorefrontClient({
  baseUrl: "https://api.sayren.app/storefront/v1",
  storeCode: "mystore",
  ...analyticsIdsFromCookie(request.headers.get("cookie")),
});

브라우저에서 API를 부르면 analytics.ids()의 값을 visitorId·sessionId로 넘겨요. 동의 전이면 null이에요.

수집하지 않는 것

페이지 URL은 경로와 utm_source·utm_medium·utm_campaign만 저장하고 나머지 쿼리와 해시는 버려요. 리퍼러는 호스트만 저장해요. IP 주소는 저장하지 않아요. 검색 엔진 봇과 자동화 브라우저의 방문은 표시해 두고 집계에서 빼요.

수집 도메인 제한

수집 요청에는 스토어 코드만 실리므로, 다른 사이트가 이 스토어 코드로 SDK를 심으면 통계가 섞일 수 있어요. 셀러 콘솔 설정 › 스토어 정보 › 방문 분석 수집 도메인에 스토어프런트 도메인(예: https://shop.example.com)을 넣으면 그 도메인에서 보낸 수집만 받아요. 목록 밖에서 보낸 요청은 403 ORIGIN_NOT_ALLOWED이고, 페이지 주소가 목록 밖인 이벤트는 버려요. 비워 두면 모든 도메인에서 받아요. 바꾼 설정은 1분 안에 적용돼요.

API로는 PATCH /store의 analyticsAllowedOrigins(최대 20개)로 정해요. store-sdk는 api.store.update({ analyticsAllowedOrigins })예요.

브라우저가 보내는 Origin 헤더로 판단하므로 다른 웹사이트를 통한 오염을 막는 장치예요. 서버에서 직접 보내는 요청은 수집 한도가 양을 막아요.

한도

한 번에 이벤트 50개, 32KB까지 보낼 수 있어요. 방문자당 분당 120개를 넘는 이벤트는 기록하지 않아요. SDK는 이벤트 이름마다 분당 30개, 전체 분당 100개까지만 보내므로 SDK를 쓰면 이 한도에 걸리지 않아요. 한도를 넘어도 응답은 204라 SDK가 다시 보내지 않아요. 원본 이벤트는 90일 동안 보관해요.

통계 조회

셀러 콘솔 분석 › 애널리틱스에서 개요·전환 퍼널·상품 분석·유입 경로 탭으로 볼 수 있어요. 탭을 옮겨도 고른 기간이 유지돼요. 개요는 이전 같은 길이 기간과 비교해 변화를 보여 주고, 상품 분석은 CSV로 내려받을 수 있어요. 이탈률은 참여 세션이 아닌 세션의 비율이에요.

수집한 이벤트는 한국 시간 날짜별로 집계되고, 관리 API로 조회해요. 집계는 10분마다 최근 3일을 다시 계산하므로 오늘 값은 응답의 lastComputedAt 시점까지 반영돼 있어요. 기간은 양끝을 포함해 최대 92일이에요. analytics:r 스코프가 필요하고, 콘솔 로그인에서는 OWNER와 ADMIN이 이 스코프를 가져요.

집계 기준은 다음과 같아요.

• 세션은 30분 동안 활동이 없거나 다른 캠페인으로 들어오면 새로 시작해요. 자정을 넘긴 세션은 두 날짜에 모두 잡혀요.
• 참여 세션은 페이지를 2개 이상 봤거나, 10초 이상 머물렀거나, 장바구니 담기·결제 시작·구매를 한 세션이에요.
• 방문자 수는 날짜별 순방문자를 더한 값이에요. 여러 날 방문한 사람은 날마다 세요.
• 체류 시간은 페이지 하나에 최대 30분까지, 세션 하나에 세션 길이 + 30분까지 세요.
• 구매 금액은 주문 결제 금액(배송비 포함)이고, 상품별 구매 금액은 그 상품의 주문 금액(배송비 제외)이에요. 이후 취소·환불은 빼지 않아요. 취소·환불을 뺀 순매출은 매출 리포트에서 확인해요.
• 퍼널의 각 단계는 그 행동을 한 세션 수예요. 앞 단계를 거쳤는지는 따지지 않아요.
• 유입은 세션 첫 페이지뷰의 utm과 리퍼러로 정해요. utm이 리퍼러보다 우선해요. 페이지뷰 없이 서버 이벤트만 있는 세션은 UNKNOWN이에요.
• 봇·자동화 브라우저로 표시된 이벤트가 하나라도 있는 세션은 모든 집계에서 빠져요.
• 샌드박스 결제로 만든 구매는 기본으로 빠지고 includeTest=true로 포함해요.

API

SDK를 쓰지 않을 때는 POST /storefront/v1/events로 직접 보내요. 본문 형식은 스토어프론트 API 레퍼런스를 참고해요.