Discover how AI Docs tracks usage analytics and collects user feedback for continuous improvement.
AI Docs provides robust tools to help you understand how users interact with your generated documentation. By automatically tracking page views and enabling direct user feedback, you gain valuable insights into content effectiveness, popular topics, and areas that may require improvement. This data empowers you to continuously refine your documentation to better serve your audience and ensure your content remains relevant and helpful.
AI Docs automatically tracks page views for your documentation, providing an overview of popular content and overall engagement. This data is collected passively as users navigate your documentation.
When a user visits any page of your generated documentation, a client-side component, PageViewTracker, sends an event to the AI Docs backend. This event records the specific documentation page's unique identifier (docSlug) and the project it belongs to (projectId).
The PageViewTracker component leverages the navigator.sendBeacon API for reliable tracking, especially when a user is navigating away from a page. If sendBeacon is not available, it falls back to a standard fetch request with the keepalive option. This ensures that page view events are sent even if the user quickly closes the tab or navigates to another page.
// components/page-view-tracker.tsx
"use client";
import { useEffect } from "react";
export function PageViewTracker({
projectId,
docSlug,
apiBaseUrl = "",
}: {
projectId: string;
docSlug: string;
apiBaseUrl?: string;
}) {
useEffect(() => {
const body = JSON.stringify({ projectId, docSlug });
if (navigator.sendBeacon) {
navigator.sendBeacon(`${apiBaseUrl}/api/analytics`, body);
} else {
fetch(`${apiBaseUrl}/api/analytics`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body,
keepalive: true,
}).catch(() => {});
}
}, [projectId, docSlug, apiBaseUrl]);
return null;
}
The backend API endpoint, POST /api/analytics, receives this information and records it in the database, allowing for aggregation and analysis. This endpoint is designed for high-volume, fire-and-forget requests and does not require user authentication.
You can access detailed page view analytics for your projects through the AI Docs dashboard. The analytics interface, powered by the Analytics component, provides several key metrics and visualizations:
You can adjust the reporting period to view data for the last 7, 30, or 90 days, providing flexibility in analyzing short-term trends or long-term performance.
The analytics data is fetched from the GET /api/analytics endpoint, which requires an authenticated user and a projectId.
// components/Analytics.tsx (simplified useEffect)
"use client";
import { useState, useEffect } from "react";
// ... (other imports and interfaces)
export default function Analytics({ projectId }: { projectId: string }) {
const [data, setData] = useState(null);
const [loading, setLoading] = useState(true);
const [days, setDays] = useState(30); // Default to 30 days
useEffect(() => {
setLoading(true);
fetch(`/api/analytics?projectId=${projectId}&days=${days}`)
.then((r) => r.json())
.then(setData)
.catch(() => setData(null))
.finally(() => setLoading(false));
}, [projectId, days]);
// ... (rest of the component rendering charts and stats)
}
Regularly review your top pages to ensure their content remains accurate and comprehensive. Pages with consistently low views might indicate content that is less relevant or harder to discover.
Beyond passive tracking, AI Docs enables direct user feedback collection on each documentation page. This allows your readers to explicitly indicate whether a page was helpful and to provide comments, offering qualitative insights into their experience.
Users can submit feedback directly from any documentation page. This typically involves a simple "Was this page helpful?" prompt with "Yes" or "No" options, and an optional text field for comments.
When a user submits feedback, a client-side function sends the data to the POST /api/feedback endpoint.
// Example of client-side feedback submission
// This would be triggered by a user interaction (e.g., clicking a thumbs up/down button)
const submitFeedback = async (projectId: string, docSlug: string, helpful: boolean, comment?: string) => {
const response = await fetch(`/api/feedback`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ projectId, docSlug, helpful, comment }),
});
if (response.ok) {
console.log("Feedback submitted successfully!");
} else {
console.error("Failed to submit feedback.");
}
};
// Example usage:
// submitFeedback("your-project-id", "getting-started", true, "This explanation was very clear!");
// submitFeedback("your-project-id", "api-reference", false, "Could use more code examples for this section.");
The POST /api/feedback endpoint securely records this feedback, associating it with the specific project and documentation page. This endpoint is public-facing but is rate-limited by the publicApiLimiter to prevent abuse.
The AI Docs dashboard provides a dedicated section for reviewing user feedback, helping you understand overall satisfaction and pinpoint specific areas for improvement. The Feedback component in the dashboard aggregates and displays this information.
Key feedback metrics and displays include:
The aggregated feedback counts (helpful/not helpful) are retrieved via the GET /api/feedback endpoint. This endpoint is public-facing but rate-limited by the publicApiLimiter. It can provide overall counts for a project or filtered counts for a specific docSlug.
AI Docs exposes dedicated API endpoints to manage page view analytics and user feedback. These endpoints are built using Next.js App Router and adhere to the API Design and Next.js App Router principles, including CORS handling, input validation, and consistent error responses.
POST /api/analytics - Record Page ViewThis endpoint is used by the client-side PageViewTracker to record a documentation page view.
POSTprojectId (string, required): The unique identifier of the documentation project.docSlug (string, required): The unique slug of the documentation page being viewed.200 OK: { "ok": true } on successful processing (even if the database insert fails silently).400 Bad Request: { "error": "projectId and docSlug required" } if inputs are missing.GET /api/analytics - Retrieve Project AnalyticsThis endpoint provides aggregated page view and feedback data for a specific project, used by the AI Docs dashboard.
GETprojectId.authApiLimiter. Refer to API Design and Next.js App Router.projectId (string, required): The unique identifier of the documentation project.days (number, optional, default: 30): The number of past days for which to retrieve analytics data.200 OK: JSON object containing:
totalViews (number): Total page views.topPages (array): List of most viewed pages ({ docSlug: string, views: number }[]).viewsPerDay (array): Daily view counts ({ date: string, views: number }[]).feedback (object): Summary of feedback ({ up: number, down: number }).400 Bad Request: { "error": "projectId required" } if projectId is missing.401 Unauthorized: If no authenticated user session is found.403 Forbidden: If the authenticated user does not own the project.500 Internal Server Error: { "error": "Failed to fetch analytics" } for server-side errors.POST /api/feedback - Submit User FeedbackThis endpoint allows users to submit feedback on the helpfulness of a documentation page.
POSTpublicApiLimiter. Refer to API Design and Next.js App Router.projectId (string, required): The unique identifier of the documentation project.docSlug (string, required): The unique slug of the documentation page.helpful (boolean, required): true if the page was helpful, false otherwise.comment (string, optional): An optional text comment from the user.200 OK: { "success": true } on successful feedback submission.400 Bad Request: { "error": "projectId, docSlug, and helpful (boolean) are required" } if inputs are missing or invalid.404 Not Found: { "error": "Project not found" } if the projectId does not exist.429 Too Many Requests: If rate limit is exceeded.500 Internal Server Error: { "error": "Failed to save feedback" } for server-side errors.GET /api/feedback - Retrieve Aggregated FeedbackThis endpoint provides aggregated helpfulness counts for a project or a specific documentation page.
GETpublicApiLimiter. Refer to API Design and Next.js App Router.projectId (string, required): The unique identifier of the documentation project.docSlug (string, optional): The unique slug of a specific documentation page to filter feedback for.200 OK: JSON object containing:
up (number): Count of "helpful" votes.down (number): Count of "not helpful" votes.total (number): Sum of up and down votes.400 Bad Request: { "error": "projectId is required" } if projectId is missing.429 Too Many Requests: If rate limit is exceeded.500 Internal Server Error: { "error": "Failed to fetch feedback" } for server-side errors.The insights gained from page views and user feedback are invaluable for maintaining high-quality documentation.
By actively engaging with your documentation's analytics and feedback, you can ensure it remains a dynamic, user-centric resource that truly supports your project's users. You can also monitor these metrics on your Billing and Subscription Management page to understand your overall usage.
The following diagram illustrates the end-to-end flow of how page views are tracked and user feedback is collected and processed within AI Docs.