@sessionlens/sdk 0.2.1 → 0.3.0

package/README.md

@@ -45,6 +45,28 @@ sessionLens.sessionLensIdentify({
 sessionLens.sessionLensReset();
 ```
 
+## Identity and anonymous tracking (0.3.0+)
+
+`user_id` is optional. Without it, events are tracked against a persistent anonymous device id
+(`localStorage._sl_device_id`). Link the device to a person when you know who they are:
+
+```javascript
+await sessionLens.sessionLensInit({ sdk_key: '...', org_id: '...' }); // no user_id needed
+
+sessionLens.sessionLensTrack({ event_name: 'pricing_viewed' });       // anonymous
+
+sessionLens.identify('user-123', { name: 'Ada Lovelace', email: 'ada@example.com', plan: 'pro' });
+sessionLens.setUserProperties({ company: 'Analytical Engines' });     // name/email map to core profile fields
+
+sessionLens.reset();                                                  // on logout: new anonymous identity
+```
+
+- Identifying again on the same device (a different user) links the device to the new user; past events keep their original attribution.
+- `alias(newId, oldId)` is deprecated and simply calls `identify(newId)`.
+- Passing `user_id` to `sessionLensInit` still works and behaves like an implicit `identify()`.
+- Each event is automatically enriched with `$device_id`, `$distinct_id`, `$insert_id`, `$library`, `$library_version`, `$current_url`, `$pathname`, `$referrer`, `$initial_referrer`, UTM parameters, screen size and client browser/OS hints. Browser, OS and geo (from the request IP) are derived on the server.
+- Trait limits: at most 100 keys, keys up to 128 characters, values up to 4 KB. Trait keys may not start with `$` or contain `.`; offending keys are dropped without failing the call.
+
 ### Advanced Usage with Custom Configuration
 
 ```javascript

package/dist/core/config.d.ts

@@ -1,14 +1,16 @@
 export interface SessionLensConfig {
     sdk_key: string;
-    user_id: string;
+    user_id?: string;
     org_id: string;
     project_id?: string;
+    app?: string;
     debug?: boolean;
     api_base_url?: string;
     endpoints?: {
         events?: string;
         identify?: string;
         reset?: string;
+        userProperties?: string;
         validate?: string;
     };
 }
@@ -17,10 +19,11 @@ interface SessionInfo {
     client_id: string;
     org_id: string;
     project_id: string;
-    user_id: string;
+    user_id?: string;
     started_at: number;
     last_activity: number;
 }
+export declare function restartSession(): void;
 export declare function sessionLensInit(config: SessionLensConfig): Promise<void>;
 export declare function sessionLensGetConfig(): SessionLensConfig;
 export declare function getSessionInfo(): SessionInfo;

package/dist/core/enrich.d.ts

@@ -0,0 +1,6 @@
+/**
+ * System properties attached to every event. All browser access is guarded so this
+ * is safe to call during SSR (only identity/library fields are returned there).
+ * The server re-derives browser/os/geo authoritatively; the client UA fields are a fallback.
+ */
+export declare function buildSystemProperties(clientTimestamp: number): Record<string, any>;

package/dist/core/identity.d.ts

@@ -0,0 +1,14 @@
+export interface Identity {
+    device_id: string;
+    distinct_id: string;
+    user_id?: string;
+}
+export declare function getDeviceId(): string;
+/** Current identity. Anonymous visitors have distinct_id === device_id and no user_id. */
+export declare function getIdentity(): Identity;
+/** Persist a user identity. From now on events carry distinct_id = userId. */
+export declare function setUser(userId: string): void;
+/** Forget the user and start a fresh anonymous identity on a new device id. */
+export declare function resetIdentity(): Identity;
+/** Referrer of the very first page load, persisted once ('$direct' when there was none). */
+export declare function getInitialReferrer(currentReferrer: string): string;

package/dist/core/tracker.d.ts

@@ -1,4 +1,19 @@
+import { SessionLensConfig } from './config';
 import { SessionLensEvent, SessionLensUser } from '../types';
+/**
+ * Initialize the SDK. If `config.user_id` is supplied (pre-0.3 integrations) it is treated
+ * as an implicit identify() - sent only when it differs from the persisted identity.
+ */
+export declare function sessionLensInit(config: SessionLensConfig): Promise<void>;
 export declare function sessionLensTrack(event: SessionLensEvent): void;
+/** Link the current device to `userId` (last identify wins) and optionally set traits. */
+export declare function identify(userId: string, traits?: Record<string, any>): void;
+/** @deprecated Aliasing is subsumed by identify(); `oldId` is ignored (the device link is implicit). */
+export declare function alias(newId: string, _oldId?: string): void;
+/** Set traits on the current profile (`name` and `email` map to core profile fields). */
+export declare function setUserProperties(traits: Record<string, any>): void;
+/** Legacy signature: sessionLensIdentify({ user_id, properties }). */
 export declare function sessionLensIdentify(user: SessionLensUser): void;
-export declare function sessionLensReset(): void;
+/** Forget the user, start an anonymous identity on a new device id and a new session. */
+export declare function reset(): void;
+export declare const sessionLensReset: typeof reset;

package/dist/index.d.ts

@@ -2,12 +2,18 @@ import { SessionLensConfig } from './core/config';
 import { SessionLensEvent, SessionLensUser, SessionLensInstance } from './types';
 export * from './types';
 export { SessionLensConfig } from './core/config';
+export { SDK_VERSION } from './version';
 export * from './integrations/react';
 declare class SessionLens implements SessionLensInstance {
     sessionLensInit(config: SessionLensConfig): Promise<void>;
     sessionLensTrack(event: SessionLensEvent): void;
     sessionLensIdentify(user: SessionLensUser): void;
     sessionLensReset(): void;
+    identify(userId: string, traits?: Record<string, any>): void;
+    /** @deprecated Use identify(). */
+    alias(newId: string, oldId?: string): void;
+    setUserProperties(traits: Record<string, any>): void;
+    reset(): void;
 }
 declare const sessionLens: SessionLens;
 export default sessionLens;