tracking-lib-ott 1.0.13 → 1.0.14

package/README.md

@@ -1,8 +1,6 @@
 # Tracking Library OTT
 
-Thư viện tracking events dành cho các dự án OTT (Web, iOS, Android).
-npm version patch
-npm publish
+Thư viện tracking events dành cho các dự án OTT (Web, Smart TV).
 
 ## Cài đặt
 
@@ -12,6 +10,21 @@ npm install tracking-lib-ott
 yarn add tracking-lib-ott
 ```
 
+---
+
+## API Endpoint
+
+| Property     | Value                             |
+| ------------ | --------------------------------- |
+| Method       | `POST`                            |
+| URL          | `/v2/event_batch`                 |
+| Content-Type | `application/json`                |
+| Giới hạn     | Tối đa **200 events** mỗi request |
+
+> **Cơ chế**: Thông tin chung đặt ở cấp top-level, phần sự kiện nằm trong mảng `events`. Server sẽ hợp nhất thông tin chung vào từng event trước khi gửi vào Kafka.
+
+---
+
 ## Sử dụng cơ bản
 
 ### 1. Khởi tạo (Init)
@@ -20,442 +33,321 @@ yarn add tracking-lib-ott
 import tracking from "tracking-lib-ott";
 
 tracking.init({
-  baseURL: "https://api.example.com/v1/event_batch",
-  debug: true, // Bật log để debug
+  baseURL: "https://api.example.com/v2/event_batch",
+  debug: true,
 
-  // Thông tin bắt buộc
-  session_id, // Sẽ được tự sinh ra khi init session tracking và  K cần thêm vì đã trong thư viện đã tự động làm việc đó
-  session_sign: "session-signature", // Mỗi SDK client init bằng một key sign cho message. Sử dụng phương thức sign như sau:MD5(append(session_id,secret_key)) secret_key: Server cùng cấp để init SDK
-  user_id: 12345,
+  // Required fields
+  appId: "ONPlus", // ONPlus, ONLiveTV
+  packageId: "com.vtvcab.onsportstv",
+  sessionId: "uuid-v4-session-id", // Hoặc để trống sẽ tự động tạo từ cookie
+  sessionSign: "md5_signature", // MD5(append(session_id, secret_key))
   deviceId: "device-unique-id",
-  deviceModel: "iPhone 14",
-  deviceBrand: "Apple",
-  ip_address: "192.168.1.1",
-
-  // Thông tin tuỳ chọn
-  appName: "app_name",
-  appId: "app-id",
-  packageId: "Là package hoặc bundle id nếu website là domain website",
-  platform: "Web", // 'Web' | 'Ios' | 'Android'
-  os_version: "17.0",
-  app_version: "1.0.0",
-  language: "vi",
-  country: "VN",
-  net_type: "Loại mạng mà khác hàng đang kết nối",
+  platform: "SmartTV", // WebPC | WebMobile | SmartTV | AndroidTV
+  deviceModel: "Samsung TV 2024",
+  deviceBrand: "Samsung",
+  events: [],
+
+  // Optional fields
+  adId: "gaid-or-idfa",
+  deviceOsVersion: "17.0",
+  sdkVersion: "1.0.0",
 });
 ```
 
-### 2. Track Page View
+### 2. Set User Info
+
+```javascript
+// Khi user đăng nhập -> set userId
+// userId sẽ tự động được thêm vào mỗi event
+tracking.setUserInfo({ userId: 12345 });
+
+// Khi user đăng xuất
+tracking.setUserInfo({ userId: -1 });
+```
+
+### 3. Track Page View
 
 ```javascript
-// Track khi user vào một trang
 tracking.trackPageView("/home");
 tracking.trackPageView("/detail/123");
 tracking.trackPageView("/live/channel-1");
 ```
 
-### 3. Track Custom Event
+### 4. Track Custom Event
 
 ```javascript
-// Track event tuỳ ý với params
 tracking.trackEvent("button_click", {
   button_id: "subscribe_btn",
   page_id: "detail",
 });
 
-tracking.trackEvent("video_play", {
-  video_id: "12345",
-  video_title: "Trận đấu hay nhất",
-  duration: 3600,
-});
-
 tracking.trackEvent("search", {
   keyword: "bóng đá",
   results_count: 25,
 });
 ```
 
-### 4. Send Event trực tiếp
-
-```javascript
-// Gửi event với full control payload
-await tracking.sendEvent({
-  event_name: "custom_event",
-  custom_field_1: "value1",
-  custom_field_2: "value2",
-});
-```
-
 ---
 
-## Tích hợp Next.js (Pages Router)
+## Video Playback Events
 
-### Trong `_app.js` hoặc `_app.tsx`
+Thư viện hỗ trợ các events cho video player:
 
-```javascript
-import { useEffect } from "react";
-import { useRouter } from "next/router";
-import tracking from "tracking-lib-ott";
-
-function MyApp({ Component, pageProps }) {
-  const router = useRouter();
+### Flow tracking video
 
-  useEffect(() => {
-    // Khởi tạo tracking
-    tracking.init({
-      baseURL: process.env.NEXT_PUBLIC_TRACKING_URL,
-      session_id: "session-id-from-somewhere",
-      session_sign: "session-sign",
-      user_id: 12345,
-      deviceId: "device-id",
-      deviceModel: navigator.userAgent,
-      deviceBrand: "Web Browser",
-      ip_address: "", // Lấy từ API hoặc để trống
-      debug: process.env.NODE_ENV === "development",
-    });
-
-    // Auto track page views
-    const cleanup = tracking.usePageViewTracking(router);
-
-    return cleanup;
-  }, [router]);
-
-  return <Component {...pageProps} />;
-}
-
-export default MyApp;
+```
+view_content_details → playback_started → playback_progress (định kỳ) → playback_completed
+                                       ↘ playback_paused ↔ playback_resumed
+                                       ↘ buffer_started → buffer_ended
+                                       ↘ quality_changed
+                                       ↘ playback_error
 ```
 
----
-
-## Session Lifecycle Tracking
-
-Thư viện hỗ trợ tự động track session của user:
-
-| Event              | Khi nào gọi               | Mô tả                          |
-| ------------------ | ------------------------- | ------------------------------ |
-| `session_start`    | User mở app               | Gọi 1 lần khi init             |
-| `session_progress` | Định kỳ (mặc định 5 phút) | Heartbeat khi user đang active |
-| `session_end`      | User đóng tab/browser/app | Tự động detect                 |
-
-### Cách sử dụng
+### 1. View Content Details
 
 ```javascript
-import { useEffect } from "react";
-import tracking from "tracking-lib-ott";
+import { trackViewContentDetails } from "tracking-lib-ott";
+
+trackViewContentDetails(
+  "content_123", // contentId
+  "Phim ABC", // contentTitle
+  0, // contentType: 0=VOD, 1=Event, 2=Channel
+  "channel_vtv1", // channelId (optional)
+  1755766513, // eventTime (optional)
+);
+```
 
-function MyApp({ Component, pageProps }) {
-  useEffect(() => {
-    // 1. Init tracking trước
-    tracking.init({
-      baseURL: "https://api.example.com/v1/event_batch",
-      sessionId: "session-id", // K cần thêm vì đã trong thư viện đã tự động làm việc đó
-      sessionSign: "session-sign",
-      // ... other config
-    });
+### 2. Playback Started
 
-    // 2. Init session tracking (tự động gọi session_start)
-    tracking.initSession({
-      progressInterval: 5 * 60 * 1000, // 5 phút (ms)
-      autoStart: true,
-      debug: true,
-      userId: "12345",
-    });
+```javascript
+import { trackPlaybackStarted } from "tracking-lib-ott";
+
+trackPlaybackStarted({
+  contentId: "content_123",
+  contentTitle: "Phim ABC",
+  contentType: 0, // 0=VOD, 1=Live, 2=Channel
+  playbackSession: "md5_session_hash", // MD5(content_id + start_timestamp)
+  videoQuality: "1080p", // 360p | 480p | 720p | 1080p | 2k | 4k
+  startTimestamp: 1755766513,
+  startPosition: 0, // Live=0, VOD: 0 nếu mới, >0 nếu resume
+  duration: 3600, // Live=-1, VOD=số giây
+  // Optional
+  channelId: "channel_vtv1",
+  subContentId: "program_456",
+  subContentTitle: "Thời sự 19h",
+});
+```
 
-    // 3. Cleanup khi unmount
-    return () => {
-      tracking.cleanupSession();
-    };
-  }, []);
+### 3. Playback Progress (gửi định kỳ 5s/25s)
 
-  return <Component {...pageProps} />;
-}
+```javascript
+import { trackPlaybackProgress } from "tracking-lib-ott";
+
+trackPlaybackProgress({
+  contentId: "content_123",
+  contentTitle: "Phim ABC",
+  contentType: 0,
+  playbackSession: "md5_session_hash",
+  totalWatchTime: 60, // Tổng thời gian đã xem (giây, không tính pause)
+  // Optional
+  channelId: "channel_vtv1",
+  subContentId: "program_456",
+  subContentTitle: "Thời sự 19h",
+});
 ```
 
-### Session Config Options
+### 4. Playback Completed
 
-| Option             | Type    | Default       | Mô tả                                 |
-| ------------------ | ------- | ------------- | ------------------------------------- |
-| `progressInterval` | number  | `300000` (5m) | Khoảng thời gian gửi session_progress |
-| `autoStart`        | boolean | `true`        | Tự động gọi session_start khi init    |
-| `debug`            | boolean | `false`       | Hiển thị log                          |
-| `userId`           | string  | `undefined`   | User ID để gửi kèm session_end        |
+```javascript
+import { trackPlaybackCompleted } from "tracking-lib-ott";
+
+trackPlaybackCompleted({
+  contentId: "content_123",
+  contentTitle: "Phim ABC",
+  contentType: 0,
+  playbackSession: "md5_session_hash",
+  totalWatchTime: 3600,
+  // Optional
+  channelId: "channel_vtv1",
+  subContentId: "program_456",
+  subContentTitle: "Thời sự 19h",
+});
+```
 
-### Session Events Payload
+### 5. Playback Paused / Resumed
 
-```json
-// session_start
-{
-  "events": [{
-    "event_name": "session_start",
-    "event_time": 1705734000000,
-    "user_id": "12345"
+```javascript
+import { trackPlaybackPaused, trackPlaybackResumed } from "tracking-lib-ott";
+
+// Khi user pause
+trackPlaybackPaused({
+  contentId: "content_123",
+  contentTitle: "Phim ABC",
+  contentType: 0,
+  playbackSession: "md5_session_hash",
+  positionSec: 120,
+});
 
-  }]
-}
+// Khi user resume
+trackPlaybackResumed({
+  contentId: "content_123",
+  contentTitle: "Phim ABC",
+  contentType: 0,
+  playbackSession: "md5_session_hash",
+  positionSec: 120,
+});
+```
 
-// session_progress (mỗi 5 phút)
-{
-  "events": [{
-    "event_name": "session_progress",
-    "event_time": 1705734300000,
-    "session_duration": 300000,
-    "user_id": "12345"
+### 6. Buffer Started / Ended
 
-  }]
-}
+```javascript
+import { trackBufferStarted, trackBufferEnded } from "tracking-lib-ott";
+
+// Khi bắt đầu buffer
+trackBufferStarted({
+  contentId: "content_123",
+  contentTitle: "Phim ABC",
+  contentType: 0,
+  playbackSession: "md5_session_hash",
+  videoQuality: "1080p",
+  positionSec: 120,
+  reason: "network_congestion", // seek_operation | network_congestion
+});
 
-// session_end (khi đóng tab/app)
-{
-  "events": [{
-    "event_name": "session_end",
-    "event_time": 1705735800000,
-    "session_duration": 1800000,
-    "user_id": "12345"
-  }]
-}
+// Khi kết thúc buffer
+trackBufferEnded({
+  contentId: "content_123",
+  contentTitle: "Phim ABC",
+  contentType: 0,
+  playbackSession: "md5_session_hash",
+  videoQuality: "1080p",
+  positionSec: 120,
+  bufferDurationSec: 3, // Buffer mất 3 giây
+  reason: "network_congestion",
+});
 ```
 
-### Các API khác
+### 7. Quality Changed
 
 ```javascript
-import {
-  sendSessionStart,
-  sendSessionEnd,
-  sendSessionProgress,
-  isSessionStarted,
-  getSessionDuration,
-  updateSessionConfig,
-} from "tracking-lib-ott";
-
-// Gọi manual nếu cần
-sendSessionStart(); // Bắt đầu session
-sendSessionProgress(); // Gửi heartbeat
-sendSessionEnd(); // Kết thúc session
-
-// Kiểm tra trạng thái
-isSessionStarted(); // true/false
-getSessionDuration(); // ms đã chạy
-
-// Cập nhật config
-updateSessionConfig({ progressInterval: 10 * 60 * 1000 });
+import { trackQualityChanged } from "tracking-lib-ott";
+
+trackQualityChanged({
+  contentId: "content_123",
+  contentTitle: "Phim ABC",
+  contentType: 0,
+  playbackSession: "md5_session_hash",
+  fromQuality: "480p",
+  toQuality: "1080p",
+  positionSec: 120,
+  reason: "user_selected", // automatic_abr | user_selected
+});
 ```
 
-### Cơ chế hoạt động
-
-1. **`session_start`**: Gọi tự động khi `initSession()` với `autoStart: true`
-2. **`session_progress`**: Timer chạy định kỳ, chỉ gửi khi tab visible
-3. **`session_end`**: Detect qua `beforeunload` (desktop) và `pagehide` (mobile)
+### 8. Playback Error
 
-> **Lưu ý**: Khi user switch tab, timer sẽ tạm dừng và resume khi user quay lại.
+```javascript
+import { trackPlaybackError } from "tracking-lib-ott";
+
+trackPlaybackError({
+  contentId: "content_123",
+  contentTitle: "Phim ABC",
+  contentType: 0, // 0=VOD, 1=Live
+  playbackSession: "md5_session_hash",
+  errorCode: 404,
+  errorMessage: "Video not found",
+  errorType: "network_error", // video_playback_error, network_error...
+});
+```
 
 ---
 
-## Session ID Cookie Management
-
-Thư viện hỗ trợ **tự động quản lý `session_id`** thông qua cookie. Nếu bạn không truyền `session_id` khi khởi tạo, thư viện sẽ tự động tạo và lưu vào cookie với thời hạn 30 phút.
-
-### Tính năng
-
-- ✅ **Tự động tạo** `session_id` nếu không được truyền lên
-- ✅ **Lưu vào cookie** với thời hạn mặc định 30 phút
-- ✅ **Hỗ trợ group domain** (ví dụ: `.example.com`)
-- ✅ **Tự động gia hạn** cookie mỗi khi có event `session_start`
-- ✅ **Persistent** - Session ID được giữ nguyên khi refresh trang trong vòng 30 phút
-
-### Cách sử dụng
+## Session Lifecycle Tracking
 
-#### 1. Auto-generate Session ID (Khuyến nghị)
+| Event              | Khi nào gọi               |
+| ------------------ | ------------------------- |
+| `session_start`    | User mở app               |
+| `session_progress` | Định kỳ (mặc định 5 phút) |
+| `session_end`      | User đóng tab/browser/app |
 
 ```javascript
 import tracking from "tracking-lib-ott";
 
-// Không cần truyền session_id - thư viện tự động tạo và lưu cookie
-tracking.init({
-  baseURL: "https://api.example.com/v1/event_batch",
-  sessionSign: "session-signature",
-  userId: 12345,
-  deviceId: "device-unique-id",
-  deviceModel: "iPhone 14",
-  deviceBrand: "Apple",
-  ipAddress: "192.168.1.1",
+// Init session tracking
+tracking.initSession({
+  progressInterval: 5 * 60 * 1000, // 5 phút
+  autoStart: true,
   debug: true,
 });
 
-// Session ID đã được tạo tự động và lưu vào cookie: _tracking_session_id
+// Cleanup khi unmount
+tracking.cleanupSession();
 ```
 
-#### 2. Custom Cookie Configuration
-
-```javascript
-tracking.init({
-  baseURL: "https://api.example.com/v1/event_batch",
-  sessionSign: "session-signature",
-  userId: 12345,
-  deviceId: "device-unique-id",
-  deviceModel: "iPhone 14",
-  deviceBrand: "Apple",
-  ipAddress: "192.168.1.1",
-
-  // Cấu hình cookie tùy chỉnh
-  sessionCookieConfig: {
-    cookieName: "my_session_id", // Tên cookie (mặc định: _tracking_session_id)
-    expirationMinutes: 60, // Thời hạn 60 phút (mặc định: 30)
-    domain: ".example.com", // Group domain cho tất cả subdomain
-    path: "/", // Cookie path
-    sameSite: "Lax", // 'Strict' | 'Lax' | 'None'
-  },
-
-  debug: true,
-});
-```
+---
 
-#### 3. Kết hợp với Session Tracking
+## Tích hợp Next.js (Pages Router)
 
 ```javascript
 import { useEffect } from "react";
+import { useRouter } from "next/router";
 import tracking from "tracking-lib-ott";
 
 function MyApp({ Component, pageProps }) {
+  const router = useRouter();
+
   useEffect(() => {
-    // 1. Init tracking (session_id tự động tạo)
+    // 1. Init tracking
     tracking.init({
-      baseURL: "https://api.example.com/v1/event_batch",
-      sessionSign: "session-signature",
-      userId: 12345,
+      baseURL: process.env.NEXT_PUBLIC_TRACKING_URL,
+      appId: "ONPlus",
+      packageId: "com.example.app",
+      sessionSign: "session-sign",
       deviceId: "device-id",
+      platform: "WebPC",
       deviceModel: navigator.userAgent,
       deviceBrand: "Web Browser",
-      ipAddress: "",
-      sessionCookieConfig: {
-        domain: ".example.com",
-        expirationMinutes: 30,
-      },
+      events: [],
       debug: process.env.NODE_ENV === "development",
     });
 
-    // 2. Init session tracking
-    tracking.initSession({
-      autoStart: true,
-      progressInterval: 5 * 60 * 1000,
-      sessionCookieConfig: {
-        domain: ".example.com",
-        expirationMinutes: 30,
-      },
-    });
+    // 2. Set user info (after login)
+    tracking.setUserInfo({ userId: 12345 });
+
+    // 3. Auto track page views
+    const cleanup = tracking.usePageViewTracking(router);
+
+    // 4. Init session tracking
+    tracking.initSession({ autoStart: true });
 
     return () => {
+      cleanup?.();
       tracking.cleanupSession();
     };
-  }, []);
+  }, [router]);
 
   return <Component {...pageProps} />;
 }
-```
-
-### Cookie Configuration Options
-
-| Option              | Type                              | Default                | Mô tả                                                     |
-| ------------------- | --------------------------------- | ---------------------- | --------------------------------------------------------- |
-| `cookieName`        | string                            | `_tracking_session_id` | Tên cookie lưu session_id                                 |
-| `expirationMinutes` | number                            | `30`                   | Thời gian hết hạn cookie (phút)                           |
-| `domain`            | string                            | `""`                   | Domain cho cookie (hỗ trợ group domain như `.domain.com`) |
-| `path`              | string                            | `"/"`                  | Cookie path                                               |
-| `sameSite`          | `"Strict"` \| `"Lax"` \| `"None"` | `"Lax"`                | SameSite attribute                                        |
-
-### Cơ chế hoạt động
 
-1. **Lần đầu khởi tạo** (không có cookie):
-   - Thư viện tạo `session_id` mới (format: `{timestamp}_{random}`)
-   - Lưu vào cookie với thời hạn 30 phút
-   - Ví dụ: `1737603823000_a8f3d9e2`
-
-2. **Refresh trang** (trong vòng 30 phút):
-   - Thư viện đọc `session_id` từ cookie
-   - Sử dụng lại session_id cũ
-   - Không tạo session mới
-
-3. **Session Start Event**:
-   - Mỗi khi có event `session_start`
-   - Cookie được **gia hạn thêm 30 phút** từ thời điểm hiện tại
-   - Ví dụ: 9:15 trigger session_start → cookie expires lúc 9:45
-
-4. **Sau 30 phút không hoạt động**:
-   - Cookie hết hạn và bị xóa
-   - Lần truy cập tiếp theo sẽ tạo `session_id` mới
-
-### Manual Cookie Management
-
-```javascript
-import {
-  generateSessionId,
-  getCookie,
-  setCookie,
-  getOrCreateSessionId,
-  renewSessionCookie,
-  clearSessionCookie,
-} from "tracking-lib-ott";
-
-// Tạo session ID mới
-const newSessionId = generateSessionId();
-console.log(newSessionId); // "1737603823000_a8f3d9e2"
-
-// Lấy hoặc tạo session ID
-const sessionId = getOrCreateSessionId({
-  cookieName: "my_session",
-  expirationMinutes: 30,
-  domain: ".example.com",
-});
-
-// Gia hạn cookie
-renewSessionCookie(sessionId, {
-  cookieName: "my_session",
-  expirationMinutes: 30,
-});
-
-// Xóa cookie
-clearSessionCookie({ cookieName: "my_session" });
-
-// Đọc cookie thủ công
-const value = getCookie("my_session");
-```
-
-### User-Provided Session ID
-
-Nếu bạn muốn tự quản lý `session_id`, vẫn có thể truyền vào như trước:
-
-```javascript
-tracking.init({
-  baseURL: "https://api.example.com/v1/event_batch",
-  sessionId: "my-custom-session-id", // Tự cung cấp
-  sessionSign: "session-signature",
-  // ... other config
-});
-
-// Cookie sẽ KHÔNG được tạo khi bạn tự truyền session_id
+export default MyApp;
 ```
 
 ---
 
 ## Custom Page Mapping
 
-Mặc định thư viện có sẵn mapping cho các page phổ biến. Bạn có thể tuỳ chỉnh:
-
 ```javascript
 tracking.init({
-  baseURL: "...",
   // ... other config
-
   pageMap: {
-    // Thêm hoặc ghi đè page mapping
+    // Override hoặc thêm mới
     phim: { name: "Phim", id: "movie" },
     "the-thao": { name: "Thể thao", id: "sports" },
-    "tin-tuc": { name: "Tin tức", id: "news" },
   },
 });
 ```
 
-**Page mapping mặc định:**
+**Default page mapping:**
 
 | URL Path    | Page Name | Page ID  |
 | ----------- | --------- | -------- |
@@ -474,146 +366,46 @@ tracking.init({
 
 ## API Reference
 
-### `tracking.init(options)`
-
-Khởi tạo thư viện với config.
-
-| Option         | Type    | Required | Mô tả                         |
-| -------------- | ------- | -------- | ----------------------------- |
-| `baseURL`      | string  | ✅       | URL endpoint để gửi events    |
-| `session_id`   | string  | ✅       | Session ID của user           |
-| `session_sign` | string  | ✅       | Session signature             |
-| `user_id`      | number  | ✅       | User ID (-1 nếu chưa login)   |
-| `deviceId`     | string  | ✅       | Device unique ID              |
-| `deviceModel`  | string  | ✅       | Tên model thiết bị            |
-| `deviceBrand`  | string  | ✅       | Hãng thiết bị                 |
-| `ip_address`   | string  | ✅       | IP address                    |
-| `debug`        | boolean | ❌       | Bật/tắt debug logs            |
-| `appName`      | string  | ❌       | Tên app (default: `app_name`) |
-| `platform`     | string  | ❌       | Platform (default: `Web`)     |
-| `pageMap`      | object  | ❌       | Custom page mapping           |
-
-### `tracking.trackPageView(url)`
-
-Track sự kiện xem trang.
-
-```javascript
-tracking.trackPageView("/detail/123?tab=info");
-```
-
-### `tracking.trackEvent(eventName, params)`
-
-Track custom event.
-
-```javascript
-tracking.trackEvent("video_complete", { video_id: "123" });
-```
-
-### `tracking.sendEvent(eventData)`
-
-Gửi event trực tiếp với full payload.
-
-```javascript
-await tracking.sendEvent({
-  event_name: "my_event",
-  ...customData,
-});
-```
-
-### `tracking.usePageViewTracking(router)`
-
-Auto track page views cho Next.js Pages Router.
+### TrackingConfig (Required Fields)
 
-```javascript
-const cleanup = tracking.usePageViewTracking(router);
-// Gọi cleanup() khi unmount
-```
+| Field         | Type   | Giới hạn | Mô tả                                              |
+| ------------- | ------ | -------- | -------------------------------------------------- |
+| `baseURL`     | string | -        | URL endpoint                                       |
+| `appId`       | string | -        | ONPlus, ONLiveTV                                   |
+| `packageId`   | string | ≤ 125    | Package/Bundle ID                                  |
+| `sessionId`   | string | UUID v4  | Session ID                                         |
+| `sessionSign` | string | 16..128  | MD5(append(session_id, secret_key))                |
+| `deviceId`    | string | ≤ 125    | Device unique ID                                   |
+| `platform`    | string | -        | Android, Ios, WebPC, WebMobile, SmartTV, AndroidTV |
+| `deviceModel` | string | ≤ 125    | Model thiết bị                                     |
+| `deviceBrand` | string | ≤ 125    | Hãng thiết bị                                      |
+| `events`      | array  | -        | Mảng events (không rỗng)                           |
 
----
+### TrackingConfig (Optional Fields)
 
-## Event Payload Structure
+| Field             | Type    | Giới hạn | Mô tả              |
+| ----------------- | ------- | -------- | ------------------ |
+| `adId`            | string  | ≤ 125    | GAID/IDFA          |
+| `deviceOsVersion` | string  | ≤ 50     | VD: "14", "17.6"   |
+| `sdkVersion`      | string  | ≤ 50     | Phiên bản SDK      |
+| `debug`           | boolean | -        | Bật/tắt debug logs |
 
-Khi gửi event, thư viện sẽ tự động format payload theo cấu trúc chuẩn:
+> **Lưu ý**: `ip_address` và `carrier_net` KHÔNG cần gửi. Server tự lấy từ header.
 
 ### Event Object Format
 
-Mỗi event được transform thành object với format:
-
-```javascript
-// Input: sendEvent({ event_name: "video_play", video_id: "123", duration: 3600 })
-
-// Output: Event object được tạo
-{
-  "event_id": "550e8400-e29b-41d4-a716-446655440000",  // UUID v4 tự động sinh
-  "event_name": "video_play",                          // Tách riêng từ eventData
-  "event_params": "{\"video_id\":\"123\",\"duration\":3600}",  // Các params còn lại được JSON stringify
-  "event_time": 1705734000,                            // Unix timestamp (seconds)
-  "user_id": 12345                                     // Từ config
-}
-```
-
-### Batch Request Payload
-
-Các events được gom lại và gửi theo batch:
-
-```json
-{
-  "app_name": "app_name",
-  "app_id": "",
-  "package_id": "domain.example.com",
-  "platform": "Web",
-
-  "session_id": "1737603823000_a8f3d9e2",
-  "session_sign": "md5_signature",
-  "user_id": 12345,
-
-  "device_id": "device-unique-id",
-  "device_model": "Chrome 120",
-  "device_brand": "Web Browser",
-  "ip_address": "192.168.1.1",
-
-  "events": [
-    {
-      "event_id": "550e8400-e29b-41d4-a716-446655440000",
-      "event_name": "page_view",
-      "event_params": "{\"page_id\":\"home\",\"page_path\":\"/home\"}",
-      "event_time": 1705734000,
-      "user_id": 12345
-    },
-    {
-      "event_id": "550e8400-e29b-41d4-a716-446655440001",
-      "event_name": "video_play",
-      "event_params": "{\"video_id\":\"123\"}",
-      "event_time": 1705734005,
-      "user_id": 12345
-    }
-  ]
-}
-```
-
-### Giải thích các trường trong Event Object
-
-| Trường         | Type   | Mô tả                                        |
-| -------------- | ------ | -------------------------------------------- |
-| `event_id`     | string | UUID v4 unique cho mỗi event                 |
-| `event_name`   | string | Tên event (tách từ eventData)                |
-| `event_params` | string | JSON string chứa tất cả params còn lại       |
-| `event_time`   | number | Unix timestamp (seconds) thời điểm tạo event |
-| `user_id`      | number | User ID từ config                            |
+| Field          | Type   | Bắt buộc | Mô tả                 |
+| -------------- | ------ | -------- | --------------------- |
+| `user_id`      | bigint | ✅       | -1 nếu chưa đăng nhập |
+| `event_name`   | string | ✅       | Tên event (≤ 125)     |
+| `event_time`   | int    | ✅       | Unix seconds          |
+| `event_params` | string | ❌       | JSON string (≤ 1024)  |
 
 ---
 
-## Debug Mode
+## Publish
 
-Khi bật `debug: true`, thư viện sẽ log ra console:
-
-- Config khi khởi tạo
-- Mỗi event được gửi đi
-- Lỗi nếu có
-
-```javascript
-tracking.init({
-  debug: process.env.NODE_ENV === "development",
-  // ...
-});
+```bash
+npm version patch
+npm publish
 ```