Quickstart · Sankofa Docs

This guide walks you through sending your first event from any official Sankofa SDK, identifying a user, and verifying the path end-to-end. You'll need a project API key — get one from the dashboard under Project → API keys.

1. Install the SDK

bash

npm install @sankofa/browser
# or
pnpm add @sankofa/browser

YAMLpubspec.yaml

dependencies:
sankofa_flutter: ^1.0.0

bash

npm install @sankofa/react-native
# Expo Config Plugin auto-applies on prebuild

SwiftPackage.swift

.package(url: "https://github.com/sankofa-hq/sankofa-ios.git", from: "1.0.0")

Kotlinbuild.gradle.kts

dependencies {
  implementation("dev.sankofa:sankofa-android:1.0.0")
}

bash

npm install @sankofa/node

bash

go get github.com/sankofa-hq/sankofa_sdk_go

bash

pip install sankofa-catch

2. Initialize with your API key

Use a live key for production builds and a test key for local development. The engine resolves the environment from the key on every request, so the same code path works for both.

TypeScriptsrc/sankofa.ts

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

await Sankofa.init({
apiKey: process.env.NEXT_PUBLIC_SANKOFA_KEY!,
endpoint: "https://api.sankofa.dev",
});

Dartlib/main.dart

void main() async {
WidgetsFlutterBinding.ensureInitialized();
await Sankofa.instance.init(
  apiKey: 'sk_live_...',
  endpoint: 'https://api.sankofa.dev',
);
runApp(const MyApp());
}

TSXApp.tsx

import { Sankofa } from "@sankofa/react-native";

Sankofa.init({
apiKey: "sk_live_...",
endpoint: "https://api.sankofa.dev",
});

SwiftAppDelegate.swift

import Sankofa

Sankofa.shared.initialize(
  apiKey: "sk_live_...",
  config: SankofaConfig(recordSessions: true)
)

KotlinMyApp.kt

Sankofa.init(
  context = this,
  apiKey = "sk_live_...",
  config = SankofaConfig(recordSessions = true)
)

TypeScriptserver.ts

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

Sankofa.init({
apiKey: process.env.SANKOFA_KEY!,
endpoint: "https://api.sankofa.dev",
});

Gomain.go

import "github.com/sankofa-hq/sankofa_sdk_go/sankofa"

client, err := sankofa.New(sankofa.Config{
  APIKey:   os.Getenv("SANKOFA_KEY"),
  Endpoint: "https://api.sankofa.dev",
})
if err != nil { log.Fatal(err) }

Pythonapp.py

import sankofa

sankofa.init(
  api_key=os.environ["SANKOFA_KEY"],
  endpoint="https://api.sankofa.dev",
)

3. Track an event

TypeScript

Sankofa.track("checkout_started", {
cart_value: 49.99,
item_count: 3,
currency: "USD",
});

Dart

await Sankofa.instance.track('checkout_started', {
'cart_value': 49.99,
'item_count': 3,
'currency': 'USD',
});

TSX

Sankofa.track("checkout_started", {
cart_value: 49.99,
item_count: 3,
currency: "USD",
});

Swift

Sankofa.shared.track("checkout_started", properties: [
  "cart_value": 49.99,
  "item_count": 3,
  "currency": "USD"
])

Kotlin

Sankofa.track("checkout_started", mapOf(
  "cart_value" to 49.99,
  "item_count" to 3,
  "currency" to "USD"
))

TypeScript

Sankofa.track("checkout_started", {
cart_value: 49.99,
item_count: 3,
currency: "USD",
}, { distinctId: "user_123" });

client.Track(ctx, sankofa.Event{
  Name:       "checkout_started",
  DistinctID: "user_123",
  Properties: map[string]any{
      "cart_value":  49.99,
      "item_count":  3,
      "currency":    "USD",
  },
})

Python

sankofa.track("checkout_started", {
  "cart_value": 49.99,
  "item_count": 3,
  "currency": "USD",
}, distinct_id="user_123")

4. Identify the user

When the user signs in (or you discover their identity), call identify. Sankofa stitches the pre-identify anonymous traffic onto the resolved user automatically.

TypeScript

await Sankofa.identify("user_123", {
email: "ada@example.com",
plan: "pro",
});

Dart

await Sankofa.instance.identify('user_123', traits: {
'email': 'ada@example.com',
'plan': 'pro',
});

TSX

Sankofa.identify("user_123", {
email: "ada@example.com",
plan: "pro",
});

Swift

Sankofa.shared.identify(userId: "user_123", traits: [
  "email": "ada@example.com",
  "plan": "pro"
])

Kotlin

Sankofa.identify("user_123", mapOf(
  "email" to "ada@example.com",
  "plan" to "pro"
))

TypeScript

Sankofa.identify("user_123", {
email: "ada@example.com",
plan: "pro",
});

client.Identify(ctx, sankofa.Person{
  DistinctID: "user_123",
  Traits:     map[string]any{"email": "ada@example.com", "plan": "pro"},
})

Python

sankofa.identify("user_123", traits={
  "email": "ada@example.com",
  "plan": "pro",
})

5. Verify the path

Check the dashboard
Open app.sankofa.dev → your project → Live events. Your checkout_started event should appear within a few seconds.
Confirm the environment
The event card shows whether it was ingested as live or test. If it landed on the wrong side, you used the wrong API key — see Environments and API keys.
Validate identity stitching
After your identify call, the same event should appear on the People view, attributed to user_123. Anonymous events from before identify get re-attributed automatically.

What to read next

Concepts

Events deep dive

Naming conventions, default properties, and how events flow through the engine.

Hands-on

Your first feature flag

Roll out a feature to a cohort, gate behind A/B variants, and halt on a Catch signal.

API reference

Direct HTTP ingestion

Skip the SDK and POST events to /api/v1/track from any environment.