SDKsOfficial

Web SDK

Integrate Sankofa into your web applications with support for event tracking and identity resolution via NPM or CDN.

Source of truthhttps://github.com/Sankofa-HQ/sankofa_sdk_web

The Sankofa Web SDK is the core integration layer for browser-based applications. View source on GitHub. It provides a high-level API for tracking user behavior, capturing identity profile updates, and recording user sessions via session replay.

Integration Methods

You can integrate Sankofa using either the NPM package (recommended for modern frameworks) or via a direct Script tag (ideal for simple sites or CMS integrations).

1. Script Tag (CDN)

Copy and paste this snippet into the <head> or at the end of the <body> of your website. This method makes the Sankofa global object available immediately.

<script src="https://cdn.jsdelivr.net/npm/@sankofa/[email protected]/dist/sankofa.min.js"></script>
<script>
  Sankofa.init({
    apiKey: "your-api-key",
    endpoint: "https://api.sankofa.dev"
  });
</script>

2. NPM / Yarn

For projects using React, Vue, or other modern frameworks:

npm install @sankofa/browser

Initialize the SDK once in your application entry point:

import { Sankofa } from "@sankofa/browser";

await Sankofa.init({
  apiKey: "your-api-key",
  endpoint: "https://api.sankofa.dev",
});

Core Functionality

Tracking Events

Track user actions with custom properties to build your event analytics.

Sankofa.track("purchased_item", {
  item_id: "sku_123",
  price: 49.99,
  currency: "USD",
  category: "electronics"
});

Identity and People

Sankofa uses a dual-method approach to manage user identity: identify for internal IDs and setPerson for human-readable profile traits.

Identifying Users

Use identify when a user logs in to link their anonymous history to their persistent internal ID.

await Sankofa.identify("user_987");

Setting Profile Traits

Use setPerson to enrich user profiles with information that appears in the Sankofa dashboard.

await Sankofa.setPerson({
  name: "John Doe",
  email: "[email protected]",
  avatar: "https://example.com/avatars/john.jpg",
  // You can also add custom attributes
  plan: "premium",
  signup_date: "2024-03-17"
});

Default Properties

The Web SDK automatically collects the following properties with every event:

$current_url: The full URL of the page.
$host: The domain name.
$pathname: The URL path.
$referrer: The referring URL.
$browser: Browser name (e.g., Chrome, Firefox).
$os: Operating system.
$screen_height / $screen_width: Device resolution.

Advanced Configuration

Option	Type	Default	Description
`apiKey`	`string`	Required	Your project API key.
`endpoint`	`string`	Required	Your Sankofa engine URL (e.g., `https://api.sankofa.dev`).
`debug`	`boolean`	`false`	Enable console logging.
`flushIntervalMs`	`number`	`5000`	How often to batch and send events.
`autocapture`	`boolean`	`true`	Automatically track pageviews.

🎥 Session Replay

Web Session Replay uses the industry-standard rrweb engine to capture DOM changes and user interactions.

1. Register the Plugin

Add the rrwebReplayPlugin to your initialization options.

import { Sankofa } from '@sankofa/browser';
import { rrwebReplayPlugin } from '@sankofa/replay-rrweb';

Sankofa.init({
  apiKey: 'YOUR_PROJECT_API_KEY',
  endpoint: 'https://api.sankofa.dev',
  plugins: [
    rrwebReplayPlugin({
      flushIntervalMs: 5000,
      maxEventsPerChunk: 250,
    })
  ]
});

2. Privacy & Masking

By default, the plugin enables maskAllInputs, which replaces all text entered into input fields with asterisks. You can fine-tune privacy using specific CSS selectors.

Option	Description
`blockSelector`	Elements matching this selector will be completely removed from the recording.
`maskSelector`	Text content inside these elements will be replaced with generic characters.
`ignoreSelector`	Prevents recording events (like clicks) on these elements.

🛠 Advanced Configuration

Option	Type	Default	Description
`apiKey`	`string`	Required	Your project API key.
`endpoint`	`string`	Required	Your Sankofa engine URL.
`debug`	`boolean`	`false`	Enable console logging.
`flushIntervalMs`	`number`	`5000`	How often to batch and send events.
`autocapture`	`boolean`	`true`	Automatically track pageviews.

📑 Next Steps

Flutter SDK

Official Flutter support for event tracking, identity, and offline queueing.

Integrations

Use direct HTTP ingestion when you need Sankofa in environments outside the official Flutter SDK.