Homepage Custom API 위젯 가이드

엔드포인트

공개 URL: GET /api/homepage-widget
운영 예시: https://sori.studio/api/homepage-widget
NAS 호스트 포트 예시: http://NAS_LAN_IP:43080/api/homepage-widget
같은 Docker 네트워크 예시: http://sori-studio:3000/api/homepage-widget

Homepage가 Docker 컨테이너에서 실행 중이면 localhost는 Homepage 컨테이너 자신을 가리킨다. 같은 서버의 sori.studio에 연결할 때는 공개 도메인, NAS 내부 IP 또는 같은 Docker 네트워크의 서비스 이름을 사용한다.

제공 필드

필드	형식	설명
`title`	text	사이트 제목
`updatedAt`	date	API 응답 생성 시각
`todayVisitors`	number	오늘 순방문자 수
`totalVisitors`	number	일별 순방문자 수의 누적 합계
`todayPageViews`	number	오늘 페이지뷰
`totalPageViews`	number	전체 누적 페이지뷰
`visitorsLast7Days`	number	최근 7일 방문자 합계
`visitorsLast30Days`	number	최근 30일 방문자 합계
`visitorsLast180Days`	number	최근 180일(약 6개월) 방문자 합계
`visitorsLast365Days`	number	최근 365일(1년) 방문자 합계
`pageViewsLast30Days`	number	최근 30일 페이지뷰
`onlineNow`	number	최근 90초 안에 활동한 접속자
`loggedInNow`	number	현재 접속자 중 로그인 회원
`avgEngagedSeconds`	duration	오늘 평균 체류시간(오늘 값이 없으면 조회 범위 평균)
`totalPosts`	number	현재 공개된 발행 게시글 수
`totalComments`	number	공개 게시글에 달린 공개 댓글 수
`totalPages`	number	공개 고정 페이지 수
`totalTags`	number	전체 태그 수
`totalMembers`	number	전체 가입 계정 수
`items`	array	이름·표시 문자열·원본 값을 포함한 기본 통계 목록

totalVisitors는 사이트 전체에서 동일인을 영구 식별한 값이 아니다. 날짜별 중복을 제거한 방문자 수를 누적하므로 같은 사람이 다른 날짜에 방문하면 다시 집계된다.

선택 가능한 설정 예시

방문·조회 통계

mappings:
  - field: todayVisitors
    label: 오늘 방문자
    format: number
    suffix: 명
  - field: totalVisitors
    label: 누적 방문자
    format: number
    suffix: 명
  - field: todayPageViews
    label: 오늘 조회
    format: number
    suffix: 회
  - field: totalPageViews
    label: 누적 조회
    format: number
    suffix: 회

콘텐츠 통계

mappings:
  - field: totalPosts
    label: 게시글
    format: number
    suffix: 개
  - field: totalComments
    label: 댓글
    format: number
    suffix: 개
  - field: totalPages
    label: 페이지
    format: number
    suffix: 개
  - field: totalTags
    label: 태그
    format: number
    suffix: 개

기간·실시간 통계

mappings:
  - field: visitorsLast7Days
    label: 최근 7일 방문
    format: number
    suffix: 명
  - field: visitorsLast30Days
    label: 최근 30일 방문
    format: number
    suffix: 명
  - field: visitorsLast180Days
    label: 최근 6개월 방문
    format: number
    suffix: 명
  - field: visitorsLast365Days
    label: 최근 1년 방문
    format: number
    suffix: 명
  - field: pageViewsLast30Days
    label: 최근 30일 조회
    format: number
    suffix: 회
  - field: onlineNow
    label: 현재 접속
    format: number
    suffix: 명
  - field: avgEngagedSeconds
    label: 평균 체류
    format: duration

회원·갱신 정보

mappings:
  - field: totalMembers
    label: 전체 회원
    format: number
    suffix: 명
  - field: loggedInNow
    label: 로그인 접속
    format: number
    suffix: 명
  - field: updatedAt
    label: 갱신
    format: relativeDate
    locale: ko
    numeric: auto

확인 방법

curl https://sori.studio/api/homepage-widget

응답이 정상인데 Homepage에 값이 나오지 않으면 Homepage 컨테이너 내부에서 해당 URL에 접근할 수 있는지 먼저 확인한다.

방문 기간 통계는 일별 집계 테이블에서 최근 7·30·180·365일을 한 번에 합산한다. Homepage를 개인용으로 간헐적으로 확인한다면 refreshInterval: 300000(5분) 또는 600000(10분)으로 두면 충분하다.

5.1 KiB Raw Blame History