SDKs

userGist supports React Native, native iOS, native Android, Flutter, and desktop/mobile websites. They share the same authenticated subject protocol, consent model, durable delivery rules, campaign evaluators, and dashboard contract while using platform-native APIs for lifecycle and push integration.

Pick a platform

How the correct SDK is selected

userGist does not inspect your application and download an SDK automatically. You choose one or more platforms when creating an app in the dashboard. The SDK setup page then shows the matching install, initialization, identity, and event snippets for those platforms. Your package manager downloads the package you selected from its public registry.

At runtime, the responsibilities stay separate:

1. The installed package determines which platform implementation runs.
2. The write key tells api.usergist.com which userGist app and environment owns the request.
3. The SDK sends its platform, SDK version, and host-app version as request context for diagnostics and analytics.
4. The backend uses one shared protocol for identity, consent, events, campaigns, and responses; it never swaps one SDK implementation for another.

One userGist app or several?

Use one userGist app and write key across multiple platform builds when they represent the same product and environment and you want one combined audience, campaign set, and analytics view. For example, the iOS and Android versions of Acme Production can share one userGist app.

Create separate userGist apps when you need isolation:

• Production versus staging or development
• Separate products, legal entities, or data boundaries
• Independent campaigns, push credentials, write-key rotation, or analytics

Selecting platforms controls setup guidance and the platforms available for client registration. Campaign delivery platforms are selected separately in Target. The write key—not the platform selection—is what authenticates and routes runtime traffic to the correct userGist app.

What every SDK provides

• Identity — native SDKs support anonymous installation sessions. Web initialization is inactive until identification, or explicit allowAnonymous / startAnonymous() activation. Await web reset() before changing accounts.
• Events — track(name, props?) queues a behavioural event and flushes in batches.
• Consent — setConsent({ analytics, feedback, push, survey }) gates each subsystem.
• Surveys — getAvailableSurveys(), openSurvey(id), deep-link handling, save-resume.
• Feature requests — full board API: list, vote, follow, comment, submit, search.
• Push (native only) — register and rotate tokens, synchronize channels, and beacon delivery events; each platform guide documents its permission and host-forwarding APIs.
• Lifecycle hooks — onPromptShown, onResponse, onPushEvent.

See packages/PARITY.md for the full feature matrix and platform-specific push helpers.

Security & privacy defaults

The SDK family uses these defaults:

• Bounded platform storage for identity, queues and survey progress. React Native uses AsyncStorage; web uses IndexedDB with a memory fallback. These stores are not encrypted; do not send secrets or sensitive free-form data as event properties.
• Platform HTTPS trust for api.usergist.com. Application-level certificate pinning is not currently implemented in React Native.
• Schema versioning on disk — incompatible event snapshots are safely discarded and durable mutations remain explicitly versioned.
• PII allow-list enforced at ingest (email, phone, ssn, tax_id blocked by default — configurable per app).

A typical native integration

For websites, follow the Web SDK integration, including origin setup and explicit activation.

// 1. Init at app launch
UserGist.init({ writeKey: 'rk_live_...', environment: 'production' })
 
// 2. Identify after the user signs in
// Fetch from your own authenticated backend. That backend exchanges its
// rtk_ token at POST /v1/apps/:appId/sdk/subject-tokens.
const { subjectToken } = await yourBackend.getUserGistSubjectToken()
UserGist.identify(user.id, { plan: user.plan, signedUpAt: user.createdAt }, subjectToken)
 
// 3. Track behaviour
UserGist.track('checkout_completed', { amountUsd: 49 })
 
// 4. (Optional) Show a survey on a key moment
const surveys = await UserGist.getAvailableSurveys()
if (surveys[0]) UserGist.openSurvey(surveys[0].id)
 
// 5. (Optional) Enable push
await UserGist.enablePush({ environment: 'production' })
 
// 6. On logout
UserGist.reset()

Push permission and token acquisition remain platform-native; each platform guide shows the required APNs or FCM forwarding code.