행동 데이터 연동 가이드
인증하기 (Authenticate)
준비된 키를 HTTP 요청 헤더(Header)에 설정합니다. 모든 API 요청 시 아래 헤더가 반드시 포함되어야 합니다.
Content-Type
필수
데이터 전송 형식을 JSON으로 지정합니다.
serviceKey
필수
[인증키] genser 어드민 설정에서 발급받은 서비스 식별 키입니다. (비밀번호처럼 관리해주세요)
requestId
필수
[추적키] 매 요청마다 새로 생성하는 고유 식별자입니다. (오류 추적용)
Idempotency-Key
필수
[중복방지키] 네트워크 오류 등으로 인한 중복 처리를 막기 위한 키입니다.
Idempotency Key 포맷 상세 기준
genser API는 UUID Version 4 표준 사용을 권장합니다.
권장 형식: 하이픈(-)이 포함된 표준 형식
글자 수 길이:
표준 (권장): 하이픈 포함 시 총 36자 (예:
550e8400-e29b-41d4-a716-446655440000)대체: 하이픈 제거 시 총 32자 (예:
550e8400e29b41d4a716446655440000)
HTTP 요청 헤더 예시:
POST /actions/cart/add HTTP/1.1
Host: statistics.genser.app
Content-Type: application/json
serviceKey: cb37cce9d6ae434fa366151b3420a9af
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
requestId: req-20260112-001데이터 전송하기 (Send Data)
사용자의 행동이 발생한 시점(버튼 클릭, 페이지 로드 등)에 맞춰 해당 API를 호출합니다. 아래 상황별 JSON 예시를 참고하여 데이터를 전송해 주세요. 상세한 필드 규격은 각 항목의 [API 레퍼런스]에서 확인하실 수 있습니다.
장바구니 (Cart)
장바구니 추가 (Add to Cart)
사용자가 '장바구니 담기' 버튼을 클릭했을 때 호출합니다.
Path: /actions/cart/add
본문(Body) 코드 샘플
{
"specversion": "1.0.0",
"id": "EVT-ADD-TO-CART-001",
"type": "add_to_cart",
"time": "2025-12-02T10:00:00Z",
"source": "[https://shop.groobee.com](https://shop.groobee.com)",
"data": {
"@context": "[https://schema.org/](https://schema.org/)",
"@type": "AddAction",
"agent": {
"@type": "Person",
"identifier": [
{ "@type": "PropertyValue", "propertyID": "memberId", "value": "user1234" },
{ "@type": "PropertyValue", "propertyID": "userId", "value": "2aa9a562..." }
]
},
"object": {
"@type": "OrderItem",
"orderQuantity": 2,
"orderedItem": {
"@type": "Product",
"sku": "131776",
"name": [{ "@value": "소이 3인소파", "@language": "ko" }],
"offers": { "@type": "Offer", "price": 1285000, "priceCurrency": "KRW" }
}
},
"target": {
"@type": "EntryPoint",
"urlTemplate": "[https://www.groobee.com/cart](https://www.groobee.com/cart)"
}
}
}장바구니 제거 (Remove from Cart)
사용자가 장바구니에서 상품을 삭제했을 때 호출합니다.
Path: /actions/cart/remove
본문(Body) 코드 샘플
{
"specversion": "1.0.0",
"id": "EVT-REMOVE-FROM-CART-001",
"type": "remove_from_cart",
"time": "2025-12-02T10:10:00Z",
"source": "[https://shop.groobee.com](https://shop.groobee.com)",
"data": {
"@context": "[https://schema.org/](https://schema.org/)",
"@type": "DeleteAction",
"agent": {
"@type": "Person",
"identifier": [
{ "@type": "PropertyValue", "propertyID": "memberId", "value": "user1234" }
]
},
"object": {
"@type": "OrderItem",
"orderQuantity": 1,
"orderedItem": {
"@type": "Product",
"sku": "131776",
"name": [{ "@value": "소이 3인소파", "@language": "ko" }],
"offers": { "@type": "Offer", "price": 1285000, "priceCurrency": "KRW" }
}
},
"target": {
"@type": "EntryPoint",
"urlTemplate": "[https://shop.groobee.com/cart](https://shop.groobee.com/cart)"
}
}
}주문/결제 (Purchase)
결제 시작 (Start Checkout)
사용자가 주문서 작성 페이지에 진입했을 때 호출합니다.
Path: /actions/purchase/checkout
결제 완료 (Complete Purchase)
결제가 성공적으로 완료된 시점(주문 완료 페이지)에 호출합니다. 가장 중요한 데이터입니다.
Path: /actions/purchase/complete
결제 취소 (Cancel Purchase)
사용자가 결제를 취소하거나 주문을 철회했을 때 호출합니다.
Path: /actions/purchase/cancel
검색 (Search)
검색어 제출 (Search Submitted)
사용자가 검색창에 검색어를 입력하고 엔터키를 치거나 돋보기 아이콘을 눌렀을 때 호출합니다.
Path: /actions/search/submitted
검색 결과 조회 (View Search Result)
검색 결과 리스트 페이지가 로딩되었을 때 호출합니다.
Path: /actions/search/result
상품 (Product)
상품 상세 조회 (View Product)
상품 상세 페이지(PDP)에 진입했을 때 호출합니다.
Path: /actions/view/product
상품 클릭 (Click Product)
리스트에서 특정 상품을 클릭했을 때 호출합니다.
Path: /actions/click/product
위시리스트 (Wishlist)
위시리스트 등록 (Add to Wishlist)
'찜하기' 또는 '위시리스트 추가' 버튼 클릭 시 호출합니다.
Path: /actions/wishlist/add=
위시리스트 제거 (Remove from Wishlist)
위시리스트에서 상품을 삭제할 때 호출합니다.
Path: /actions/wishlist/remove
응답 확인하기 (Check Response)
API 호출 후 HTTP 상태 코드를 확인하여 전송 성공 여부를 판단합니다.
200 OK
성공
성공입니다. 다음날 00:15am 배치를 통해 반영됩니다.
400 Bad Request
요청 형식 오류
JSON 문법이 틀렸거나, 필수 값(sku, name 등)이 누락되었는지 확인하세요.
401 Unauthorized
인증 실패
serviceKey가 유효하지 않거나 누락되었습니다.
500 Internal Error
서버 오류
일시적인 장애일 수 있습니다. 잠시 후 재시도(Retry) 로직을 실행하세요.
연동 결과 확인하기 (Verify)
API 연동 후 데이터가 정상적으로 쌓이고 있는지 genser 어드민에서 확인할 수 있습니다.
대시보드 화면의 통계 지표를 통해 이벤트 건수가 정상적으로 집계되는지 확인합니다.
검색 인사이트 화면의 통계 지표를 통해 이벤트 건수가 정상적으로 집계되는지 확인합니다.
데이터 반영 및 갱신 시점 안내
genser는 데이터의 성격에 따라 실시간 반영과 정기 업데이트(Batch)를 구분하여 운영합니다. 확인하고자 하는 데이터 종류에 따른 갱신 시점과 기준 시간대를 참고해 주십시오.
검색 로그
전체 검색 이력 목록
실시간 (Real-time)
UTC
통계/분석
'오늘(Today)' 조회 시
매 시간 5분 (예: 11:05)
KST (한국 시간)
통계/분석
'어제' 및 과거 기간 조회 시
매일 00시 (자정)
KST (한국 시간)
Last updated
Was this helpful?