방문 분석

스토어프론트의 방문을 수집하고 상점 플랫폼에서 방문·유입·퍼널 통계를 봅니다.

브라우저 SDK는 페이지뷰·상품 조회·목록 노출·검색·체류 시간을 보냅니다. 장바구니 담기·결제 시작·구매는 스토어프론트 API가 서버에서 기록하므로 조작이나 누락이 없습니다.

브라우저에서 시작하기

@sayren/storefront-sdk/analytics의 createAnalytics를 브라우저에서 한 번 호출합니다. 서버 렌더 중에는 아무것도 하지 않습니다.

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

const analytics = createAnalytics({
  baseUrl: "https://api.sayren.io/storefront/v1",
  storeCode: "{상점 코드}",
  consent: "granted",
});

페이지뷰는 첫 페이지와 History API 이동(pushState·replaceState·뒤로 가기)마다 셉니다(해시 이동 제외). 페이지를 떠나거나 탭을 숨기면 보인 시간을 체류 시간으로 보냅니다.

localhost·사설 IP에서는 기본으로 보내지 않습니다. 개발 중인 방문이 통계에 섞이지 않게 하려는 기본값입니다. 개발 서버에서 수집을 확인하려면 debug: true를 줍니다. MCP 스토어프론트 템플릿은 .env에 SAYREN_ANALYTICS_DEBUG=1을 넣으면 켜집니다. 배포한 주소에서는 설정 없이 보냅니다.

MCP 스토어프론트 템플릿은 consent: "granted"로 시작합니다(개인정보 없는 1st-party 쿠키, 국내 기준). EU처럼 사전 동의가 필요하면 pending으로 시작하고 동의 배너에서 analytics.setConsent("granted" | "denied")를 부르십시오. denied면 모은 이벤트를 버리고 더 보내지 않습니다.

행동 이벤트

// 상품 상세를 봤을 때. 옵션이 정해졌으면 variantId도 넣습니다
analytics.track({ name: "product_view", productId: "prod_001" });
// 상품 목록이 보였을 때. listId는 목록 이름(예: home:new, search)
analytics.track({ name: "product_list_view", listId: "category:cat_12", productIds: ["prod_001", "prod_002"] });
// 검색 결과가 보였을 때
analytics.track({ name: "search", query: "린넨 셔츠", resultCount: 12 });

같은 페이지뷰 안의 같은 행동은 한 번만 보내므로 다시 렌더돼도 괜찮습니다. 이벤트는 모아서 5초마다 보내고, 50개가 차거나 탭을 숨기거나 페이지를 떠나면 바로 보냅니다.

구매와 방문 잇기

SDK는 쿠키 sy_vid(방문자, 1년)·sy_sid(세션, 30분 비활동)를 만듭니다. 스토어프론트 API 호출에 이 값을 x-sayren-visitor·x-sayren-session 헤더로 실어야 거래 이벤트가 방문에 이어지고, 없으면 거래 이벤트를 기록하지 않습니다. SSR은 요청 쿠키에서 읽어 넘기고, 브라우저는 analytics.ids()(동의 전 null)를 visitorId·sessionId로 넘깁니다.

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

const api = createStorefrontClient({
  baseUrl: "https://api.sayren.io/storefront/v1",
  storeCode: "{상점 코드}",
  ...analyticsIdsFromCookie(request.headers.get("cookie")),
});

수집하지 않는 것

URL은 경로와 utm_source·utm_medium·utm_campaign만, 리퍼러는 호스트만 저장합니다. IP는 저장하지 않습니다. 검색 엔진 봇과 자동화 브라우저의 방문은 표시해 두고 집계에서 뺍니다.

수집 도메인 제한

상점 플랫폼에서 설정 › 로그인으로 이동합니다(소유자만). 스토어프론트 도메인 카드에 쇼핑몰 주소(예: https://shop.example.com)를 넣으면 그 도메인에서 보낸 수집만 받습니다. 다른 사이트가 내 상점 코드로 통계를 섞는 것을 막습니다(브라우저 Origin 기준, 서버에서 직접 보내는 요청은 수집 한도가 막음).

• 목록 밖에서 보낸 요청은 403 ORIGIN_NOT_ALLOWED이고, 페이지 주소가 목록 밖인 이벤트는 버립니다.
• 비워 두면 모든 도메인에서 받습니다. 바꾼 설정은 1분 안에 적용됩니다.
• 이 목록은 소셜 로그인 복귀 주소 허용 목록과 같습니다. 쇼핑몰 주소를 모두 넣으십시오.
• API는 PATCH /store의 storefrontOrigins(최대 20개), SDK는 api.store.update({ storefrontOrigins })입니다.

한도

요청당 이벤트 50개·32KB, 방문자당 분당 120개까지 기록합니다. SDK는 이름마다 분당 30개·전체 100개까지만 보내 한도에 걸리지 않습니다. 한도를 넘어도 응답은 204입니다. 원본 이벤트는 90일 보관합니다.

통계 조회

상점 플랫폼에서 상점 관리 › 분석 › 애널리틱스로 이동합니다(소유자·관리자).

기본 기간은 최근 7일입니다. 이전 기간과 비교로 같은 길이의 직전 기간을 함께 보고, 결제 구분으로 테스트 결제 구매를 포함합니다. 탭을 옮기거나 메뉴로 다시 들어와도 마지막 기간이 유지됩니다.

집계는 한국 날짜 단위이고 10분마다 최근 3일을 다시 계산합니다. 오늘 값은 응답의 lastComputedAt까지 반영돼 있습니다. 관리 API는 GET /analytics/{overview|products|sources|devices|pages|search|checkout|realtime}이고 analytics:r 스코프, 기간은 양끝 포함 최대 92일입니다. realtime만 집계를 기다리지 않고 원본 이벤트로 계산합니다.

API

SDK 없이 보낼 때는 POST /storefront/v1/events를 씁니다. 본문 형식은 스토어프론트 API 레퍼런스를 참고하십시오.

다음 단계

• Storefront SDK
• 매출 리포트
• 결제 연동