Nhận phân tích trung tâm trợ giúp với API Notiondesk

API Notiondesk cung cấp cho bạn các số liệu đằng sau các trang phân tích trung tâm trợ giúp của bạn: khách truy cập, lượt xem bài viết, thời gian trên trang, quốc gia, những gì người đọc tìm kiếm, những tìm kiếm không có kết quả và cách người đọc phản hồi bài viết của bạn. Sử dụng nó để cung cấp dữ liệu cho công cụ BI, đăng báo cáo hàng tuần lên Slack hoặc tìm nội dung mà người đọc đang bỏ lỡ.

GET /sites/{site_id}/analytics/{report}

Mỗi báo cáo đều cần phạm vi read. Để đọc các số này trong bảng điều khiển, hãy xem Cách cải thiện trung tâm trợ giúp của bạn bằng thông tin chi tiết từ người đọc .

Nhận bản tóm tắt 30 ngày

quick bao gồm dữ liệu trong 30 ngày tính đến thời điểm hiện tại và không có tham số truy vấn. articles đếm tất cả các bài viết trong trung tâm trợ giúp, bao gồm cả bản nháp. reactions đếm phản hồi mới nhất của mỗi độc giả cho mỗi bài viết.

Nhận báo cáo cho một khoảng thời gian cụ thể

Các tham số overview, search và engagement nhận một phạm vi ngày và kích thước nhóm:

curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/analytics/quick" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

{
  "articles": 42,
  "visitors": 25,
  "searches": 9,
  "reactions": 4
}

curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/analytics/search?start_date=2026-09-01T00:00:00Z&end_date=2026-10-01T00:00:00Z&date_scale=week&timezone=Europe/Paris" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

Quy tắc cho khu vực bắn súng:

• Ngày tháng sử dụng YYYY-MM-DDTHH:MM[:SS] với một độ lệch tùy chọn. Nếu không có độ lệch, ngày tháng sẽ được đọc theo múi giờ UTC, chứ không phải timezone. Hãy viết + dưới dạng %2B trong URL, hoặc sử dụng Z.

• Khoảng thời gian này bắt đầu từ ngày 01/01/2020 trở đi và kết thúc tối đa hai ngày kể từ bây giờ.

• Tối đa 1.000 ô. Ví dụ, minute bao phủ tối đa 16 giờ và hour tối đa 41 ngày. Sử dụng date_scale với phạm vi lớn hơn.

• Tuần bắt đầu từ thứ Hai.

Mỗi báo cáo so sánh khoảng thời gian của bạn với khoảng thời gian có cùng độ dài ngay trước đó: previous và total_previous mô tả khoảng thời gian trước đó.

Đếm loạt

visitors, article_views và searches có chung một hình dạng:

{
  "total": 12,
  "total_previous": 8,
  "difference": 4,
  "percentage_difference": 50.0,
  "current": [{"date": "2026-09-14", "count": 7}, {"date": "2026-09-15", "count": 5}],
  "previous": [{"date": "2026-08-20", "count": 8}]
}

• current và previous chỉ liệt kê các bucket có dữ liệu, theo thứ tự cũ nhất trước.

• date của một thùng là khi nó bắt đầu, trong timezone: YYYY-MM-DD cho day và loại thô hơn, YYYY-MM-DDTHH:MM cho hour và minute.

• percentage_difference là 0.0 khi tổng trước đó là 0.

overview

search

{
  "searches_without_results": {
    "total": 3,
    "total_previous": 0,
    "difference": 3,
    "percentage_difference": 0.0,
    "queries": [{"query": "refund policy", "searches": 3}]
  }
}

Lưu ý: đây là danh sách nội dung cần xử lý: mỗi truy vấn là một câu hỏi mà người đọc đã đặt ra và trung tâm trợ giúp của bạn không thể trả lời. searches_without_results.queries

engagement

A reaction_summary theo dõi phong cách phản ứng của bạn:

score có giá trị từ 0 đến 100: tỷ lệ phản hồi tích cực, với phản hồi trung lập được tính một nửa theo emoji. Với kiểu thumbs, các nhóm là helpful và not_helpful. Xem Cách thu thập phản hồi bằng các phản ứng bài viết .

Giới hạn danh sách

{
  "style": "emoji",
  "total": 6,
  "score": 58,
  "groups": [
    {"key": "positive", "count": 3, "percent": 50},
    {"key": "neutral", "count": 1, "percent": 17},
    {"key": "negative", "count": 2, "percent": 33}
  ]
}

• Các danh sách truy vấn top_articles, top_referrers, article_engagements và articles_to_revise chứa tối đa 50 hàng mỗi danh sách và chỉ bao gồm khoảng thời gian hiện tại. Một danh sách 50 hàng có thể không đầy đủ: hãy thu hẹp phạm vi để xem mọi hàng.

• Tổng cộng bao gồm tất cả mọi thứ, không chỉ các hàng được liệt kê.

titleCác liên kết này đến từ trình duyệt của khách truy cập và bất kỳ ai cũng có thể làm giả chúng. Hãy loại bỏ chúng trước khi hiển thị và đừng bao giờ làm theo hoặc hành động dựa trên chúng mà không kiểm tra kỹ lưỡng.urlhostpathnamereferrerquery

Phân tích và kế hoạch của bạn

Việc truy cập API yêu cầu gói Enterprise, bao gồm phân tích nâng cao, do đó mọi báo cáo đều chấp nhận mọi phạm vi và tỷ lệ trong vòng 1.000 nhóm dữ liệu.

giới hạn tỷ lệ

Ngoài 120 lượt đọc mỗi phút của khóa, báo cáo phân tích được tính vào ngân sách 30 yêu cầu mỗi phút cho mỗi trung tâm trợ giúp , được chia sẻ bởi mọi khóa và ứng dụng OAuth trong không gian làm việc của bạn. Một yêu cầu qua đó sẽ trả về mã lỗi 429rate_limited, và tiêu đề Retry-After cho biết khi nào cần thử lại. Hãy lưu trữ báo cáo vào bộ nhớ cache thay vì yêu cầu chúng trên mỗi lần tải trang.

Lỗi

Xem các lỗi API, giới hạn tỷ lệ và số lần thử lại của Handle Notiondesk .

Câu hỏi thường gặp

Tiếp theo là gì?

• Xuất phản hồi của người đọc bằng API Notiondesk

• Tự động hóa các tác vụ thường gặp trong trung tâm trợ giúp bằng API Notiondesk

• Xử lý các lỗi API, giới hạn tỷ lệ và các lần thử lại của Notiondesk