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. To stop recording a visitor, call the opt-out function from your consent banner or a link.

Recordings appear under Recordings in the portal within seconds of a visit.

Install, opt-out 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.com/sdk/0.3.1/loader.js"
  integrity="sha384-..."
  crossorigin="anonymous"
  referrerpolicy="no-referrer"
  data-site-key="ifa_site_..."
></script>

The snippet records from the first page load. To opt a visitor out, call this from your consent banner or a link, before or after the snippet loads. Recording stops, anything not yet sent is discarded in the browser, and the browser remembers the choice, so later pages do not record either:

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

If the visitor changes their mind, setConsent({ replay: true }) starts recording again.

Where the law requires consent before recording, as it usually does for visitors in the UK and the EU, turn on Ask for consent first in the site's Recording tab. The snippet the Installation tab then gives you carries data-consent="required": it makes no request and records nothing until your page calls setConsent({ replay: true }) once the visitor agrees. Deciding whether your visitors need to be asked is yours to do.

A visit across several pages in the same tab continues one recording. Once a recording starts, the browser also keeps a random visitor id in local storage and sends it with each new recording, so a second tab or a return visit can be found beside the first. It is made from nothing about the visitor, it is not a cookie, and opting out deletes it.

If your site has a Content Security Policy, allow https://analytics.ironfang.com 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:

• Anything that looks like a payment card number is masked wherever it appears: in page text, in a field or in an attribute. This is always on.
• Card number, CVV, password and one-time-code fields are blocked: they appear as empty boxes of the same size. This is always on too.
• With Mask form fields on, every field's value is replaced with placeholders, and so is text typed into an editable region (contenteditable). It is off for a new site.
• With Mask all text on, page text is masked too; list selectors whose text is safe to show. It is off for a new site.
• Regions matching your always-mask selectors have their text and fields masked either way.
• Regions matching your block selectors, or carrying the rr-block class, are never recorded.
• Recorded URLs never keep a fragment. They keep only the query parameters you list, such as utm_source, or, with Record all query parameters on, every parameter except the ones you list to remove, such as token.

To keep your own visits out of your recordings, list your home or office addresses under Excluded visitors in the site's capture settings: single addresses or ranges such as 203.0.113.0/24, or a network's /64 for IPv6. A visit from one is not recorded at all, and the settings page can add the address of the device you are using.

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, the page they came from without its query and the browser's visitor id. All of it is deleted with the recording. Your privacy notice should say that you record sessions and keep these details, and that the browser keeps a visitor id.

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, entry path and visitor id. A recording opens on its replay and the visitor details kept with it, with the same browser's other recordings beneath.

A recording whose visitor is on the site now is Live, and opens live: you see the page a second or two behind them. While you watch, their browser sends what it records every second instead of every ten seconds. Nothing on their page changes, and nothing tells them anyone is watching. A recording that is still open but has not been heard from for 90 seconds is Inactive: the visitor has most likely left.

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.com/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.com/analytics. The OpenAPI 3.1 document at https://api.ironfang.com/analytics/openapi.yaml carries every schema and error, with stable operation ids for generated clients.

Machine interfaces