Getting started

Everything a new site needs, in order. Steps 1 to 3 take five minutes; the rest adds revenue and search data when you are ready.

1. Create an account at Sign up, then choose Add a site with a name and your domain (example.com covers www and other subdomains too).
2. Save the secret key shown once after creating the site (ana_sec_…) in your server's environment, e.g. METRICRAVEN_SECRET_KEY. It records payments and sign-ups and reads reports. Never put it in browser code. Lost it? Create a new site.
3. Install the script (Install). Open your site, then the dashboard: you appear under Visitors now within seconds. Using a cookie banner? Wire it up as in Consent.
4. Exclude yourself and internal pages: in Settings → Exclusions add paths like /admin/*, your IP, or staging hostnames. Or visit your site once with ?ana_ignore=true.
5. Mark your goals: sign-up buttons, checkout, pricing views (Goals), then build funnels in Conversions → Edit funnels.
6. Connect revenue: pass window.analytics.getVisitorId() into your checkout (e.g. Stripe metadata) and send each payment from your server (Payments). Call Identify when users sign in so their visits and payments join up.
7. Add Search Console for keywords (Search Console) and, optionally, crawler tracking (Crawlers).
8. Share it: invite teammates by giving them the secret key (they choose Add an existing site), or create a read-only share link (Share & embed).

Install

Add the script to every page, before </head>. Your site ID is in the dashboard under Settings.

<script
  defer
  src="https://metricraven.com/js/script.js"
  data-site-id="ana_pub_…"
></script>

That records pageviews (including client-side navigation in React, Next.js and other SPAs), time on page, sources and UTM tags, devices, locations and clicks on links to other sites.

Not tracked: automated browsers, pages inside iframes, and your own browser once you set localStorage.ana_ignore = "true". Exclude paths, IPs, countries or hostnames in Settings.

Goals

Any click on an element with data-goal is a goal. Other data-goal-* attributes become its properties.

<button data-goal="signup_clicked" data-goal-plan="pro">Start free trial</button>

Scroll goals fire when an element comes into view:

<section data-scroll-goal="pricing_seen" data-scroll-threshold="0.5">…</section>

From JavaScript (calls made before the script loads are queued):

window.analytics = window.analytics || { q: [] };
window.analytics.q.push(["track", "checkout_started", { plan: "pro" }]);
// or, once loaded:
window.analytics.track("checkout_started", { plan: "pro" });

Up to 10 properties per event. ?ref=, ?via= and ?source= on a landing URL are kept as the visit's ref tag.

Consent

Until consent is given, nothing is stored in the browser: the server derives an anonymous ID that changes every day. After consent, a first-party ID is kept for a year so visits on different days connect.

<script>window.analyticsConsent = true</script> <!-- before the tag, if already granted -->
window.analytics.setConsent(true)  // when the visitor accepts
window.analytics.setConsent(false) // when they withdraw

Serve from your domain

Ad blockers often block third-party analytics. Serve the script and the event endpoint from your own domain and pass the visitor's IP on, so locations stay accurate:

<script defer src="/a/s.js" data-api="/a/e" data-site-id="ana_pub_…"></script>

// GET  /a/s.js → fetch https://metricraven.com/js/script.js and return it
// POST /a/e    → forward the body to https://metricraven.com/api/v1/collect with
//               x-visitor-ip: <the visitor's IP>, Origin and User-Agent

Payments

Send each payment from your server with your secret key. Include the visitor ID (window.analytics.getVisitorId(), passed through your checkout) or your user ID to credit it to the visit that brought the customer.

POST https://metricraven.com/api/v1/payments
Authorization: Bearer ana_sec_…

{ "amount": 29, "currency": "USD", "transaction_id": "ch_123",
  "visitor_id": "…", "user_id": "42", "plan": "pro", "renewal": false }

transaction_id makes it idempotent. For a refund, send the same transaction_id with "refunded": true and the total refunded so far as amount.

Identify users

Link a visitor to your user when they sign in, so their visits, goals and payments form one journey.

POST https://metricraven.com/api/v1/identify
Authorization: Bearer ana_sec_…

{ "visitor_id": "…", "user_id": "42", "email": "[email protected]", "name": "Ana" }

Server events

Things only your server knows, such as an account created or onboarding finished, recorded as goals for that user:

POST https://metricraven.com/api/v1/events
Authorization: Bearer ana_sec_…

{ "name": "signup", "user_id": "42", "props": { "plan": "free" } }

Crawlers

Crawlers rarely run JavaScript. Report their requests from your server or edge middleware, and MetricRaven classifies the bot (GPTBot, ClaudeBot, Googlebot…):

POST https://metricraven.com/api/v1/crawls
Authorization: Bearer ana_sec_…

{ "url": "https://example.com/pricing", "userAgent": "<request user agent>", "status": 200 }

Search Console

Show your Google keywords and landing pages next to your traffic, with revenue estimated per keyword:

1. In Google Search Console, open your property → Settings → Users and permissions → Add user, enter [email protected] and choose Restricted(read-only).
2. In the dashboard, Settings → Search Console, enter the property exactly as Google names it: sc-domain:example.com for a domain property, or https://example.com/ for a URL-prefix one.
3. Open Traffic: the Search Console card shows clicks, impressions, CTR and position. Google's data arrives about two days late.

Share & embed

Settings → Share & embed creates a read-only link. It shows every report except live visitors and journeys, without anyone's name or email. Replace the link to cut off old copies, or turn sharing off.

<iframe src="https://metricraven.com/share/shr_…?embed=1&theme=light"
        style="width:100%;height:1600px;border:0" loading="lazy"></iframe>

embed=1 drops the header; theme=light or theme=dark matches your page.

Reports API

Every report in the dashboard is also an API, read with your secret key:

Ranged reports take from and to (ISO dates), granularity (hour, day, week) and optional filters, a JSON list such as [{"dim":"country","value":"US"}].

Erase a person

For data deletion requests. Their events and identity links are deleted; payments stay in revenue totals without pointing to them.

DELETE https://metricraven.com/api/v1/people
Authorization: Bearer ana_sec_…

{ "user_id": "42" }   // or { "email": "…" } or { "visitor_id": "…" }