SDKsWeb
API reference
Methods, options, and types for the MotiSig web SDK.
All methods are available on window.motisig (script tag). Async methods return promises; mutating calls are queued so they run in order.
Methods
| Method | Description |
|---|---|
initialize(options) | Configure SDK key, project id, base URL, anonymous options. Returns Promise<boolean> (false if key or project id is empty) |
identify(userId, extras?) | Register and switch to a known user id (POST /users; 409 treated as success) |
event(eventName, data?) | Send an event (POST /events); works anonymously before identify |
updateUser(payload) | Update profile fields (PATCH /users/{id}) |
addTags(tags) | Add tags |
removeTags(tags) | Remove tags |
addOrUpdateAttributes(attrs) | Add or update custom attributes |
removeAttributes(keys) | Remove attributes by key |
getUser() | Fetch the current user from the API, or null |
enableActivityTracking(options?) | Start session/foreground activity batching |
getAnonymousId() | Current anonymous visitor id, or null |
getAnonymousIdProvider() | fingerprintjs or internal |
currentUserId() | Active identified user id, or null |
logout() | Sign out — clear the identified user, keep the anonymous visitor id |
reset() | Full local wipe (user + anonymous + activity); not for auth sign-out |
subscribePush() | Request permission, register service worker, and subscribe (requires push.enabled). Returns Promise<{ ok: boolean; reason?: 'unsupported' | 'denied' | 'no_user' | 'not_enabled' }> |
unsubscribePush() | Unsubscribe and remove token from MotiSig |
setPushEnabled(enabled) | Toggle delivery on/off without unsubscribing |
getPushPermission() | Returns current browser notification permission: 'default' | 'granted' | 'denied' |
MotiSigWebOptions
interface MotiSigWebOptions {
sdkKey: string;
projectId: string;
baseURL?: string; // defaults to https://api.motisig.ai/client
anonymous?: AnonymousOptions;
logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent'; // default 'info'
anonymousUserExtras?: Omit<RegisterUserPayload, 'id' | 'platform' | 'anonymousId' | 'anonymousIdProvider'>;
push?: PushOptions;
}PushOptions
interface PushOptions {
enabled?: boolean; // default false — opt-in; SDK ignores push unless true
autoSubscribe?: boolean; // default false; if true and permission already granted, subscribe on init
serviceWorkerPath?: string; // default '/motisig-sw.js'
serviceWorkerScope?: string; // default '/'
vapidPublicKey?: string; // optional override; otherwise fetched from /web-config
}AnonymousOptions
interface AnonymousOptions {
enabled?: boolean; // default true
optOut?: boolean; // default true; false = enable FingerprintJS CDN
fingerprintCdnUrl?: string;
getVisitorId?: () => Promise<string> | string;
geolocation?: boolean; // default false
}RegisterUserPayload (identify extras)
interface RegisterUserPayload {
id: string;
platform?: 'web';
timezone?: string;
locale?: string;
firstName?: string;
lastName?: string;
email?: string;
phone?: string;
tags?: string[];
customAttributes?: Record<string, unknown>;
anonymousId?: string;
anonymousIdProvider?: 'fingerprintjs' | 'internal';
context?: ClientContextInput;
}UpdateUserPayload
interface UpdateUserPayload {
firstName?: string;
lastName?: string;
email?: string;
timezone?: string;
locale?: string;
}ActivityTrackingOptions
interface ActivityTrackingOptions {
appOpens?: boolean; // default true
flushIntervalMs?: number; // default 30000
pushReceived?: boolean;
pushDismissed?: boolean;
screenViews?: boolean;
}