160 lines
4.4 KiB
Markdown
160 lines
4.4 KiB
Markdown
# 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일 방문자 합계 |
|
|
| `pageViewsLast30Days` | number | 최근 30일 페이지뷰 |
|
|
| `onlineNow` | number | 최근 90초 안에 활동한 접속자 |
|
|
| `loggedInNow` | number | 현재 접속자 중 로그인 회원 |
|
|
| `avgEngagedSeconds` | duration | 오늘 평균 체류시간(오늘 값이 없으면 조회 범위 평균) |
|
|
| `totalPosts` | number | 현재 공개된 발행 게시글 수 |
|
|
| `totalComments` | number | 공개 게시글에 달린 공개 댓글 수 |
|
|
| `totalPages` | number | 공개 고정 페이지 수 |
|
|
| `totalTags` | number | 전체 태그 수 |
|
|
| `totalMembers` | number | 전체 가입 계정 수 |
|
|
| `items` | array | 이름·표시 문자열·원본 값을 포함한 기본 통계 목록 |
|
|
|
|
`totalVisitors`는 사이트 전체에서 동일인을 영구 식별한 값이 아니다. 날짜별 중복을 제거한 방문자 수를 누적하므로 같은 사람이 다른 날짜에 방문하면 다시 집계된다.
|
|
|
|
## 추천 기본 설정
|
|
|
|
`services.yaml`에서 필요한 항목만 골라 `mappings`에 넣는다.
|
|
|
|
```yaml
|
|
- sori.studio:
|
|
href: https://sori.studio
|
|
description: 블로그 통계
|
|
widget:
|
|
type: customapi
|
|
url: https://sori.studio/api/homepage-widget
|
|
refreshInterval: 30000
|
|
mappings:
|
|
- field: todayVisitors
|
|
label: 오늘 방문자
|
|
format: number
|
|
suffix: 명
|
|
- field: totalVisitors
|
|
label: 누적 방문자
|
|
format: number
|
|
suffix: 명
|
|
- field: totalPosts
|
|
label: 전체 게시글
|
|
format: number
|
|
suffix: 개
|
|
- field: totalComments
|
|
label: 전체 댓글
|
|
format: number
|
|
suffix: 개
|
|
```
|
|
|
|
## 선택 가능한 설정 예시
|
|
|
|
### 방문·조회 통계
|
|
|
|
```yaml
|
|
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: 회
|
|
```
|
|
|
|
### 콘텐츠 통계
|
|
|
|
```yaml
|
|
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: 개
|
|
```
|
|
|
|
### 기간·실시간 통계
|
|
|
|
```yaml
|
|
mappings:
|
|
- field: visitorsLast7Days
|
|
label: 최근 7일 방문
|
|
format: number
|
|
suffix: 명
|
|
- field: pageViewsLast30Days
|
|
label: 최근 30일 조회
|
|
format: number
|
|
suffix: 회
|
|
- field: onlineNow
|
|
label: 현재 접속
|
|
format: number
|
|
suffix: 명
|
|
- field: avgEngagedSeconds
|
|
label: 평균 체류
|
|
format: duration
|
|
```
|
|
|
|
### 회원·갱신 정보
|
|
|
|
```yaml
|
|
mappings:
|
|
- field: totalMembers
|
|
label: 전체 회원
|
|
format: number
|
|
suffix: 명
|
|
- field: loggedInNow
|
|
label: 로그인 접속
|
|
format: number
|
|
suffix: 명
|
|
- field: updatedAt
|
|
label: 갱신
|
|
format: relativeDate
|
|
locale: ko
|
|
numeric: auto
|
|
```
|
|
|
|
## 확인 방법
|
|
|
|
```bash
|
|
curl https://sori.studio/api/homepage-widget
|
|
```
|
|
|
|
응답이 정상인데 Homepage에 값이 나오지 않으면 Homepage 컨테이너 내부에서 해당 URL에 접근할 수 있는지 먼저 확인한다.
|