Appearance
Single-page apps & frames
Replora works with single-page apps out of the box: it records the page continuously, so in-app navigation needs no new snapshot, and it counts every address change as a page view. This page explains how that works, when to take page views into your own hands, and how frames, several domains and subdomains are handled.
How page views are counted
A full page load records a snapshot of the page. In a single-page app the address changes without a load, so the tracker watches:
history.pushStateandhistory.replaceState(it wraps both; your router keeps working even if the tracker failed),- the
popstateevent (back and forward), - the
hashchangeevent (hash routers).
Each change to a new address counts as a page view (a navigate event): heatmaps, funnels, the session's page list and page-based surveys and A/B tests all see it. About a second later the tracker records the new document.title (apps often set it late). A change to the same address is not counted.
On every new page view form analytics, survey targeting and A/B tests are re-evaluated for the new address, and Google Analytics event names start counting afresh.
Taking page views into your own hands
Two commands change the automatic behaviour (JavaScript API):
| Command | When to use it |
|---|---|
virtualPage | Count a page view now, for steps that don't change the address (a wizard, a modal "page"), optionally with an address: __sr.push(['virtualPage', '/signup/step-2']). |
disableVirtualPage | Stop counting address changes; only virtualPage counts. For routers that rewrite the address several times per navigation, or when you want your router's view of a page. Push it before the tracker loads. |
js
window.__sr = window.__sr || [];
__sr.push(['disableVirtualPage']);
// after each navigation of your router:
__sr.push(['virtualPage', newPath]);Framework recipes
The Install page has each of these filled in with your key and server (Install › npm package › Framework).
React, Next.js, React Router, Remix
sh
npm install @replora/browser @replora/reactPlain React (the tracker counts page views itself):
tsx
import { ReploraProvider } from '@replora/react';
createRoot(document.getElementById('root')!).render(
<ReploraProvider config={{ site: 'YOUR_SITE_KEY', server: 'https://replora.example.com' }}>
<App />
</ReploraProvider>,
);Next.js App Router (app/replora.tsx, then wrap {children} in app/layout.tsx):
tsx
'use client';
import { ReploraProvider } from '@replora/react';
import { useNextPageviews } from '@replora/react/next';
function Pageviews() {
useNextPageviews();
return null;
}
export function Replora({ children }: { children: React.ReactNode }) {
return (
<ReploraProvider config={{ site: 'YOUR_SITE_KEY', server: 'https://replora.example.com', disableVirtualPage: true }}>
<Pageviews />
{children}
</ReploraProvider>
);
}| Router | Hook (inside the provider) | Import |
|---|---|---|
| Next.js App Router | useNextPageviews() | @replora/react/next |
Next.js Pages Router (pages/_app.tsx) | useNextPagesRouterPageviews() | @replora/react/next |
React Router v6/v7 (inside <BrowserRouter> or RouterProvider) | useReactRouterPageviews() | @replora/react/router |
Remix (in root.tsx, around <Outlet />) | useReactRouterPageviews() | @replora/react/router |
| Anything else | usePageviews(url) with your current address | @replora/react |
With a router hook set disableVirtualPage: true. The hooks don't count the first page (the tracker already did) and never count twice under React StrictMode. @replora/react/next needs next, @replora/react/router needs react-router-dom.
Vue and Nuxt
ts
// Vue: src/main.ts
import { init, replora } from '@replora/browser';
init({ site: 'YOUR_SITE_KEY', server: 'https://replora.example.com', disableVirtualPage: true });
router.afterEach((to) => replora.virtualPage(to.fullPath));ts
// Nuxt: plugins/replora.client.ts
import { init, replora } from '@replora/browser';
export default defineNuxtPlugin((nuxtApp) => {
init({ site: 'YOUR_SITE_KEY', server: 'https://replora.example.com', disableVirtualPage: true });
nuxtApp.$router.afterEach((to) => replora.virtualPage(to.fullPath));
return { provide: { replora } };
});SvelteKit and Astro
svelte
<!-- src/routes/+layout.svelte -->
<script>
import { browser } from '$app/environment';
import { afterNavigate } from '$app/navigation';
import { init, replora } from '@replora/browser';
if (browser) init({ site: 'YOUR_SITE_KEY', server: 'https://replora.example.com', disableVirtualPage: true });
let first = true;
afterNavigate(({ to }) => {
if (!first && to) replora.virtualPage(to.url.pathname + to.url.search);
first = false;
});
</script>
<slot />Astro (multi-page by default): init({ site, server }) in a <script> of your layout is enough.
Angular and other frameworks
Angular's router uses history.pushState, so the plain snippet in src/index.html counts page views without any code. To count them from the router instead:
ts
// app.component.ts
import { NavigationEnd, Router } from '@angular/router';
import { filter } from 'rxjs/operators';
declare global { interface Window { __sr: unknown[] } }
export class AppComponent {
constructor(router: Router) {
window.__sr = window.__sr || [];
window.__sr.push(['disableVirtualPage']);
router.events.pipe(filter((e) => e instanceof NavigationEnd)).subscribe((e) => {
window.__sr.push(['virtualPage', (e as NavigationEnd).urlAfterRedirects]);
});
}
}Server rendering
@replora/browser and @replora/react do nothing outside a browser, so they can be imported in server-rendered code. init() adds the script once, even when React renders twice in development.
Grouping changing addresses
Product pages, order pages and other addresses with ids show up as separate pages. Group them for heatmaps and funnels with pageUrl after each navigation:
js
__sr.push(['pageUrl', 'https://shop.example/product/*']);Frames and iframes
| Frame | What happens |
|---|---|
| Same domain as the page | Recorded as part of the page automatically (the recorder sees into it). Canvas drawings inside it are captured too, when canvas recording is on. |
| Another domain (a checkout, a booking widget) | Shown as an empty box, unless Record frames from other domains is on and the tracking code (same website key) is also on the framed page. Then the frame records itself and hands its recording to the page around it, so the replay shows it in place. |
For frames of other domains:
- Put the same snippet (same
data-site) on the framed pages. - Add the framed page's domain and the page's domain to the website's Allowed domains.
- Switch on Record frames from other domains (Site settings › Privacy and sampling).
A frame only hands its recording to a page on one of the website's allowed domains, never to an unknown page that frames it. Whenever the page starts over from a full snapshot (start, a retry after an outage, a new session, every 10 minutes) it asks its frames to send theirs again, so frames never go blank in the replay. Nested frames work the same way.
Masking in frames
The site's masking rules apply inside frames too (the frame loads the same rules). Payment frames of payment providers you don't control can't run your tracker, so they stay empty boxes, which is what you want.
Cross-domain sessions
Browsers keep the session (sessionStorage) per domain, so a visitor who goes from shop.example to pay.example would start a new session. To keep one session, put the same website's snippet on both domains and push the list on both:
js
__sr.push(['crossDomain', ['shop.example', 'pay.example']]);Or with the npm package: init({ …, crossDomain: ['shop.example', 'pay.example'] }).
How it works: just before a visitor follows a link to one of those domains (click, middle click, keyboard), the tracker adds _sr_x=<session id>.<last activity> to the link. The arriving page continues that session when its last activity is less than 30 minutes ago, and removes the parameter from the address bar at once. Subdomains of the listed domains count; up to 20 domains.
Forms that post to the other domain and redirects made by your server don't carry the parameter: only links do.
Subdomains
Subdomains share nothing by default either. Two settings help:
| Need | Setting |
|---|---|
| Accept data from every subdomain | List the parent domain in Allowed domains (shop.com covers www.shop.com and blog.shop.com). |
| One returning visitor, identity and opt-out across subdomains | One visitor across subdomains of: shop.com. Stored in one first-party cookie (_sr_v) of that domain. |
A session still lives per tab and domain; use crossDomain for links between subdomains if one session matters.
Tabs
Each browser tab has its own session (it lives in sessionStorage). A new session starts after 30 minutes without activity or once a session is 24 hours old. The visitor id, identity and opt-out are shared by all tabs of the browser (in localStorage).
Shadow DOM, canvas and other content
- Shadow DOM: open shadow roots (web components) are recorded by the rrweb recorder like the rest of the page; closed shadow roots can't be read by any script and stay empty.
- Canvas: charts, maps and games drawn on
<canvas>are recorded only with Record canvas drawings on: about one image a second per changed canvas, at most 1280 px wide. - Fonts and stylesheets: replays load the page's stylesheets; with Keep copies of stylesheets (on by default) the server keeps copies so replays keep their look after the site changes its CSS.
- Light and dark: the visitor's colour scheme is recorded, so replays look the way the visitor saw the site.
