Browser SDK - RetainPixel Docs

Installation

Install via npm:

bash

npm install @retainpixel/sdk-browser

Or load via script tag:

html

<script src="https://cdn.retainpixel.com/v1/rp.min.js" data-write-key="rpx_live_YOUR_KEY_HERE"></script>

Configuration

javascript

import { RetainPixel } from '@retainpixel/sdk-browser';

const rp = RetainPixel.init({
  writeKey: 'rpx_live_YOUR_KEY_HERE',  // Required. Your API key
  consent: true,                        // Optional. Enable consent mode (default: true)
  autocapture: false,                   // Optional. Auto-capture clicks, forms, etc.
  debug: false,                         // Optional. Log events to console
});

Option	Type	Default	Description
writeKey	string	--	Required. Your API key from the dashboard.
consent	boolean	true	Whether tracking is initially consented.
autocapture	boolean	false	Auto-capture click, form, scroll, and visibility events.
debug	boolean	false	Log all events to the browser console.

Core Methods

rp.track(event, properties?)

Track a custom event with optional properties.

javascript

rp.track('feature_used', {
  feature: 'export',
  format: 'csv',
});

rp.identify(userId, traits?)

Identify a user and associate future events with their profile.

javascript

rp.identify('user-123', {
  email: 'user@example.com',
  plan: 'pro',
  created_at: '2026-01-15',
});

rp.group(groupId, traits?)

Associate the user with a group (team, company, etc.).

javascript

rp.group('company-456', {
  name: 'Acme Corp',
  plan: 'enterprise',
});

rp.page(name?, properties?)

Track a page view. Called automatically when autocapture is enabled.

javascript

rp.page('Pricing');

rp.revenue(amount, properties?)

Track a revenue event for conversion tracking.

javascript

rp.revenue(49.99, {
  currency: 'USD',
  plan: 'pro',
});

Consent Management

Control tracking consent at runtime. Events are buffered locally when consent is revoked and flushed when granted.

javascript

// Grant consent (events start flowing)
rp.setConsent(true);

// Revoke consent (events buffered locally)
rp.setConsent(false);

// Permanently opt out (clears local data)
rp.optOut();

Autocapture

When enabled, the SDK automatically captures click, form submission, scroll depth, and element visibility events. Use the data-rp-track attribute to tag specific elements:

html

<button data-rp-track="signup_cta">Sign Up</button>
<form data-rp-track="checkout_form">...</form>

Elements with data-rp-track are captured with their track name as the event name, making them easy to find in your analytics.

Session Management

Sessions rotate after 30 minutes of inactivity. The SDK generates a unique session ID and includes it with every event. Events are buffered in localStorage when offline and flushed when connectivity returns.

Transport

The SDK uses navigator.sendBeacon on page hide for reliable delivery during navigation, with a fetch fallback for normal event batching.