주요 콘텐츠로 건너뛰기

API 참조

분석 API

분석 API

분석 API는 레스토랑 운영자를 위한 메뉴 성과 데이터와 고객 상호 작용을 기록하는 추적 엔드포인트를 제공합니다.

GET /api/analytics

레스토랑의 분석 데이터를 조회합니다.

인증: 필요(Bearer 토큰). 레스토랑 소유권도 확인합니다.

응답(200 OK)

{
  "success": true,
  "data": {
    "totalViews": 1250,
    "uniqueVisitors": 890,
    "averageDuration": 45.2,
    "topItems": [
      {
        "id": "uuid",
        "name": "Margherita Pizza",
        "views": 340
      }
    ],
    "modelCoverage": 0.85
  }
}

참고: modelCoverage 필드는 READY 상태의 3D 모델이 있는 메뉴 항목의 비율을 나타냅니다(3D Menu Pro 전용). 이 값은 status = 'READY'인 three_d_models 테이블에 대한 LEFT JOIN을 사용합니다.

POST /api/analytics/track

새 페이지 조회를 기록합니다. 메뉴 뷰어 클라이언트에서 사용합니다.

인증: 공개(토큰 불필요)

요청 본문

{
  "restaurantId": "uuid",
  "menuItemId": "uuid"
}

응답(201 Created)

{
  "success": true,
  "data": {
    "id": "uuid"
  }
}

중요: 응답은 데이터를 data.data로 감쌉니다. 파싱된 JSON에서 response.id가 아닌 response.data?.id를 사용하세요.

PATCH /api/analytics/track

기존 조회 기록을 체류 시간 및 상호 작용 데이터로 업데이트합니다.

인증: 공개(토큰 불필요)

요청 본문

{
  "viewId": "uuid",
  "duration": 45,
  "interactions": 3
}

응답(200 OK)

{
  "success": true,
  "data": {
    "id": "uuid",
    "duration": 45,
    "interactions": 3
  }
}

참고: 분석 추적 호출에는 항상 keepalive: true와 함께 fetch를 사용하세요. navigator.sendBeacon은 text/plain 콘텐츠 유형의 POST만 지원하므로 사용하지 마세요.