{"_id":"@bship-analytics/analytics-sdk","name":"@bship-analytics/analytics-sdk","dist-tags":{"latest":"1.0.11"},"versions":{"1.0.11":{"name":"@bship-analytics/analytics-sdk","version":"1.0.11","description":"Analytics Platform JS SDK — track events from client apps","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","dev":"tsc --watch"},"devDependencies":{"ts-node":"^10.9.2","tsx":"^4.21.0","typescript":"^5.4.0"},"license":"MIT","gitHead":"68efbc97abe54f14f950a53302f927730b16ee43","_id":"@bship-analytics/analytics-sdk@1.0.11","_nodeVersion":"25.8.2","_npmVersion":"11.11.1","dist":{"integrity":"sha512-njx2LxWKGO4ISKjOM2F+BGH78iZyUUc9qRaKUj6zf4YLjX6FDUhM2F2NCwO+PAhw/YYBEmFeMPKsMklPfXeRdQ==","shasum":"88d894e5c36345411f7959b2d050f326f35919a2","tarball":"https://registry.npmjs.org/@bship-analytics/analytics-sdk/-/analytics-sdk-1.0.11.tgz","fileCount":8,"unpackedSize":17996,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCHVa2aLhOWfy9YqvTjolLjhoXluFjVeXTE0aajyDttAQIgaJFevUftWR+81iML3jIx63MNeNhM6hUtRKeoIbsC2Xk="}]},"_npmUser":{"name":"megabeehothanhminh","email":"megabee.hothanhminh@gmail.com"},"directories":{},"maintainers":[{"name":"megabeehothanhminh","email":"megabee.hothanhminh@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/analytics-sdk_1.0.11_1778841499990_0.5827266461304172"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-15T10:38:19.869Z","1.0.11":"2026-05-15T10:38:20.186Z","modified":"2026-05-15T10:38:20.560Z"},"maintainers":[{"name":"megabeehothanhminh","email":"megabee.hothanhminh@gmail.com"}],"description":"Analytics Platform JS SDK — track events from client apps","license":"MIT","readme":"# Analytics SDK (JS/TS + Go)\n\nSDK gửi sự kiện analytics theo kiểu **non-blocking + best-effort**.\nMục tiêu: nếu analytics server chậm/chết thì **không làm ảnh hưởng luồng chính của app client**.\n\n## JS/TS SDK\n\n### Cài đặt\n\n```bash\nnpm install @bship/analytics-sdk\n```\n\n### Khởi tạo\n\n```ts\nimport { AnalyticsClient } from '@bship/analytics-sdk'\n\nconst analytics = new AnalyticsClient('sk_live_...', {\n  endpoint: 'https://api.yourdomain.com',\n  requestTimeoutMs: 1200,\n  appPlatform: 'ios',\n  channel: 'app',\n  deviceId: 'device-uuid',\n  autoSession: true,\n  sessionIdleTimeoutMs: 30 * 60 * 1000,\n  sessionMaxDurationMs: 4 * 60 * 60 * 1000,\n  onError: (err) => {\n    // optional: log Sentry / console\n    console.warn('analytics send failed', err)\n  },\n})\n```\n\n### Identify / Capture / Batch\n\n```ts\nanalytics.identify({\n  userId: 'user-123',\n  anonymousId: 'device-uuid',\n  userProperties: { email: 'test@example.com' },\n})\n\nanalytics.capture({\n  event: 'trip_completed',\n  appPlatform: 'ios',\n  channel: 'app',\n  deviceId: 'device-uuid',\n  properties: { final_price: 52000 },\n})\n\nanalytics.batch([\n  { distinct_id: 'user-123', event: 'app_opened', app_platform: 'ios', channel: 'app', device_id: 'device-uuid' },\n  { distinct_id: 'user-123', event: 'button_clicked', properties: { button_id: 'confirm' } },\n])\n```\n\nLưu ý:\n- `identify/capture/batch` dispatch request nền (fire-and-forget), không chờ server trả về.\n- Nếu đã set `deviceId` mà chưa `identify`, `capture` sẽ tự fallback `distinct_id = deviceId`.\n- SDK tự gắn `$app_platform` và `$channel` vào `properties` cho mỗi event.\n- SDK tự gắn `$device_id` vào `properties` nếu có truyền `deviceId`.\n- SDK tự tạo và gắn `properties.session_id` (không cần app tự tạo).\n- Session tự rotate khi idle quá lâu hoặc quá tuổi thọ session.\n- SDK cũng gửi top-level `app_platform` và `channel` để backend ingest map vào cột nhanh hơn.\n- SDK cũng gửi top-level `device_id` khi có.\n- Không hard-code whitelist trong SDK: client truyền giá trị nào thì SDK giữ nguyên giá trị đó.\n- Lỗi request chỉ đi qua callback `onError` (nếu bạn truyền vào).\n\n## Go SDK\n\n### Cài đặt\n\n```bash\ngo get gitlab.com/bship1/datawarehouse/analytics-sdk/go\n```\n\n### Khởi tạo\n\n```go\nclient := analytics.NewClient(os.Getenv(\"ANALYTICS_API_KEY\"), analytics.Options{\n    Endpoint:       \"https://api.yourdomain.com\",\n    RequestTimeout: 1200 * time.Millisecond,\n    AppPlatform:    \"android\",\n    Channel:        \"mini_app_zalo\",\n    DeviceID:       \"device-uuid\",\n    OnError: func(err error) {\n        log.Printf(\"analytics send failed: %v\", err)\n    },\n})\n```\n\n### Identify / Capture / Batch\n\n```go\nclient.Identify(context.Background(), analytics.Identify{\n    DistinctID:  \"user-123\",\n    AnonymousID: \"device-123\",\n    Properties: analytics.NewProperties().\n        Set(\"email\", \"test@example.com\"),\n})\n\nclient.Capture(context.Background(), analytics.Capture{\n    DistinctID:  \"user-123\",\n    Event:       \"button_clicked\",\n    AppPlatform: \"android\",\n    Channel:     \"mini_app_zalo\",\n    DeviceID:    \"device-uuid\",\n    Properties: analytics.NewProperties().\n        Set(\"name\", \"login\").\n        Set(\"type\", \"otp\"),\n})\n\nclient.Batch(context.Background(), []analytics.Capture{\n    {DistinctID: \"user-123\", Event: \"app_opened\", AppPlatform: \"android\", Channel: \"mini_app_zalo\"},\n})\n```\n\nLưu ý:\n- `Identify/Capture/Batch` chạy nền bằng goroutine, trả về ngay.\n- SDK tự gắn `$app_platform` và `$channel` vào `properties` cho mỗi event.\n- SDK tự gắn `$device_id` vào `properties` nếu có truyền `DeviceID`.\n- SDK cũng gửi top-level `app_platform` và `channel`.\n- SDK cũng gửi top-level `device_id` khi có.\n- Không hard-code whitelist trong SDK: client truyền giá trị nào thì SDK giữ nguyên giá trị đó.\n- Nếu server chết/chậm, app vẫn tiếp tục chạy bình thường.\n- Lỗi gửi request được report qua `OnError`.\n","readmeFilename":"README.md","_rev":"1-085a47d38726f5bef0644ddd8dc667e4"}