Thư viện tracking events dành cho các dự án OTT (Web, Smart TV).
npm install tracking-lib-ottbash
npm install tracking-lib-ott
hoặc
yarn add tracking-lib-ott
`
Session ID
`javascript
const sessionId = getOrCreateSessionId({
domain: window.location.hostname,
expirationMinutes: 30,
});
`
$3
`javascript
import tracking from "tracking-lib-ott";
tracking.init({
baseURL: "https://api.example.com/v2/event_batch",
debug: true,
// Required fields
appId: "ONPlus", // ONPlus, ONLiveTV
packageId: "Name of app",
sessionSign: "md5_signature", // MD5(append(sessionId, secret_key))
deviceId: "device-unique-id",
platform: "SmartTV", // WebPC | WebMobile | SmartTV | AndroidTV
deviceModel: "Samsung TV 2024",
deviceBrand: "Samsung",
events: [],
userId: -1, // User ID, -1 nếu chưa đăng nhập
// Optional fields
adId: "gaid-or-idfa",
deviceOsVersion: "17.0",
sdkVersion: "1.0.0",
});
`
$3
`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
`javascript
tracking.trackPageView("/home");
tracking.trackPageView("/detail/123");
tracking.trackPageView("/live/channel-1");
`
$3
`javascript
tracking.trackEvent("button_click", {
button_id: "subscribe_btn",
page_id: "detail",
});
tracking.trackEvent("search", {
keyword: "bóng đá",
results_count: 25,
});
`
---
Video Playback Events
Thư viện hỗ trợ các events cho video player:
$3
`
view_content_details → playback_started → playback_progress (định kỳ) → playback_completed
↘ playback_paused ↔ playback_resumed
↘ buffer_started → buffer_ended
↘ quality_changed
↘ playback_error
`
$3
`javascript
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)
);
`
$3
`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
`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",
});
`
$3
`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",
});
`
$3
`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,
});
`
$3
`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
});
// 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",
});
`
$3
`javascript
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
});
`
$3
`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 Lifecycle Tracking
| 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";
// Init session tracking
tracking.initSession({
progressInterval: 5 60 1000, // 5 phút
autoStart: true,
debug: true,
});
// Cleanup khi unmount
tracking.cleanupSession();
`
---
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
tracking.init({
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",
events: [],
debug: process.env.NODE_ENV === "development",
});
// 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
}
export default MyApp;
`
---
Custom Page Mapping
`javascript
tracking.init({
// ... other config
pageMap: {
// Override hoặc thêm mới
phim: { name: "Phim", id: "movie" },
"the-thao": { name: "Thể thao", id: "sports" },
},
});
`
Default page mapping:
| 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
$3
| 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) |
$3
| 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 |
> Lưu ý: ip_address và carrier_net KHÔNG cần gửi. Server tự lấy từ header.
$3
| 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) |
---
Publish
`bash
npm version patch
npm publish
``