Starport analytics

Overview

A Starport site reports reader search and assistant activity through the analytics tools you already run. The site emits a browser event for each search and assistant interaction, and you forward those events to your analytics provider. Use this when you want to see what readers search for, which results they open, and what they ask the site assistant. If you gave Promptless a PostHog project key during setup, your site also reports page views and searches to PostHog.

For the full capability list, see What’s included in Starport.

Before you start

• Your analytics provider’s browser SDK, and access to add it to your Starport site.
• Your organization’s consent setup for analytics. Search and assistant events carry what readers type, so connect them only through that setup.

Forward Starport events to your analytics provider

The site dispatches a starport:analytics event on window for each search and assistant interaction. Each event’s detail holds the event name and its properties. Every event includes page_url, the path of the page the reader was on.

1. Load your provider’s browser SDK on your Starport site, for example through Starlight’s head configuration in astro.config.mjs.

2. Add a listener that forwards each starport:analytics event to your provider:

   // Illustrative: your provider's browser SDK is loaded as `myAnalytics`.
   window.addEventListener('starport:analytics', (event) => {
     const { name, properties } = event.detail;
     myAnalytics.track(name, properties);
   });

3. Deploy the change, run a search on the published site, and confirm that the event appears in your provider’s dashboard.

Your provider then records the events listed here:

Event	When it fires	Properties besides page_url
search_query	A reader runs a search.	query, results, latency_ms, query_ms
search_result_click	A reader opens a search result.	query, url, position, source (search, recent, or starter)
search_error	A search fails.	code
assistant_question	A reader asks the site assistant a question.	question, question_length
assistant_source_click	A reader opens a page the assistant cited.	url
assistant_latency	The assistant starts or finishes an answer.	stage (first_text or complete), latency_ms, interrupted
assistant_error	The assistant can’t finish an answer.	code
assistant_feedback	A reader rates an answer.	message_id, value (up or down)

To switch providers, change the listener.

Read docs analytics in PostHog

If you gave Promptless a PostHog project key during setup, Promptless sets it as the site’s PUBLIC_POSTHOG_KEY and manages it for you. Your site then reports page views, searches, and search-result clicks to that PostHog project.

1. In PostHog, open the project whose key you gave Promptless.

2. Look for the $pageview, docs_search, and docs_search_result_clicked events from your docs site.

To let Promptless read that data back and find the pages that need work, connect PostHog read-only. See Connect PostHog.

See also

• Monitor a Starport site through read-only connections, to let Promptless read your deploy status and reader analytics.
• Data handling and classification, for what Promptless processes and retains.
• Reporting and ROI, for documentation impact across Promptless.