tracking-lib-ott 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,265 @@
+# Tracking Library OTT
+
+Thư viện tracking events dành cho các dự án OTT (Web, iOS, Android).
+
+## Cài đặt
+
+```bash
+npm install tracking-lib-ott
+# hoặc
+yarn add tracking-lib-ott
+```
+
+## Sử dụng cơ bản
+
+### 1. Khởi tạo (Init)
+
+```javascript
+import tracking from "tracking-lib-ott";
+
+tracking.init({
+  baseURL: "https://api.example.com/v1/event_batch",
+  debug: true, // Bật log để debug
+
+  // Thông tin bắt buộc
+  session_id: "unique-session-id",
+  session_sign: "session-signature",
+  user_id: 12345,
+  deviceId: "device-unique-id",
+  deviceModel: "iPhone 14",
+  deviceBrand: "Apple",
+  ip_address: "192.168.1.1",
+
+  // Thông tin tuỳ chọn
+  appName: "on_plus",
+  appId: "app-id",
+  packageId: "com.vtvcab.onsportstv",
+  platform: "Web", // 'Web' | 'Ios' | 'Android'
+  os_version: "17.0",
+  app_version: "1.0.0",
+  language: "vi",
+  country: "VN",
+});
+```
+
+### 2. 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
+
+```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)
+
+### Trong `_app.js` hoặc `_app.tsx`
+
+```javascript
+import { useEffect } from "react";
+import { useRouter } from "next/router";
+import tracking from "tracking-lib-ott";
+
+function MyApp({ Component, pageProps }) {
+  const router = useRouter();
+
+  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;
+```
+
+---
+
+## 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
+    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:**
+
+| URL Path    | Page Name | Page ID  |
+| ----------- | --------- | -------- |
+| `/`         | Home      | home     |
+| `/home`     | Home      | home     |
+| `/search`   | Search    | search   |
+| `/detail`   | Detail    | detail   |
+| `/player`   | Player    | player   |
+| `/video`    | Video     | video    |
+| `/live`     | Live      | live     |
+| `/category` | Category  | category |
+| `/profile`  | Profile   | profile  |
+| `/login`    | Login     | login    |
+
+---
+
+## 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: `on_plus`) |
+| `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.
+
+```javascript
+const cleanup = tracking.usePageViewTracking(router);
+// Gọi cleanup() khi unmount
+```
+
+---
+
+## Event Payload Structure
+
+Mỗi event được gửi lên server có cấu trúc:
+
+```json
+{
+  "app_name": "on_plus",
+  "app_id": "",
+  "package_id": "com.vtvcab.onsportstv",
+  "platform": "Web",
+
+  "session_id": "...",
+  "session_sign": "...",
+  "user_id": 12345,
+
+  "device_id": "...",
+  "device_model": "...",
+  "device_brand": "...",
+  "ip_address": "...",
+
+  "event_name": "page_view",
+  "page_name": "Home",
+  "page_id": "home",
+  "page_path": "/home",
+  "referrer_page_id": ""
+}
+```
+
+---
+
+## Debug Mode
+
+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",
+  // ...
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tracking-lib-ott",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",