Skip to main content

​
Installation

npm install despia-native

pnpm add despia-native

yarn add despia-native

import despia from 'despia-native';

​
Capture an event

Fire any named event with optional properties. This is the core call. PostHog merges your properties with the device context it captures automatically , OS, app version, screen size, and more. Your keys take precedence on any conflict. 
const props = {
    plan: "pro",
    revenue: 29.99,
    currency: "USD"
}
despia(`posthog://capture?event=Checkout&properties=${encodeURIComponent(JSON.stringify(props))}`)
ParameterRequiredDescription
eventYesEvent name. Case-sensitive. Pass as-is, no encoding needed.
propertiesNoKey-value pairs attached to the event. Wrap with encodeURIComponent(JSON.stringify(...)). Values can be strings, numbers, booleans, or flat arrays. Nested objects are not supported.
Use a consistent naming convention. PastTense verbs work well, e.g. Signed Up, Checkout Completed, Article Read. Avoid PII in event properties , use person properties via identify instead.

​
Identify a user

Associates the current anonymous device ID with a known user. Call this as soon as a user logs in. All subsequent events link to this identity until reset is called. 
const person = {
    email: "user@example.com",
    name: "Jane Smith",
    plan: "pro",
    created_at: "2025-01-15"
}
despia(`posthog://identify?distinct_id=user_123&properties=${encodeURIComponent(JSON.stringify(person))}`)
ParameterRequiredDescription
distinct_idYesYour internal user ID. Pass as-is, no encoding needed.
propertiesNoPerson properties stored on the PostHog person record, not event properties. Wrap with encodeURIComponent(JSON.stringify(...)).
Person properties on the PostHog person record have separate retention and access controls from event properties. Never send raw PII as event properties , put it on the person record where you can manage it. After identify fires, despia.postHogDistinctId and despia.postHogSessionId update in place and reflect the new identity.

​
Merge a pre-signup ID

Merges two distinct IDs into the same person. Use this at signup when a user has generated anonymous events before logging in and you want the pre-signup history to merge into their identified profile. 
despia('posthog://alias?alias=user_123')
ParameterRequiredDescription
aliasYesThe new ID to merge into the current distinct_id. Pass as-is, no encoding needed.
Call once at signup, immediately before or after posthog://identify. Do not call repeatedly. PostHog merges the anonymous session history permanently.

​
Set group context

Links all subsequent events in the session to a group , an organization, team, workspace, or account. Must be called again if the user switches group context. 
const groupProps = {
    name: "Acme Corp",
    plan: "enterprise",
    employee_count: 500
}
despia(`posthog://group?type=company&key=acme_corp&properties=${encodeURIComponent(JSON.stringify(groupProps))}`)
ParameterRequiredDescription
typeYesGroup type key, e.g. company, team, workspace. Must match a group type defined in your PostHog project. Pass as-is.
keyYesUnique identifier for the specific group. Pass as-is.
propertiesNoGroup-level properties stored on the group record. Wrap with encodeURIComponent(JSON.stringify(...)).
PostHog has a hard limit of 5 group types per project. Group types are created automatically on first use. Coordinate type naming with your PostHog project owner before shipping , renaming a type later requires a backfill.

​
Track a screen view

Sends a $screen event to PostHog with $screen_name set to the provided value. Use this on every route change inside your app. 
const props = { source: "tab_bar" }
despia(`posthog://screen?name=Settings&properties=${encodeURIComponent(JSON.stringify(props))}`)
ParameterRequiredDescription
nameYesScreen or view name, e.g. Settings, Checkout, Profile. Pass as-is.
propertiesNoAdditional properties attached to the screen event. Wrap with encodeURIComponent(JSON.stringify(...)).

​
Set person properties

Sets or updates properties on the PostHog person record without capturing an event. Use this when a user updates their profile or when you receive new attributes from your backend. 
const props = { plan: "enterprise", seats: 10 }
despia(`posthog://set_person_properties?properties=${encodeURIComponent(JSON.stringify(props))}`)
ParameterRequiredDescription
propertiesYesProperties to set. Merges with existing person properties. Wrap with encodeURIComponent(JSON.stringify(...)).

​
Register super properties

Registers super properties , key-value pairs automatically appended to every subsequent capture call for the lifetime of the session. Useful for stable session-level context like locale or app_version. 
const superProps = { locale: navigator.language, app_version: "3.2.1" }
despia(`posthog://register?properties=${encodeURIComponent(JSON.stringify(superProps))}`)
ParameterRequiredDescription
propertiesYesProperties to register. Persisted across page loads until posthog://unregister or posthog://reset. Wrap with encodeURIComponent(JSON.stringify(...)).
Super properties merge with event-level properties. If the same key appears in both, the event-level value wins.

​
Remove a super property

Removes a single super property by key. The next captured event will no longer carry that key. 
despia('posthog://unregister?key=experiment_group')
ParameterRequiredDescription
keyYesThe super property key to remove. Pass as-is.

​
Reset on logout

Resets all user data and starts a fresh session. Clears the distinct_id, all person properties, all super properties, all group associations, and the session. Call this on logout only. 
despia('posthog://reset')
After reset fires, the native layer updates despia.postHogDistinctId, despia.postHogSessionId, and despia.postHogFlags in place. Reads of those globals immediately after the call reflect the refreshed values.

​
Opt out of tracking

Opts the user out of all PostHog tracking. No events are sent and no data is stored from this point forward. Persists across sessions until posthog://opt_in is called. 
despia('posthog://opt_out')
This is the GDPR consent cutoff. Under GDPR, analytics tracking requires explicit user consent before any data is collected. Call opt_out when the user declines your consent prompt. PostHog enforces the cutoff at the SDK level , events fired after opt_out are dropped before they reach PostHog servers. despia.postHogOptedOut updates to true when this fires.

​
Opt in to tracking

Opts the user in to PostHog tracking. Call this when the user explicitly accepts analytics in your consent prompt. 
despia('posthog://opt_in')
despia.postHogOptedOut updates to false when this fires.

​
Reading current state

The native layer keeps four globals live on the despia object. They update in place whenever their value changes, with no page reload required. Read them when you need the current value , do not snapshot them at boot, since the page-load push is asynchronous and may arrive after your startup code runs. 
despia.postHogDistinctId  // current PostHog distinct_id
despia.postHogSessionId   // current session ID
despia.postHogOptedOut    // true if the user has opted out
despia.postHogFlags       // all evaluated feature flag values, keyed by flag name
GlobalTypeDescription
postHogDistinctIdstringUpdates on page load, after identify, and after reset. Defaults to "" until the native layer populates it.
postHogSessionIdstringUpdates on page load, after identify, after reset, and once the first captured event opens a session. Defaults to "".
postHogOptedOutbooleanUpdates on page load and after opt_in / opt_out. Defaults to false.
postHogFlagsobjectUpdates on page load and whenever PostHog pushes new flag values. Defaults to {}. A flag not yet loaded is absent from the object , use "flag_name" in despia.postHogFlags to check.
Reading a feature flag is synchronous and always reflects the most recent push from PostHog. No scheme call is needed. 
const enabled = despia.postHogFlags["new_checkout"]      // boolean flag
const variant = despia.postHogFlags["checkout_variant"]  // multivariate, e.g. "control" or "test_v2"

​
Standard auth flow

Correct call order for a standard login and logout sequence. 
import despia from 'despia-native'

const isDespia = navigator.userAgent.toLowerCase().includes('despia')

// 1. On app load , register session-level super properties
if (isDespia) {
    const superProps = { locale: navigator.language, app_version: window.APP_VERSION }
    despia(`posthog://register?properties=${encodeURIComponent(JSON.stringify(superProps))}`)
}

// 2. On login , identify the user
if (isDespia) {
    const person = { email: user.email, plan: user.plan }
    despia(`posthog://identify?distinct_id=${user.id}&properties=${encodeURIComponent(JSON.stringify(person))}`)
}

// 3. For B2B apps , associate with org after identify
if (isDespia) {
    const groupProps = { name: user.orgName, plan: user.orgPlan }
    despia(`posthog://group?type=company&key=${user.orgId}&properties=${encodeURIComponent(JSON.stringify(groupProps))}`)
}

// 4. Track actions
if (isDespia) {
    const props = { plan: "pro", revenue: 29.99 }
    despia(`posthog://capture?event=Checkout&properties=${encodeURIComponent(JSON.stringify(props))}`)
}

// 5. On logout , reset everything
if (isDespia) {
    despia('posthog://reset')
}

​
Not bridged

CapabilityReason
getFeatureFlag / isFeatureEnabledUse despia.postHogFlags , synchronous, always current, no scheme call needed
reloadFeatureFlags / onFeatureFlagsFlag values are cached natively and pushed into despia.postHogFlags automatically
Session recording controlsConfigured project-side in PostHog, not a per-user runtime concern
SurveysRun via PostHog’s own JS embed, not a native SDK surface

​
Resources

NPM Package

despia-native

PostHog Dashboard

Configure feature flags, funnels, and session recordings

PostHog Docs

Feature flags, person properties, and group analytics

Support

support@despia.com