tracking-lib-ott 1.0.13 → 1.0.15

package/dist/index.d.cts

@@ -99,29 +99,21 @@ declare const getSessionDuration: () => number;
 
 type TrackingConfig = {
     baseURL: string;
-    appName?: string;
-    appId?: string;
-    packageId?: string;
-    platform?: "Web" | "Ios" | "Android" | string;
     debug?: boolean;
     sessionCookieConfig?: SessionCookieConfig;
-    sessionId?: string;
+    appId: string;
+    packageId: string;
+    sessionId: string;
     sessionSign: string;
-    userId: number;
     deviceId: string;
+    platform: "Android" | "Ios" | "WebPC" | "WebMobile" | "SmartTV" | "AndroidTV";
     deviceModel: string;
     deviceBrand: string;
-    ipAddress: string;
+    events: any[];
+    userId?: number;
     adId?: string;
-    osVersion?: string;
-    netType?: string;
-    carrierNet?: string;
+    deviceOsVersion?: string;
     sdkVersion?: string;
-    appVersion?: string;
-    buildNumber?: string;
-    language?: string;
-    country?: string;
-    events?: any[];
 };
 type PageInfo = {
     name: string;
@@ -129,6 +121,9 @@ type PageInfo = {
 };
 type PageMap = Record<string, PageInfo>;
 type EventData = Record<string, any>;
+type UserInfo = {
+    userId: number;
+};
 type NextRouterLike = {
     asPath: string;
     events: {
@@ -154,6 +149,11 @@ declare const defaultPageMap: PageMap;
 declare const initTracking: (options?: Partial<TrackingConfig> & {
     pageMap?: Partial<PageMap>;
 }) => void;
+/**
+ * Cập nhật thông tin người dùng (userId)
+ * userId sẽ được tự động thêm vào mỗi event trong events array
+ */
+declare const setUserInfo: (userInfo: UserInfo) => void;
 /**
  * Lấy thông tin page từ URL
  */
@@ -170,6 +170,247 @@ declare const trackPageView: (url: string) => void;
  * Track custom event
  */
 declare const trackEvent: (eventName: string, params?: EventData) => void;
+/**
+ * Track view content details event
+ * @param contentId - ID của content (required)
+ * @param contentTitle - Tiêu đề content (required)
+ * @param contentType - Loại content: 0=VOD, 1=Event, 2=Channel (required)
+ * @param channelId - Mã kênh EPG (optional)
+ * @param eventTime - Timestamp Unix (optional, mặc định lấy time hiện tại)
+ */
+declare const trackViewContentDetails: (contentId: string, contentTitle: string, contentType: 0 | 1 | 2, channelId?: string, eventTime?: number) => void;
+/**
+ * Track playback started event
+ * @param params.contentId - ID của content (required)
+ * @param params.contentTitle - Tiêu đề content (required)
+ * @param params.contentType - Loại content: 0=VOD, 1=Live, 2=Channel (required)
+ * @param params.playbackSession - Session ID: MD5(content_id + start_timestamp) (required)
+ * @param params.videoQuality - Chất lượng video: 360p, 480p, 720p, 1080p, 2k, 4k (required)
+ * @param params.startTimestamp - Unix timestamp khi bắt đầu phát (required)
+ * @param params.startPosition - Vị trí bắt đầu: Live=0, VOD: 0 nếu mới, >0 nếu xem lại (required)
+ * @param params.duration - Thời lượng: Live=-1, VOD=số giây (required)
+ * @param params.channelId - Mã kênh EPG (optional)
+ * @param params.subContentId - ID chương trình trong kênh live (optional)
+ * @param params.subContentTitle - Title chương trình trong kênh live (optional)
+ * @param params.eventTime - Unix timestamp (optional)
+ */
+declare const trackPlaybackStarted: (params: {
+    contentId: string;
+    contentTitle: string;
+    contentType: 0 | 1 | 2;
+    playbackSession: string;
+    videoQuality: "360p" | "480p" | "720p" | "1080p" | "2k" | "4k";
+    startTimestamp: number;
+    startPosition: number;
+    duration: number;
+    channelId?: string;
+    subContentId?: string;
+    subContentTitle?: string;
+    eventTime?: number;
+}) => void;
+/**
+ * Track playback progress event
+ * Gửi định kỳ: loop 1 = 5s, loop 2 = 25s để track thời lượng user xem nội dung
+ * Lưu ý: total_watch_time là tổng thời gian xem được (không tính pause)
+ *
+ * @param params.contentId - ID của content (required)
+ * @param params.contentTitle - Tiêu đề content (required)
+ * @param params.contentType - Loại content: 0=VOD, 1=Live, 2=Channel (required)
+ * @param params.playbackSession - Session ID từ playback_started (required)
+ * @param params.totalWatchTime - Tổng thời gian đã xem tính bằng giây (required)
+ * @param params.channelId - Mã kênh EPG (optional)
+ * @param params.subContentId - ID chương trình trong kênh live (optional)
+ * @param params.subContentTitle - Title chương trình trong kênh live (optional)
+ * @param params.eventTime - Unix timestamp (optional)
+ */
+declare const trackPlaybackProgress: (params: {
+    contentId: string;
+    contentTitle: string;
+    contentType: 0 | 1 | 2;
+    playbackSession: string;
+    totalWatchTime: number;
+    channelId?: string;
+    subContentId?: string;
+    subContentTitle?: string;
+    eventTime?: number;
+}) => void;
+/**
+ * Track playback completed event
+ * Tương tự playback_progress nhưng là event cuối cùng khi kết thúc xem
+ * Với Live có thể thoát chủ động thì tracking event này
+ *
+ * @param params.contentId - ID của content (required)
+ * @param params.contentTitle - Tiêu đề content (required)
+ * @param params.contentType - Loại content: 0=VOD, 1=Live, 2=Channel (required)
+ * @param params.playbackSession - Session ID từ playback_started (required)
+ * @param params.totalWatchTime - Tổng thời gian đã xem tính bằng giây (required)
+ * @param params.channelId - Mã kênh EPG (optional)
+ * @param params.subContentId - ID chương trình trong kênh live (optional)
+ * @param params.subContentTitle - Title chương trình trong kênh live (optional)
+ * @param params.eventTime - Unix timestamp (optional)
+ */
+declare const trackPlaybackCompleted: (params: {
+    contentId: string;
+    contentTitle: string;
+    contentType: 0 | 1 | 2;
+    playbackSession: string;
+    totalWatchTime: number;
+    channelId?: string;
+    subContentId?: string;
+    subContentTitle?: string;
+    eventTime?: number;
+}) => void;
+/**
+ * Track playback error event
+ * Trigger khi:
+ * - Video không load/play được (network timeout, source 404)
+ * - Player error (format không hỗ trợ, DRM error)
+ * - Source error (media source and manifest-related errors)
+ *
+ * @param params.contentId - ID của content (required)
+ * @param params.contentTitle - Tiêu đề content (required)
+ * @param params.contentType - Loại content: 0=VOD, 1=Live (required)
+ * @param params.playbackSession - Session ID từ playback_started (required)
+ * @param params.channelId - Mã kênh EPG (optional)
+ * @param params.errorCode - Mã lỗi (optional)
+ * @param params.errorMessage - Thông báo lỗi (optional)
+ * @param params.errorType - Loại lỗi: video_playback_error, network_error... (optional)
+ * @param params.eventTime - Unix timestamp (optional)
+ */
+declare const trackPlaybackError: (params: {
+    contentId: string;
+    contentTitle: string;
+    contentType: 0 | 1;
+    playbackSession: string;
+    channelId?: string;
+    errorCode?: number;
+    errorMessage?: string;
+    errorType?: string;
+    eventTime?: number;
+}) => void;
+/**
+ * Track quality changed event
+ * Trigger khi:
+ * - Tự động thay đổi do thuật toán ABR
+ * - Thay đổi chủ động bởi người dùng
+ *
+ * @param params.contentId - ID của content (required)
+ * @param params.contentTitle - Tiêu đề content (required)
+ * @param params.contentType - Loại content: 0=VOD, 1=Live, 2=Channel (required)
+ * @param params.playbackSession - Session ID từ playback_started (required)
+ * @param params.fromQuality - Chất lượng trước khi đổi (required)
+ * @param params.toQuality - Chất lượng sau khi đổi (required)
+ * @param params.positionSec - VOD: vị trí hiện tại, Live: số giây từ lúc bắt đầu xem (required)
+ * @param params.channelId - Mã kênh EPG (optional)
+ * @param params.reason - Lý do: automatic_abr hoặc user_selected (optional)
+ * @param params.eventTime - Unix timestamp (optional)
+ */
+declare const trackQualityChanged: (params: {
+    contentId: string;
+    contentTitle: string;
+    contentType: 0 | 1 | 2;
+    playbackSession: string;
+    fromQuality: "360p" | "480p" | "720p" | "1080p" | "2k" | "4k";
+    toQuality: "360p" | "480p" | "720p" | "1080p" | "2k" | "4k";
+    positionSec: number;
+    channelId?: string;
+    reason?: "automatic_abr" | "user_selected";
+    eventTime?: number;
+}) => void;
+/**
+ * Track buffer started event
+ * Buffering xảy ra khi video không còn segment kế tiếp để phát, video sẽ pause để tải thêm segment
+ *
+ * @param params.contentId - ID của content (required)
+ * @param params.contentTitle - Tiêu đề content (required)
+ * @param params.contentType - Loại content: 0=VOD, 1=Live, 2=Channel (required)
+ * @param params.playbackSession - Session ID từ playback_started (required)
+ * @param params.videoQuality - Chất lượng video hiện tại (required)
+ * @param params.positionSec - VOD: vị trí hiện tại, Live: số giây từ lúc bắt đầu xem (required)
+ * @param params.channelId - Mã kênh EPG (optional)
+ * @param params.reason - Lý do: seek_operation, network_congestion (optional)
+ * @param params.eventTime - Unix timestamp (optional)
+ */
+declare const trackBufferStarted: (params: {
+    contentId: string;
+    contentTitle: string;
+    contentType: 0 | 1 | 2;
+    playbackSession: string;
+    videoQuality: "360p" | "480p" | "720p" | "1080p" | "2k" | "4k";
+    positionSec: number;
+    channelId?: string;
+    reason?: "seek_operation" | "network_congestion";
+    eventTime?: number;
+}) => void;
+/**
+ * Track buffer ended event
+ * Khi buffering kết thúc và video tiếp tục phát
+ *
+ * @param params.contentId - ID của content (required)
+ * @param params.contentTitle - Tiêu đề content (required)
+ * @param params.contentType - Loại content: 0=VOD, 1=Live, 2=Channel (required)
+ * @param params.playbackSession - Session ID từ playback_started (required)
+ * @param params.videoQuality - Chất lượng video hiện tại (required)
+ * @param params.positionSec - VOD: vị trí hiện tại, Live: số giây từ lúc bắt đầu xem (required)
+ * @param params.bufferDurationSec - Tổng số giây mà buffer xảy ra (required)
+ * @param params.channelId - Mã kênh EPG (optional)
+ * @param params.reason - Lý do: seek_operation, network_congestion (optional)
+ * @param params.eventTime - Unix timestamp (optional)
+ */
+declare const trackBufferEnded: (params: {
+    contentId: string;
+    contentTitle: string;
+    contentType: 0 | 1 | 2;
+    playbackSession: string;
+    videoQuality: "360p" | "480p" | "720p" | "1080p" | "2k" | "4k";
+    positionSec: number;
+    bufferDurationSec: number;
+    channelId?: string;
+    reason?: "seek_operation" | "network_congestion";
+    eventTime?: number;
+}) => void;
+/**
+ * Track playback paused event
+ * Khi user pause video
+ *
+ * @param params.contentId - ID của content (required)
+ * @param params.contentTitle - Tiêu đề content (required)
+ * @param params.contentType - Loại content: 0=VOD, 1=Live, 2=Channel (required)
+ * @param params.playbackSession - Session ID từ playback_started (required)
+ * @param params.positionSec - VOD: vị trí hiện tại, Live: số giây từ lúc bắt đầu xem (required)
+ * @param params.channelId - Mã kênh EPG (optional)
+ * @param params.eventTime - Unix timestamp (optional)
+ */
+declare const trackPlaybackPaused: (params: {
+    contentId: string;
+    contentTitle: string;
+    contentType: 0 | 1 | 2;
+    playbackSession: string;
+    positionSec: number;
+    channelId?: string;
+    eventTime?: number;
+}) => void;
+/**
+ * Track playback resumed event
+ * Khi user resume video sau khi pause
+ *
+ * @param params.contentId - ID của content (required)
+ * @param params.contentTitle - Tiêu đề content (required)
+ * @param params.contentType - Loại content: 0=VOD, 1=Live, 2=Channel (required)
+ * @param params.playbackSession - Session ID từ playback_started (required)
+ * @param params.positionSec - VOD: vị trí hiện tại, Live: số giây từ lúc bắt đầu xem (required)
+ * @param params.channelId - Mã kênh EPG (optional)
+ * @param params.eventTime - Unix timestamp (optional)
+ */
+declare const trackPlaybackResumed: (params: {
+    contentId: string;
+    contentTitle: string;
+    contentType: 0 | 1 | 2;
+    playbackSession: string;
+    positionSec: number;
+    channelId?: string;
+    eventTime?: number;
+}) => void;
 /**
  * Hook cho Next.js - auto track page views
  * Dùng cho Next.js Pages Router (next/router)
@@ -180,8 +421,110 @@ declare const tracking: {
     init: (options?: Partial<TrackingConfig> & {
         pageMap?: Partial<PageMap>;
     }) => void;
+    setUserInfo: (userInfo: UserInfo) => void;
     trackPageView: (url: string) => void;
     trackEvent: (eventName: string, params?: EventData) => void;
+    trackViewContentDetails: (contentId: string, contentTitle: string, contentType: 0 | 1 | 2, channelId?: string, eventTime?: number) => void;
+    trackPlaybackStarted: (params: {
+        contentId: string;
+        contentTitle: string;
+        contentType: 0 | 1 | 2;
+        playbackSession: string;
+        videoQuality: "360p" | "480p" | "720p" | "1080p" | "2k" | "4k";
+        startTimestamp: number;
+        startPosition: number;
+        duration: number;
+        channelId?: string;
+        subContentId?: string;
+        subContentTitle?: string;
+        eventTime?: number;
+    }) => void;
+    trackPlaybackProgress: (params: {
+        contentId: string;
+        contentTitle: string;
+        contentType: 0 | 1 | 2;
+        playbackSession: string;
+        totalWatchTime: number;
+        channelId?: string;
+        subContentId?: string;
+        subContentTitle?: string;
+        eventTime?: number;
+    }) => void;
+    trackPlaybackCompleted: (params: {
+        contentId: string;
+        contentTitle: string;
+        contentType: 0 | 1 | 2;
+        playbackSession: string;
+        totalWatchTime: number;
+        channelId?: string;
+        subContentId?: string;
+        subContentTitle?: string;
+        eventTime?: number;
+    }) => void;
+    trackPlaybackError: (params: {
+        contentId: string;
+        contentTitle: string;
+        contentType: 0 | 1;
+        playbackSession: string;
+        channelId?: string;
+        errorCode?: number;
+        errorMessage?: string;
+        errorType?: string;
+        eventTime?: number;
+    }) => void;
+    trackQualityChanged: (params: {
+        contentId: string;
+        contentTitle: string;
+        contentType: 0 | 1 | 2;
+        playbackSession: string;
+        fromQuality: "360p" | "480p" | "720p" | "1080p" | "2k" | "4k";
+        toQuality: "360p" | "480p" | "720p" | "1080p" | "2k" | "4k";
+        positionSec: number;
+        channelId?: string;
+        reason?: "automatic_abr" | "user_selected";
+        eventTime?: number;
+    }) => void;
+    trackBufferStarted: (params: {
+        contentId: string;
+        contentTitle: string;
+        contentType: 0 | 1 | 2;
+        playbackSession: string;
+        videoQuality: "360p" | "480p" | "720p" | "1080p" | "2k" | "4k";
+        positionSec: number;
+        channelId?: string;
+        reason?: "seek_operation" | "network_congestion";
+        eventTime?: number;
+    }) => void;
+    trackBufferEnded: (params: {
+        contentId: string;
+        contentTitle: string;
+        contentType: 0 | 1 | 2;
+        playbackSession: string;
+        videoQuality: "360p" | "480p" | "720p" | "1080p" | "2k" | "4k";
+        positionSec: number;
+        bufferDurationSec: number;
+        channelId?: string;
+        reason?: "seek_operation" | "network_congestion";
+        eventTime?: number;
+    }) => void;
+    trackPlaybackPaused: (params: {
+        contentId: string;
+        contentTitle: string;
+        contentType: 0 | 1 | 2;
+        playbackSession: string;
+        positionSec: number;
+        channelId?: string;
+        eventTime?: number;
+    }) => void;
+    trackPlaybackResumed: (params: {
+        contentId: string;
+        contentTitle: string;
+        contentType: 0 | 1 | 2;
+        playbackSession: string;
+        positionSec: number;
+        channelId?: string;
+        eventTime?: number;
+    }) => void;
     sendEvent: (eventData: EventData) => Promise<Response | void>;
     getPageInfo: (url: string) => PageInfo;
     usePageViewTracking: (router: NextRouterLike) => (() => void) | undefined;
@@ -192,4 +535,4 @@ declare const tracking: {
     sessionEnd: () => void;
 };
 
-export { type EventData, type NextRouterLike, type PageInfo, type PageMap, type SessionConfig, type SessionCookieConfig, type TrackingConfig, cleanupSessionTracking, clearSessionCookie, tracking as default, defaultConfig, defaultPageMap, generateSessionId, getCookie, getOrCreateSessionId, getPageInfo, getSessionDuration, initSessionTracking, initTracking, isSessionStarted, renewSessionCookie, sendEvent, sendSessionEnd, sendSessionProgress, sendSessionStart, setCookie, trackEvent, trackPageView, updateSessionConfig, usePageViewTracking };
+export { type EventData, type NextRouterLike, type PageInfo, type PageMap, type SessionConfig, type SessionCookieConfig, type TrackingConfig, type UserInfo, cleanupSessionTracking, clearSessionCookie, tracking as default, defaultConfig, defaultPageMap, generateSessionId, getCookie, getOrCreateSessionId, getPageInfo, getSessionDuration, initSessionTracking, initTracking, isSessionStarted, renewSessionCookie, sendEvent, sendSessionEnd, sendSessionProgress, sendSessionStart, setCookie, setUserInfo, trackBufferEnded, trackBufferStarted, trackEvent, trackPageView, trackPlaybackCompleted, trackPlaybackError, trackPlaybackPaused, trackPlaybackProgress, trackPlaybackResumed, trackPlaybackStarted, trackQualityChanged, trackViewContentDetails, updateSessionConfig, usePageViewTracking };