Developer documentation

Quickstart

1. In the portal, add a site with your website's origin, such as https://www.example.com.
2. Publish the DNS TXT record the portal shows, then choose Verify. Verification asks your domain's own nameservers, so it passes as soon as the record is published.
3. Turn recording on in the site's Recording tab.
4. Add the install snippet from the Installation tab to every page, and call the consent function from your consent banner.

Recordings appear under Recordings in the portal within seconds of a visitor agreeing.

Install and consent

Copy the snippet from the site's Installation tab: it names the current release and carries its Subresource Integrity hash and your site's public key.

<script async
  src="https://analytics.ironfang.uk/sdk/0.1.1/loader.js"
  integrity="sha384-..."
  crossorigin="anonymous"
  referrerpolicy="no-referrer"
  data-site-key="ifa_site_..."
></script>

The snippet makes no request and records nothing until your page grants consent. Call this from your consent banner once the visitor agrees, before or after the snippet loads:

window.ironfangAnalytics = window.ironfangAnalytics || [];
ironfangAnalytics.push(['setConsent', { replay: true }]);

When the visitor withdraws it, recording stops and anything not yet sent is discarded in the browser:

ironfangAnalytics.push(['setConsent', { replay: false }]);

A visit across several pages in the same tab continues one recording. If your site has a Content Security Policy, allow https://analytics.ironfang.uk in script-src and connect-src.

What is recorded

The page as it was displayed, and the scrolling, pointer movement, clicks and page changes on it. Masking happens in the visitor's browser, before anything is sent:

• Every form field's value is replaced with placeholders, whatever the site settings say.
• Password, payment card and sign-in fields are blocked: they appear as empty boxes of the same size.
• With Mask all text on (the default), page text is masked too; list selectors whose text is safe to show.
• Regions matching your block selectors, or carrying the rr-block class, are never recorded.
• Recorded URLs keep no query values and no fragments except the parameters you allow, such as utm_source.

Beside each recording Ironfang keeps the visitor's IP address and whether Cloudflare reported it, the full user agent, window and screen size, pixel ratio, language, time zone, country and the page they came from without its query. All of it is deleted with the recording. Your privacy notice should say that you record sessions and keep these details.

Sites and origins

A site is one website: the origins its recorder may send from, a public collection key and what it captures. A public origin must be verified before it records: publish _ironfang-analytics.<host> as a TXT record with the value the portal shows. Loopback origins such as http://localhost:3000 need no record, for development.

The public key is safe to publish: it can only ask to record for its own site. Rotating it keeps the old key working for 24 hours so cached pages keep recording.

Recordings

Search recordings across every site by date, state, country, device class, browser, operating system, IP address or network in CIDR notation, and entry path. A recording opens on its replay and the visitor details kept with it.

A recording is one browser tab on one site. It ends when the visitor leaves, after 30 minutes with nothing received, or at 60 minutes or 100 MiB, whichever comes first. Deleting a recording removes its replay and every detail kept with it at once.

API keys and scopes

Platform API keys are minted in the portal and start with if_live_. Send one as a bearer token; it acts only in the organisation it was minted for.

Authorization: Bearer if_live_...

• analytics:sites:readRead sites, their origins, keys, settings history and installation state
• analytics:sites:writeCreate and change sites, add and verify origins, rotate the public key
• analytics:sessions:readSearch and read recordings, with their visitor details, and fetch their playback batches
• analytics:sessions:deleteDelete a recording
• analytics:*All Ironfang Analytics scopes

Errors

Every error is a JSON object with a stable code, a message for people and the request id to quote to support.

{
  "error": {
    "code": "not_found",
    "message": "no such object in this organisation",
    "docs": "https://ironfang.uk/analytics/docs#errors"
  },
  "request_id": "01a0c375-7bae-7f02-a3d4-91e6b8c25f70"
}

Limits and retention

• Recordings are kept 28 days from when they start, then deleted with every detail kept with them.
• The Free plan includes 1,000 recordings a month and 2 GiB of stored recordings; paid plans are on the pricing section.
• When a month's recordings are used up, new visits are not recorded until the next month. Pages keep working and recordings already made are unaffected.
• Up to 100 sites per organisation. A recording ends at 60 minutes or 100 MiB compressed.
• Lists page with cursor and limit, up to 100 per page.

API reference

Base URL https://api.ironfang.uk/analytics. The OpenAPI 3.1 document at https://api.ironfang.uk/analytics/openapi.yaml carries every schema and error, with stable operation ids for generated clients.

Machine interfaces