Cosmic Insights

Cosmic Insights is the analytics layer of the Cosmic platform. It captures cookieless web analytics from any deployed app and joins them back to the Cosmic objects that produced the underlying content.

What you get

Web analytics: pageviews, sessions, visitors, bounce rate, sources, devices, countries.
Custom events: track signups, button clicks, anything you care about.
Conversions and revenue: pass revenue_cents and currency and the event is auto-tagged as revenue and rolled up everywhere.
Per-object attribution: every Cosmic object gets a Performance card showing pageviews, visitors, and revenue.
Agent feedback loop: a read_performance tool that lets your AI agents read their own results and propose what to do next.

Dashboard tabs

The Insights area of the dashboard has six tabs: Overview, Pages, Content, Events, Custom events, and Sources. Per-object analytics also surface as a Performance card on each object's detail page.

Metrics on the Overview

The Overview tab shows four headline tiles, each with a period-over-period delta and a click-to-chart toggle that swaps the line in the chart below.

Metric	What it counts	Direction
Visitors	Unique visitor identifiers in the range. The visitor id is a salted, daily-rotating hash, so the same browser counts as a new visitor each UTC day.	Higher is better.
Pageviews	Every page render captured by the tracker, including SPA navigations. One visitor reading three pages = three pageviews.	Higher is better (mostly: see bounce rate).
Sessions	Distinct visits, where a visit ends after 30 minutes of inactivity or when the tab closes. One visitor can have multiple sessions across the day.	Higher is better.
Bounce rate	Percent of sessions where the visitor saw a single page and triggered no other event (no clicks tracked via `data-cosmic-event`, no custom events, no conversions).	Lower is better. The tile delta colors are inverted: a drop in bounce rate is rendered green.

Each tile compares the current window to the immediately preceding window of the same length ("vs. previous 7 days" for the 7d preset, etc.) so you don't need a second chart to see whether things are trending up or down.

How to install

Two paths.

Auto-install (recommended)

If your app is built or deployed via Cosmic AI Build, the tracker is injected automatically. Set COSMIC_INSIGHTS_PROJECT to your project id in the build env (Cosmic does this for you on apps it builds).

Manual install

Drop one tag in your <head>:

<script
  defer
  src="https://insights.cosmicinsights.dev/script.js"
  data-project="YOUR_PROJECT_ID"
  data-bucket="YOUR_BUCKET_ID"
></script>

Where to find your IDs

Both IDs are the id of the underlying Cosmic resource and are not secrets.

Project ID: In the dashboard, open your project and go to Settings, Basic settings. The PROJECT ID is shown under the project description with a copy button. It also appears in the dashboard URL.
Bucket ID: In the dashboard, open the bucket and go to Settings, Basic. The BUCKET ID is shown under the bucket title with a copy button.

Optional script attributes that apply as defaults to every event from this page:

Attribute	Default for	Notes
`data-bucket`	`bucket_id`	Filters the dashboard's bucket dropdown.
`data-agent`	`agent_id`	Tags every event with the AI agent that produced the page.
`data-user`	`user_id`	Tags every event with the dashboard user that authored the page.
`data-host`	endpoint host	Override the collect endpoint (advanced).

Custom events

window.cosmicInsights('signup', { plan: 'team' });

The first argument is the event name. The second is a free-form props object. Recognized top-level fields (like revenue_cents and object_id) are promoted onto the event row; everything else is stored as JSON in event_props.

Conversions and revenue

Pass revenue_cents (number) and currency (string). The event is automatically classified as a revenue event and rolled up by source and object.

window.cosmicInsights('order_paid', {
  revenue_cents: 4900,
  currency: 'USD',
});

Object attribution

The recommended way to attribute pageviews on a static or server-rendered page is one meta tag in the <head>:

<meta name="cosmic-context"
      content='{"object_id":"OBJ_ID","object_type":"posts"}'>

That's it. The tracker parses this once on init and merges every key into every event from the page, so the per-object analytics in the dashboard light up automatically.

Per-event values passed to cosmicInsights('view', {...}) win over the meta tag, which wins over data-* script attributes.

Promotable keys: object_id, object_type, bucket_id, agent_id, automation_id, user_id, revenue_cents, currency.

When using a Cosmic AI Build, the build also emits a routes.json map that resolves path -> object_id server-side, so you don't have to remember to add the meta tag everywhere. See Attribution for the full precedence model.

Privacy

No cookies, no localStorage, no fingerprinting.
The raw IP is dropped server-side after we derive a salted hash.
Visitor identifiers mix the day into the hash input, so they reset every day at UTC midnight.
Bots are filtered out before they hit your event totals.
US data residency in v1; EU residency in v2.

Pricing

Insights is included in every Cosmic plan. See pricing for event allotments per tier.