Browser (JavaScript)

@mirafive/sdk-browser is the JavaScript client for any frontend you bundle (Vite, webpack, esbuild, Rollup) without a MIRA FIVE framework package: Svelte, Solid, Angular, Lit or plain TypeScript. It is also the client the React and Vue packages wrap. No build step? Use the script tag. On Next.js, TanStack Start, Nuxt or Astro, use their framework packages.

InstallCopy Anchor Link

npm install @mirafive/sdk-browser

The package is ESM only, has no dependencies and is built for ES2022 browsers. Every feature is its own import, and what you do not import is not shipped:

Each plugin is measured as a bundler adds it to a page that already has the core.

Set upCopy Anchor Link

You need the website key of a website source (mf_…). See Keys for where to find it. Put it in your bundler's public env var:

VITE_MIRAFIVE_KEY=mf_…

Create the client once, in code that runs only in the browser, and export it:

import { createMira } from '@mirafive/sdk-browser'
import { pageviews } from '@mirafive/sdk-browser/pageviews'

export const mira = createMira({
  key: import.meta.env.VITE_MIRAFIVE_KEY,
  plugins: [pageviews()],
})

Import that module from your entry point. pageviews() records the landing page and every client-side navigation for any router. You do not add a router hook.

The client starts in consentless mode: it sets no cookies, stores nothing on the device, never reads the browser's language, time zone or screen size, and needs no consent banner.

VerifyCopy Anchor Link

1. Open the app on its real domain. Events from localhost, 127.*, [::1], *.local and file: are dropped unless you pass trackLocalhost: true.
2. In the browser's network tab, look for POST https://events.mirafive.io/v1/batch/mf_…. Batches leave 5 seconds after the first event, after 20 events, or when the tab is hidden. Call mira.flush() to send at once.
3. It answers 202:

{ "batch": "…", "accepted": 1, "dropped": 0 }

4. Open the source's live view in MIRA FIVE and find the pageview.

Nothing arriving? See Troubleshooting.

Track eventsCopy Anchor Link

Call track(name, properties) where the thing happens:

import { mira } from './mira'

document.querySelector('#signup')?.addEventListener('submit', () => {
  mira.track('signup', { plan: 'pro' })
})

Names are 1 to 128 characters, cannot start with $ and cannot start or end with whitespace. The core drops an event the server would refuse, with a development warning, so it cannot take its batch down: properties over 32 KB of JSON, over 64 leaf values, deeper than 5 levels, a key over 128 characters, or a string with a lone surrogate. Event names, property limits and revenue are covered in Track events.

Name your events in a type to have TypeScript check every call. Typed events are types only and add nothing to the bundle:

import { createMira } from '@mirafive/sdk-browser'
import { pageviews } from '@mirafive/sdk-browser/pageviews'

type Events = {
  signup: { plan: string }
  logout: undefined
}

export const mira = createMira<Events>({
  key: import.meta.env.VITE_MIRAFIVE_KEY,
  plugins: [pageviews()],
})

mira.track('signup', { plan: 'pro' }) // checked
mira.track('logout') // properties optional

To record clicks, form submits and field changes without code, add autocapture():

import { autocapture } from '@mirafive/sdk-browser/autocapture'

const mira = createMira({ key: import.meta.env.VITE_MIRAFIVE_KEY, plugins: [pageviews(), autocapture()] })

It sends $autocapture for a, button, input, select, textarea and elements with a button, link, tab or menuitem role. It records the tag, a short selector, the id and classes (generated names skipped), link and button text, the cleaned href, name, type, and data-testid, data-test, data-cy, data-qa, data-track plus any selectorAttributes you pass. It never records what a visitor typed, and skips password, email and hidden inputs and everything inside [data-mira-no-capture]. Autocapture works in both modes.

Identify usersCopy Anchor Link

Identifying users needs full mode and the identity() plugin:

import { createMira } from '@mirafive/sdk-browser'
import { identity } from '@mirafive/sdk-browser/identity'
import { pageviews } from '@mirafive/sdk-browser/pageviews'

export const mira = createMira({
  key: import.meta.env.VITE_MIRAFIVE_KEY,
  mode: 'full',
  plugins: [pageviews(), identity()],
})

// After login, once the visitor granted statistics consent
mira.identify(user.id, { plan: user.plan })

// After logout
mira.reset()

identify sends $identify and puts the user id on every later event. Ids are 1 to 256 characters; numbers are turned into strings. When a different user signs in on the same browser, the anonymous and session ids start fresh.

Events before statistics consent are dropped, $identify included. The user id is kept in memory and stamped on later events, but call identify again after the grant if you need the $identify event.

To link server-side events to the visitor, send mira.anonymousId() to your server. It is undefined without statistics consent. See Identify users.

ConsentCopy Anchor Link

In full mode, nothing is sent and nothing is stored until the visitor answers. Pass the answer with consent():

The landing pageview is sent when consent is first granted, so a visitor who accepts on the first page still counts that page. Wire your consent manager's callback to it. statistics is the usual "analytics" category, targeting the "marketing" one:

import { mira } from './mira'

// Cookiebot
window.addEventListener('CookiebotOnConsentReady', () => {
  const { statistics, preferences, marketing } = Cookiebot.consent
  mira.consent({ statistics, experiments: preferences, targeting: marketing })
})

// OneTrust (default group ids: C0002 performance, C0003 functional, C0004 targeting)
window.OptanonWrapper = () => {
  const groups = window.OnetrustActiveGroups ?? ''
  mira.consent({
    statistics: groups.includes(',C0002,'),
    experiments: groups.includes(',C0003,'),
    targeting: groups.includes(',C0004,'),
  })
}

If the answer is known before the client starts, set window.__mirafive_consent = { statistics, experiments, targeting } (or false) first. identity() applies it at creation, so the landing pageview is counted with the answer ($boot: 1).

Full mode stores, in localStorage only and never in cookies, mirafive:{namespace}:aid (the anonymous id, kept 365 days since last seen), :sid (the session, 30 minutes idle) and :uid (a hash of the user id). The namespace is the key without its last _… part.

Do Not Track, Global Privacy Control, window.__mirafive_ignore = true (set it for your own visits) and prerendering send nothing in either mode. A prerendered page sends once it is shown. See Consent.

Feature flagsCopy Anchor Link

Add flags(), then read flags in an onFlags listener. It runs once flags have loaded, and again whenever they change:

import { createMira } from '@mirafive/sdk-browser'
import { flags } from '@mirafive/sdk-browser/flags'
import { pageviews } from '@mirafive/sdk-browser/pageviews'

export const mira = createMira({
  key: import.meta.env.VITE_MIRAFIVE_KEY,
  plugins: [pageviews(), flags()],
})

mira.onFlags(() => {
  const newCheckout = mira.flag('new-checkout', false)
  const limits = mira.config('checkout-limits', { maxItems: 10 })

  document.body.classList.toggle('new-checkout', newCheckout === true)
  document.querySelector('#max-items')!.textContent = String(limits.maxItems)
})

• flag(key, fallback) returns the variant key, or true/false for an on/off flag. It returns the fallback until flags load, and for a flag this source does not have (with a development warning).
• config(key, fallback) returns the remote-config value of the variant.
• setFlagProperties(properties) passes facts for targeting rules. They stay in memory and are never sent.

The plugin fetches the source's flags at start, every refreshSeconds (300) while the page is visible, when the page becomes visible again and when the URL changes. In consentless mode it fetches only the answers; in full mode it evaluates rules in the browser, and with targeting consent it also looks up the visitor's segments. If the page has a <script type="application/json" id="mirafive-flags"> block from a server SDK, the first read already has its answers: see Feature flags.

To preview a variant, open the page with ?mirafive-preview=new-checkout:b. To pin answers in development, pass overrides (full mode only): flags({ overrides: { 'new-checkout': true } }). Previews and overrides are never counted.

ExperimentsCopy Anchor Link

Code experiments are flags: read them with flag(). In full mode, with statistics and experiments consent, the client sends one $exposure per flag and page load for experiments counted in the browser. An experiment keeps the variant the page first showed until the page reloads, unless the experiment is turned off.

Page experiments are drawn before the page renders by a head snippet that MIRA FIVE generates. To count them, add experiments() after flags(), in full mode:

import { createMira } from '@mirafive/sdk-browser'
import { experiments } from '@mirafive/sdk-browser/experiments'
import { flags } from '@mirafive/sdk-browser/flags'
import { identity } from '@mirafive/sdk-browser/identity'
import { pageviews } from '@mirafive/sdk-browser/pageviews'

export const mira = createMira({
  key: import.meta.env.VITE_MIRAFIVE_KEY,
  mode: 'full',
  plugins: [pageviews(), identity(), flags(), experiments()],
})

It sends $exposure for each page experiment the snippet drew (window.__mirafive_experiments), once the experiments scope is granted. See Experiments.

Single-page appsCopy Anchor Link

• pageviews() listens to the Navigation API's navigatesuccess where the browser has it, else patches pushState and replaceState and listens to popstate. The title is read one task after the URL changes, so a router has time to set it.
• A navigation that leaves the cleaned URL unchanged is not a new view. The cleaned URL keeps only utm_*, ref, source and click-id parameters, and drops the fragment.
• Hash routing (/#/pricing): pass pageviews({ hash: true }). Hash changes become pageviews and the fragment is kept.
• After the first view, the referrer is the previous page.
• For full control, leave out pageviews() and call mira.pageview() after each route change.

Create one client per page. A second createMira while one is running stays inert and warns in development. destroy() stops timers and listeners, undoes the history patch, drops the queue and releases the page, so a component that creates the client on mount and destroys it on unmount (React StrictMode mounts twice) works. createMira needs window: do not call it during a server render.

Writing a pluginCopy Anchor Link

A plugin is { name, setup(core) }. setup may return a teardown that destroy() runs. Plugins given to createMira are set up in order during creation; use() adds one later.

import type { Plugin } from '@mirafive/sdk-browser'

export const outboundLinks = (): Plugin => ({
  name: 'outbound-links',
  setup(core) {
    const onClick = (event: MouseEvent) => {
      const link = (event.target as Element | null)?.closest('a')

      if (link && link.host !== location.host) {
        core.send('outbound_link', { host: link.host }, { url: core.clean(location.href) })
      }
    }

    document.addEventListener('click', onClick, true)

    return () => document.removeEventListener('click', onClick, true)
  },
})

setup receives MiraCore:

In mode 'full' the core sends nothing until state.mode is 'full', whichever plugins are present.

API referenceCopy Anchor Link

import { createMira } from '@mirafive/sdk-browser'
import { autocapture } from '@mirafive/sdk-browser/autocapture'
import { experiments } from '@mirafive/sdk-browser/experiments'
import { flags } from '@mirafive/sdk-browser/flags'
import { identity } from '@mirafive/sdk-browser/identity'
import { pageviews } from '@mirafive/sdk-browser/pageviews'
import { siteSearch } from '@mirafive/sdk-browser/search'

There are no default exports.

createMiraCopy Anchor Link

createMira<Events>(options): Mira<Events>

A flushAt or flushAfterMs out of range is clamped with a development warning. createMira throws a TypeError for a secretKey option, a host without a scheme, and mode: 'full' without identity(). Nothing else throws: transport problems drop the batch with a development warning.

Client membersCopy Anchor Link

A member whose plugin is missing warns once in development and does nothing: flag and config return the fallback, onFlags returns a no-op unsubscribe.

PluginsCopy Anchor Link

pageviews options:

autocapture options:

siteSearch options:

flags options:

TypesCopy Anchor Link

import type {
  ConsentAnswer,
  EventMap,
  FlagBootstrap,
  FlagState,
  Json,
  Mira,
  MiraCore,
  MiraEvent,
  MiraHooks,
  MiraOptions,
  MiraState,
  Mode,
  Page,
  Plugin,
  Properties,
} from '@mirafive/sdk-browser'

The plugin entries also export their option types: PageviewsOptions, AutocaptureOptions, SiteSearchOptions and FlagsOptions.

Batches are text/plain POSTs to {host}/v1/batch/{key}, so they need no CORS preflight. On page hide they go by navigator.sendBeacon. A failed send is tried up to three times in all, with backoff, honouring Retry-After up to 10 seconds. The client reports mirafive-browser/1.0.0 as the SDK. If your site sends a Content Security Policy, add connect-src https://events.mirafive.io (or your host).

TroubleshootingCopy Anchor Link

Development warnings appear only on local hosts. Pass trackLocalhost: true to see events and warnings while you develop.

Set up with an AI agentCopy Anchor Link

Paste this into your coding agent:

Add MIRA FIVE analytics to this bundled frontend with @mirafive/sdk-browser.
Docs: https://docs.mirafive.io/sdks/browser.md

1. Install @mirafive/sdk-browser with the project's package manager. If the app uses React,
   Next.js, TanStack Start, Vue, Nuxt or Astro, use that MIRA FIVE package instead (see the docs).
2. Put the source's website key (mf_…) in the bundler's public env var: VITE_MIRAFIVE_KEY,
   NEXT_PUBLIC_MIRAFIVE_KEY, PUBLIC_MIRAFIVE_KEY or NUXT_PUBLIC_MIRAFIVE_KEY.
   Never put MIRAFIVE_SECRET_KEY in browser code.
3. In a module that runs once and only in the browser, add:
     import { createMira } from '@mirafive/sdk-browser'
     import { pageviews } from '@mirafive/sdk-browser/pageviews'
     export const mira = createMira({ key: <the env var>, plugins: [pageviews()] })
   Add autocapture() from '@mirafive/sdk-browser/autocapture' if clicks should be counted,
   and flags() from '@mirafive/sdk-browser/flags' if the app reads feature flags.
4. Do not add router hooks for pageviews; pageviews() covers every router.
5. Keep the default consentless mode: it needs no consent banner. Only if the site already has a
   consent manager and wants user ids: add identity() from '@mirafive/sdk-browser/identity',
   pass mode: 'full', and call mira.consent({ statistics, experiments, targeting }) from the
   consent manager's callback.
6. Verify: load a page on a non-localhost domain (or pass trackLocalhost: true), call
   mira.flush(), and check the network tab for POST https://events.mirafive.io/v1/batch/<key>
   answering 202. Report what you changed.
Do not add other analytics libraries, cookies or consent banners.