tracking-lib-ott

v1.0.21

Published

5 days ago

Thư viện tracking events dành cho các dự án OTT (Web, Smart TV).

Downloads

2,259

0High
0Medium
0Low

hoantiny

Tracking Library OTT

Thư viện tracking events dành cho các dự án OTT (Web, Smart TV).

Cài đặt

npm install tracking-lib-ott
# hoặc
yarn add tracking-lib-ott

Session ID

const sessionId = getOrCreateSessionId({
  domain: window.location.hostname,
  expirationMinutes: 30,
});

1. Khởi tạo (Init)

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",
});

2. Set User Info

// 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

tracking.trackPageView("/home");
tracking.trackPageView("/detail/123");
tracking.trackPageView("/live/channel-1");

4. Track Custom Event

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:

Flow tracking video

view_content_details → playback_started → playback_progress (định kỳ) → playback_completed
                                       ↘ playback_paused ↔ playback_resumed
                                       ↘ buffer_started → buffer_ended
                                       ↘ quality_changed
                                       ↘ playback_error

1. View Content Details

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)
);

2. Playback Started

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. Playback Progress (gửi định kỳ 5s/25s)

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",
});

4. Playback Completed

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",
});

5. Playback Paused / Resumed

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,
});

6. Buffer Started / Ended

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",
});

7. Quality Changed

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
});

8. Playback Error

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 |

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)

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 <Component {...pageProps} />;
}

export default MyApp;

Custom Page Mapping

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

TrackingConfig (Required Fields)

| 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)

| 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.

Event Object Format

| 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

npm version patch
npm publish