@livx.cc/native-kit 0.16.1 → 0.17.0

package/README.md

@@ -13,6 +13,17 @@ await kit.haptics.impact('medium');     // native vibration in the shell, no-op/
 const photo = await kit.photos.pick();  // native picker on device, <input type=file> on web
 ```
 
+### Analytics context
+
+`kit.context()` returns one flat, vendor-neutral property bag (client taxonomy, app version/build, install source, device, push permission, …) — spread it straight into your analytics super-properties. Native-only fields degrade gracefully on web. First-party & non-tracking: the install id is iOS IDFV / an Android UUID, never IDFA/GAID.
+
+```ts
+import { kit } from '@livx.cc/native-kit';
+mixpanel.register(await kit.context());
+// → { client: 'native-ios', platform: 'ios', app_version: '1.0.3',
+//     install_source: 'testflight', device_model: 'iPhone15,3', push_permission: 'granted', … }
+```
+
 The kit detects whether it's running inside the appwrap shell and routes each call to the native bridge or a web fallback, so a single web build works everywhere. Capabilities advertise their real backing (`native` / `web` / `none`) so your UI can be honest about what's available.
 
 Covers haptics, share, storage, notifications, OAuth, billing (IAP), health, geo, camera, photos, contacts, calendar, motion, reviews, and more.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/native-kit",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "Isomorphic native-capabilities kit for PWAs — same API in browser and in an appwrap native shell. Zero dependencies.",
   "license": "MIT",
   "author": "Elya Livshitz",

package/src/core/NativeKit.ts

@@ -33,6 +33,38 @@ export class NativeKitOptions {
   handshakeTimeoutMs = 3000;
 }
 
+/**
+ * Flat, vendor-neutral analytics bag — spread straight into your analytics provider's
+ * super-properties (e.g. `mixpanel.register(await kit.context())`). Native-only fields
+ * degrade gracefully (omitted/undefined) on web and on older shells. snake_case keys
+ * match common analytics conventions.
+ */
+export interface KitContext {
+  /** Coarse runtime taxonomy: 'native-ios' | 'native-android' | 'web'. */
+  client: string;
+  is_native: boolean;
+  platform: Platform;
+  app_id?: string;
+  app_name?: string;
+  app_version?: string;
+  app_build?: string;
+  /** App Store / TestFlight / sideload / simulator / web. */
+  install_source?: string;
+  /** Stable per-install id (iOS IDFV / Android UUID) — first-party, non-tracking. */
+  install_id?: string;
+  first_install_at?: number;
+  last_update_at?: number;
+  is_emulator?: boolean;
+  device_model?: string;
+  device_os?: string;
+  device_os_version?: string;
+  device_manufacturer?: string;
+  device_language?: string;
+  device_region?: string;
+  push_permission?: string;
+  network_type?: string;
+}
+
 export class NativeKit {
   public readonly haptics = new HapticsModule(this);
   public readonly share = new ShareModule(this);
@@ -64,6 +96,7 @@ export class NativeKit {
   public options: NativeKitOptions;
   private adapter: NativeKitAdapter | null = null;
   private readyPromise: Promise<Handshake> | null = null;
+  private contextPromise: Promise<KitContext> | null = null;
 
   constructor(options?: Partial<NativeKitOptions>) {
     this.options = { ...new NativeKitOptions(), ...options };
@@ -94,6 +127,57 @@ export class NativeKit {
     return this.readyPromise;
   }
 
+  /**
+   * One flat analytics bag (handshake + device + install env + push perm + network),
+   * ready to spread into super-properties. Resilient: each native probe degrades to
+   * omitted on failure, so this never rejects once {@link ready} resolves. Cached.
+   */
+  context(): Promise<KitContext> {
+    if (!this.contextPromise) {
+      this.contextPromise = (async () => {
+        await this.ready();
+        const hs = this.handshakeInfo!;
+        const client = this.is.native ? `native-${hs.platform}` : 'web';
+        const ctx: KitContext = {
+          client,
+          is_native: this.is.native,
+          platform: hs.platform,
+          app_id: hs.app?.id,
+          app_name: hs.app?.name,
+          app_version: hs.app?.version,
+          app_build: hs.app?.build,
+        };
+        // Probe in parallel; a failing/absent capability simply leaves its fields unset.
+        const safe = <T>(p: Promise<T>): Promise<T | null> => p.catch(() => null);
+        const [env, device, push, net] = await Promise.all([
+          safe(this.app.environment()),
+          safe(this.device.info()),
+          this.push.capability === 'native' ? safe(this.push.permissionStatus()) : Promise.resolve(null),
+          safe(this.network.status()),
+        ]);
+        if (env) {
+          ctx.install_source = env.source;
+          ctx.install_id = env.installId;
+          ctx.first_install_at = env.firstInstallAt;
+          ctx.last_update_at = env.lastUpdateAt;
+          ctx.is_emulator = env.isEmulator;
+        }
+        if (device) {
+          ctx.device_model = device.model;
+          ctx.device_os = device.os;
+          ctx.device_os_version = device.osVersion;
+          ctx.device_manufacturer = device.manufacturer;
+          ctx.device_language = device.language;
+          ctx.device_region = device.region;
+        }
+        if (push) ctx.push_permission = push;
+        if (net) ctx.network_type = net.type;
+        return ctx;
+      })();
+    }
+    return this.contextPromise;
+  }
+
   get is() {
     return { native: this.adapter?.kind === 'appwrap', web: this.adapter?.kind === 'web' };
   }

package/src/core/web-adapter.ts

@@ -322,6 +322,17 @@ export class WebAdapter implements NativeKitAdapter {
       case 'app.openSettings':
         throw new KitError('UNSUPPORTED', 'No app settings page on web');
 
+      case 'app.environment':
+        // On web there's no install — report the honest 'web' source. is_emulator is native-only.
+        return { source: 'web', isEmulator: false } as T;
+
+      case 'push.permissionStatus': {
+        // Best-effort via the Notification API (web push ≠ native push, but the perm signal is useful).
+        if (!('Notification' in window)) return 'notDetermined' as T;
+        const perm = Notification.permission; // 'granted' | 'denied' | 'default'
+        return (perm === 'default' ? 'notDetermined' : perm) as T;
+      }
+
       case 'billing.products':
       case 'billing.purchase':
       case 'billing.restore':

package/src/index.ts

@@ -1,4 +1,6 @@
 export { NativeKit, NativeKitOptions, kit } from './core/NativeKit';
+export type { KitContext } from './core/NativeKit';
+export type { AppEnvironment, InstallSource } from './modules/app';
 export { AppwrapAdapter } from './core/appwrap-adapter';
 export { WebAdapter } from './core/web-adapter';
 export { KitError } from './core/types';

package/src/modules/app.ts

@@ -1,5 +1,28 @@
 import type { NativeKit } from '../core/NativeKit';
 
+/** Where this build was installed from. Drives beta-vs-prod analytics cohorts.
+ *  - `appstore` / `playstore` — public store install
+ *  - `testflight` — iOS beta
+ *  - `sideload` — direct install (dev build, ad-hoc, APK), or unknown installer
+ *  - `simulator` — running on a simulator/emulator
+ *  - `web` — not running inside the native shell */
+export type InstallSource = 'appstore' | 'playstore' | 'testflight' | 'sideload' | 'simulator' | 'web';
+
+/** Install-level environment facts the page can't derive itself. First-party,
+ *  non-tracking (no IDFA/GAID): `installId` is iOS IDFV / an Android UUID kept in
+ *  app storage — app-scoped and reset on uninstall. */
+export interface AppEnvironment {
+  source: InstallSource;
+  /** Stable per-install id (iOS identifierForVendor / Android random UUID). */
+  installId?: string;
+  /** First install epoch-ms (Android only; omitted on iOS — no clean API). */
+  firstInstallAt?: number;
+  /** Last update epoch-ms (Android only). */
+  lastUpdateAt?: number;
+  /** Running on a simulator/emulator. */
+  isEmulator: boolean;
+}
+
 /** System-level app actions: hand a URL to the OS, or open this app's settings page. */
 export class AppModule {
   constructor(private kit: NativeKit) {}
@@ -8,6 +31,11 @@ export class AppModule {
     return this.kit.capability('app');
   }
 
+  /** Install-level environment facts for analytics/identification (source, install id, timestamps). */
+  environment(): Promise<AppEnvironment> {
+    return this.kit.invoke('app.environment');
+  }
+
   /** Open a URL in the OS default handler (external browser, mail:, tel:, maps:, …). */
   openUrl(url: string): Promise<void> {
     return this.kit.invoke('app.openUrl', { url });

package/src/modules/push.ts

@@ -49,6 +49,12 @@ export class PushModule {
     return this.kit.invoke('push.requestPermission', undefined, { timeoutMs: 60_000 });
   }
 
+  /** Current authorization WITHOUT prompting — for opt-in funnel analytics.
+   * 'notDetermined' means the user hasn't been asked yet. */
+  permissionStatus(): Promise<'granted' | 'denied' | 'notDetermined'> {
+    return this.kit.invoke('push.permissionStatus');
+  }
+
   /** Register with APNs/FCM and resolve the device token. Call after permission is granted. */
   register(): Promise<PushToken> {
     return this.kit.invoke('push.register', undefined, { timeoutMs: 30_000 });