Intlayer Analytics Documentation

@intlayer/analytics is an optional companion package that tells you which content is actually shown to your visitors — which page, in which locale, and which specific piece of translated content — so you can understand your audience and run A/B tests on content.

Table of Contents

What it tracks

@intlayer/analytics batches three kinds of anonymous events:

Events are collected in memory and sent as a single batched request roughly every 20 seconds — never on every keystroke or render — so analytics never impacts first render time or adds a request per interaction.

How it powers A/B testing on content

Intlayer already lets you declare content Variants (e.g. a hero-banner dictionary with a default and a black_friday variant). @intlayer/analytics closes the loop:

1. useExperiment(experimentKey, variants) deterministically assigns each anonymous session to a variant — a pure function of the session id and the experiment key, so the assignment is stable across the session and requires no server round-trip before first render (no flicker, no layout shift).
2. Every content_exposure event carries the variant that was shown.
3. useConversion() lets you attribute a goal (e.g. "cta_click") to that variant.
4. The dashboard's experiment results endpoint compares conversion rates per variant, including statistical significance (a z-test).

Installation

@intlayer/analytics is an optional dependency of every framework package (react-intlayer, next-intlayer, vue-intlayer, …), so most projects already have it. Install it explicitly if your setup skips optional dependencies (npm install --no-optional, NODE_ENV=production installs of some package managers, …):

npm install @intlayer/analytics

Installing the package is all it takes to turn analytics on: analytics.enabled defaults to true, and Intlayer resolves it to false whenever the package cannot be found in your project. If you don't install it, every integration point resolves to a no-op — see Zero-cost when not installed below.

Configuration

Analytics needs no configuration to start: it is enabled by default and reuses the existing editor configuration block for its endpoint and project key.

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  editor: {
    backendURL: "https://back.intlayer.org", // Also used as the analytics ingestion endpoint
    clientId: "your-client-id", // Also used as the analytics project key
    clientSecret: "your-client-secret",
  },
};

export default config;

• editor.backendURL — the base URL analytics events are sent to (POST {backendURL}/api/analytics/events).
• editor.clientId — the public project key. It identifies the project when the SDK requests an ingest token, and acts as an enable switch: analytics stays fully disabled (and tree-shaken, see below) until clientId is configured.
• editor.clientSecret — never used by analytics, and never sent to the browser. It is a server-only credential; see How events are authenticated.

If you self-host Intlayer, analytics automatically points at your own instance since it shares editor.backendURL.

Calling the API from the browser

The same token backs a small credential-free client, so a static site or SPA can read its CMS content at runtime with no server, no server action, and no secret in the bundle:

import { createPublicClient } from "@intlayer/api/public";

const client = createPublicClient();

const keys = await client.getDictionaryKeys();
const [navbar] = await client.getDictionaries(["navbar"]);

It authenticates itself from editor.clientId — the exchange, caching and renewal are handled internally. The scopes bound what it can reach: published dictionary content and analytics ingestion. Anything else (pushing dictionaries, reading a project, spending AI credits) needs a real credential, and therefore a server or a signed-in user.

Opting out

The optional analytics block tunes — or turns off — the collection:

import type { IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  analytics: {
    enabled: false, // Default: true — opts the whole integration out of the bundle
    flushInterval: 20_000, // Milliseconds between two batched flushes
    sampleRate: 1, // Fraction of sessions to record, from 0 (none) to 1 (all)
  },
};

export default config;

Uninstalling @intlayer/analytics has the same effect as enabled: false. See the Configuration reference for the full field list.

Usage

Automatic provider-level tracking

No code changes are required. Once @intlayer/analytics is installed and editor.clientId is configured, the Intlayer provider you already mount automatically:

• initializes the analytics client on mount,
• records a page_view on initial load,
• records a page_view on every locale change,
• starts the ~20s flush loop and flushes any remaining events on unmount / tab close (via navigator.sendBeacon, falling back to fetch(..., { keepalive: true })).

The entry point differs per framework — but in every case it is the same one you already use to set Intlayer up, so there is nothing extra to add:

import { IntlayerProvider } from "react-intlayer";

const App = () => (
<IntlayerProvider>
  <Router />
</IntlayerProvider>
);

import { IntlayerProvider } from "next-intlayer";

const LocaleLayout = ({ children }) => (
<IntlayerProvider>{children}</IntlayerProvider>
);

export default LocaleLayout;

import { createApp } from "vue";
import { intlayer } from "vue-intlayer";
import App from "./App.vue";

const app = createApp(App);

app.use(intlayer);

app.mount("#app");

<script lang="ts">
import { setupIntlayer } from "svelte-intlayer";
import type { Snippet } from "svelte";

let { children, data }: { children: Snippet, data: LayoutData } = $props();

$effect(() => {
  setupIntlayer(data.locale);
});
</script>

{@render children()}

import { IntlayerProvider } from "preact-intlayer";

const App = () => (
<IntlayerProvider>
  <Router />
</IntlayerProvider>
);

import { IntlayerProvider } from "solid-intlayer";

const App = () => (
<IntlayerProvider>
  <Router />
</IntlayerProvider>
);

import { provideIntlayer } from "angular-intlayer";
import type { ApplicationConfig } from "@angular/core";

export const appConfig: ApplicationConfig = {
providers: [provideIntlayer()],
};

Automatic node-level tracking

Every time useIntlayer resolves a piece of content for display, the interpreter reports a content_exposure event for that exact dictionaryKey + key path + locale — again, no code changes required. Repeated exposures of the same node within a flush window are coalesced into a single event with a count, so a list re-rendering 50 times doesn't send 50 events.

Tracking conversions for A/B tests

useConversion() returns a callback that attributes a goal to the variant a session saw. It is exported from every framework package, with the same signature:

import { useConversion } from "react-intlayer";

const CTAButton = () => {
const trackConversion = useConversion();

return (
  <button
    onClick={() =>
      trackConversion({
        experimentKey: "homepage-hero",
        variant: "black_friday",
        goal: "cta_click",
      })
    }
  >
    Get started
  </button>
);
};

"use client";

import { useConversion } from "next-intlayer";

const CTAButton = () => {
const trackConversion = useConversion();

return (
  <button
    onClick={() =>
      trackConversion({
        experimentKey: "homepage-hero",
        variant: "black_friday",
        goal: "cta_click",
      })
    }
  >
    Get started
  </button>
);
};

<script setup lang="ts">
import { useConversion } from "vue-intlayer";

const trackConversion = useConversion();
</script>

<template>
<button
  @click="
    trackConversion({
      experimentKey: 'homepage-hero',
      variant: 'black_friday',
      goal: 'cta_click',
    })
  "
>
  Get started
</button>
</template>

<script lang="ts">
import { useConversion } from "svelte-intlayer";

const trackConversion = useConversion();
</script>

<button
onclick={() =>
  trackConversion({
    experimentKey: "homepage-hero",
    variant: "black_friday",
    goal: "cta_click",
  })}
>
Get started
</button>

import { useConversion } from "preact-intlayer";

const CTAButton = () => {
const trackConversion = useConversion();

return (
  <button
    onClick={() =>
      trackConversion({
        experimentKey: "homepage-hero",
        variant: "black_friday",
        goal: "cta_click",
      })
    }
  >
    Get started
  </button>
);
};

import { useConversion } from "solid-intlayer";

const CTAButton = () => {
const trackConversion = useConversion();

return (
  <button
    onClick={() =>
      trackConversion({
        experimentKey: "homepage-hero",
        variant: "black_friday",
        goal: "cta_click",
      })
    }
  >
    Get started
  </button>
);
};

import { Component } from "@angular/core";
import { useConversion } from "angular-intlayer";

@Component({
selector: "app-cta-button",
template: `<button (click)="onClick()">Get started</button>`,
})
export class CtaButtonComponent {
private trackConversion = useConversion();

onClick() {
  this.trackConversion({
    experimentKey: "homepage-hero",
    variant: "black_friday",
    goal: "cta_click",
  });
}
}

Resolving a variant client-side

useExperiment() assigns the session to a variant and records the exposure that becomes the denominator of the conversion rate. Gate the variant-aware subtree on isAssigned so no visitor sees the control flash before the assignment resolves:

import { useExperiment } from "react-intlayer";
import { HeroBanner } from "./HeroBanner";

export const Hero = () => {
const { variant, isAssigned } = useExperiment("homepage-hero", [
  "default",
  "black_friday",
]);

if (!isAssigned) return null;

return <HeroBanner variant={variant} />;
};

"use client";

import { useExperiment } from "next-intlayer";
import { HeroBanner } from "./HeroBanner";

export const Hero = () => {
const { variant, isAssigned } = useExperiment("homepage-hero", [
  "default",
  "black_friday",
]);

if (!isAssigned) return null;

return <HeroBanner variant={variant} />;
};

<script setup lang="ts">
import { useExperiment } from "vue-intlayer";
import HeroBanner from "./HeroBanner.vue";

const { variant, isAssigned } = useExperiment("homepage-hero", [
"default",
"black_friday",
]);
</script>

<template>
<HeroBanner v-if="isAssigned" :variant="variant" />
</template>

<script lang="ts">
import { useExperiment } from "svelte-intlayer";
import HeroBanner from "./HeroBanner.svelte";

const { variant, isAssigned } = useExperiment("homepage-hero", [
  "default",
  "black_friday",
]);
</script>

{#if $isAssigned}
<HeroBanner variant={$variant} />
{/if}

import { useExperiment } from "preact-intlayer";
import { HeroBanner } from "./HeroBanner";

export const Hero = () => {
const { variant, isAssigned } = useExperiment("homepage-hero", [
  "default",
  "black_friday",
]);

if (!isAssigned) return null;

return <HeroBanner variant={variant} />;
};

import { useExperiment } from "solid-intlayer";
import { Show } from "solid-js";
import { HeroBanner } from "./HeroBanner";

export const Hero = () => {
const { variant, isAssigned } = useExperiment("homepage-hero", [
  "default",
  "black_friday",
]);

return (
  <Show when={isAssigned()}>
    <HeroBanner variant={variant()} />
  </Show>
);
};

import { Component } from "@angular/core";
import { useExperiment } from "angular-intlayer";
import { HeroBannerComponent } from "./hero-banner.component";

@Component({
selector: "app-hero",
imports: [HeroBannerComponent],
template: `@if (experiment.isAssigned()) {
  <app-hero-banner [variant]="experiment.variant()" />
}`,
})
export class HeroComponent {
experiment = useExperiment("homepage-hero", ["default", "black_friday"]);
}

Weights are optional — pass one per variant to skew the split, e.g. useExperiment("homepage-hero", ["default", "black_friday"], [9, 1]).

The child then reads the Variant of the dictionary that matches:

import { useIntlayer } from "react-intlayer";

export const HeroBanner = ({ variant }: { variant: string }) => {
  const { headline, cta } = useIntlayer("hero-banner", { variant });

  return (
    <section>
      <h1>{headline}</h1>
      <a>{cta}</a>
    </section>
  );
};

Reading the variant in a child is what makes this work outside React: in Vue, Svelte, Solid, and Angular the selector passed to useIntlayer is captured when the component sets up, so the read has to happen in a component that only mounts once the variant is known.

If the experiment covers a whole page rather than a single dictionary, hoist the variant onto the provider instead — see Ambient variant. Every useIntlayer below then resolves against it with no call-site change.

If you need the raw assignment outside of a component, reach for the client directly:

import { getGlobalAnalyticsClient } from "@intlayer/analytics/client";

const client = getGlobalAnalyticsClient();
const variant = client?.getVariant("homepage-hero", [
  "default",
  "black_friday",
]);

getVariant only assigns — it does not record the exposure. Prefer useExperiment(), otherwise the conversion rate has no denominator.

Privacy & performance

• Anonymous by design: sessions are identified by a rotating id; the backend only ever stores a SHA-256 hash of that id — never the raw id, never an IP address.
• Location is coarse: only a country code, derived from CDN geolocation headers (cf-ipcountry, x-vercel-ip-country, …) — no IP is read or stored.
• URLs exclude search params by default, so query strings are never captured.
• Sampling: sampleRate lets you keep only a fraction of content-exposure events on high-traffic apps.
• Batched: one request roughly every 20 seconds (flushInterval), or earlier if the buffer fills up (maxBufferSize) — never one request per event.

Zero-cost when not installed

@intlayer/analytics follows the exact same optional-dependency pattern as @intlayer/editor:

• every integration point loads the package via a dynamic import() wrapped in try/catch — an app that never installs @intlayer/analytics never pays a bundle-size or runtime cost, and never sees an error;
• a compile-time env var (INTLAYER_ANALYTICS_ENABLED), automatically set to 'false' whenever the package is not installed, analytics.enabled is false, or editor.clientId is not configured, lets bundlers dead-code-eliminate the whole integration;
• analytics is disabled inside the Intlayer editor/CMS preview iframe, so editor sessions are never counted as real traffic.

Dashboard: Analytics page

Once your project has collected events, the Analytics page in the Intlayer dashboard (visible in the sidebar once a project is selected) shows:

• Active users — distinct visitors over the selected rolling window (7 / 30 / 90 days).
• Users today and users over the last 7 days.
• Page views over the selected window.
• An evolution graph of daily distinct visitors.
• Locales and Location breakdown tabs, ranking your audience by locale and by country.

Backend API reference

All read endpoints require authentication; the token exchange and ingestion are public.

You can also call these programmatically with the CMS SDK:

import { createIntlayerCMS } from "@intlayer/api";
import { analyticsEndpoint } from "@intlayer/api/analytics";

const cms = createIntlayerCMS();

const { data: audience } = await analyticsEndpoint(cms).getAudience(30);

Server-side only. createIntlayerCMS() authenticates with clientId + clientSecret, and the secret is never available in the browser — this snippet would issue unauthenticated requests if it ran there. Keep it in a route handler, server action, or script.

Useful links

• Dynamic Dictionaries - Collections & Variants
• Intlayer CMS - CMS SDK
• Intlayer Visual Editor
• Configuration Reference
• Self-Hosting Guide