@newrelic/video-core 5.0.2 → 5.1.0

package/dist/types/videotracker.d.ts

@@ -0,0 +1,366 @@
+import Tracker, { TrackerOptions } from "./tracker";
+import TrackerState from "./videotrackerstate";
+export interface VideoTrackerOptions extends TrackerOptions {
+    isAd?: boolean;
+    adsTracker?: VideoTracker;
+    src?: string;
+    tag?: any;
+}
+/**
+ * Base video tracker class provides extensible tracking over video elements. See {@link Tracker}.
+ * Extend this class to create your own video tracker class. Override getter methods and
+ * registerListeners/unregisterListeners to provide full integration with your video experience.
+ *
+ * @example
+ * Tracker instances should be added to Core library to start sending data:
+ * nrvideo.Core.addTracker(new Tracker())
+ *
+ * @extends Tracker
+ */
+declare class VideoTracker extends Tracker {
+    static Events: Record<string, string>;
+    /**
+     * TrackerState instance. Stores the state of the view. Tracker will automatically update the
+     * state of its instance, so there's no need to modify/interact with it manually.
+     * @type TrackerState
+     */
+    state: TrackerState;
+    /**
+     * Another Tracker instance to track ads.
+     * @type Tracker
+     */
+    adsTracker: VideoTracker | null;
+    /** Redeclared narrower than base Tracker's `Tracker | null` — VideoTracker's own
+     * methods (getViewId, getAdPosition, sendStart, ...) always call it as a VideoTracker.
+     * Type-only (`declare`); the real assignment happens in the base Tracker constructor. */
+    parentTracker: VideoTracker | null;
+    /**
+     * Last bufferType value.
+     * @private
+     */
+    _lastBufferType: string | null;
+    _userId: any;
+    _src: string | null;
+    player?: any;
+    tag?: any;
+    _lastWebkitBitrate?: number;
+    _lastAdRendition?: number | null;
+    _lastRendition?: number | null;
+    /**
+     * Constructor, receives player and options.
+     * Lifecycle: constructor > {@link setOptions} > {@link setPlayer} > {@link registerListeners}.
+     *
+     * @param {Object} [player] Player to track. See {@link setPlayer}.
+     * @param {Object} [options] Options for the tracker. See {@link setOptions}.
+     */
+    constructor(player?: any, options?: VideoTrackerOptions);
+    setUserId(userId: any): void;
+    /**
+     * Set options for the Tracker.
+     *
+     * @param {Object} [options] Options for the tracker.
+     * @param {Boolean} [options.isAd] True if the tracker is tracking ads. See {@link setIsAd}.
+     * @param {number} [options.heartbeat] Set time between heartbeats. See {@link heartbeat}.
+     * @param {Object} [options.customData] Set custom data. See {@link customData}.
+     * @param {Tracker} [options.parentTracker] Set parent tracker. See {@link parentTracker}.
+     * @param {Tracker} [options.adsTracker] Set ads tracker. See {@link adsTracker}.
+     * @param {Object} [options.tag] DOM element to track. See {@link setPlayer}.
+     */
+    setOptions(options?: VideoTrackerOptions): void;
+    /**
+     * Set a player and/or a tag. If there was one already defined, it will call dispose() first.
+     * Will call this.registerListeners() afterwards.
+     *
+     * @param {Object|string} player New player to save as this.player. If a string is passed,
+     * document.getElementById will be called.
+     * @param {DOMObject|string} [tag] Optional DOMElement to save as this.tag. If a string is passed,
+     * document.getElementById will be called.
+     */
+    setPlayer(player: any, tag?: any): void;
+    /** Returns true if the tracker is currently on ads. */
+    isAd(): boolean;
+    /** Sets if the tracker is currenlty tracking ads */
+    setIsAd(isAd: boolean): void;
+    /**
+     * Use this function to set up a child ad tracker. You will be able to access it using
+     * this.adsTracker.
+     *
+     * @param {Tracker} tracker Ad tracker to add
+     */
+    setAdsTracker(tracker?: VideoTracker | null): void;
+    /**
+     * Dispose current adsTracker.
+     */
+    disposeAdsTracker(): void;
+    /**
+     * Prepares tracker to dispose. Calls unregisterListener and drops references to player and tag.
+     */
+    dispose(): void;
+    /**
+     * Override this method to register listeners to player/tag.
+     * @example
+     * class SpecificTracker extends Tracker {
+     *  registerListeners() {
+     *    this.player.on('play', () => this.playHandler)
+     *  }
+     *
+     *  playHandler() {
+     *    this.send(VideoTracker.Events.REQUESTED)
+     *  }
+     * }
+     */
+    registerListeners(): void;
+    /**
+     * Override this method to unregister listeners to player/tag created in registerListeners
+     * @example
+     * class SpecificTracker extends Tracker {
+     *  registerListeners() {
+     *    this.player.on('play', () => this.playHandler)
+     *  }
+     *
+     *  unregisterListeners() {
+     *    this.player.off('play', () => this.playHandler)
+     *  }
+     *
+     *  playHandler() {
+     *    this.send(VideoTracker.Events.REQUESTED)
+     *  }
+     * }
+     */
+    unregisterListeners(): void;
+    /**
+     * Trackers will generate unique id's for every new video iteration. If you have your own unique
+     * view value, you can override this method to return it.
+     * If the tracker has a parentTracker defined, parent viewId will be used.
+     */
+    getViewId(): string;
+    /**
+     * Trackers will generate unique id's for every new video session. If you have your own unique
+     * view value, you can override this method to return it.
+     * If the tracker has a parentTracker defined, parent viewId will be used.
+     */
+    getViewSession(): string;
+    /** Override to return the Id of the video. */
+    getVideoId(): any;
+    /** Override to return Title of the video. */
+    getTitle(): any;
+    /** Override to return True if the video is live. */
+    isLive(): any;
+    /** Override to return Bitrate (in bits) of the video. */
+    getBitrate(): number | null;
+    /** Override to return the manifest-declared bitrate in bps (Indicated Bitrate). */
+    getManifestBitrate(): number | null;
+    /** Override to return the measured network bitrate in bps (Observed Bitrate). */
+    getSegmentDownloadBitrate(): number | null;
+    /** Override to return the download throughput in bps. */
+    getNetworkDownloadBitrate(): number | null;
+    /** Calculates consumed bitrate using webkitVideoDecodedByteCount. */
+    getWebkitBitrate(): number | null | undefined;
+    /** Override to return Name of the rendition (ie: 1080p). */
+    getRenditionName(): any;
+    /** Override to return Target Bitrate of the rendition. */
+    getRenditionBitrate(): any;
+    /**
+     * This method will return 'up', 'down' or null depending on if the bitrate of the rendition
+     * have changed from the last time it was called.
+     *
+     * @param {boolean} [saveNewRendition=false] If true, current rendition will be stored to be used
+     * the next time this method is called. This allows you to call this.getRenditionShift() without
+     * saving the current rendition and thus preventing interferences with RENDITION_CHANGE events.
+     */
+    getRenditionShift(saveNewRendition?: boolean): "up" | "down" | null;
+    /** Override to return renidtion actual Height (before re-scaling). */
+    getRenditionHeight(): any;
+    /** Override to return rendition actual Width (before re-scaling). */
+    getRenditionWidth(): any;
+    /** Override to return Duration of the video, in ms. */
+    getDuration(): any;
+    /** Override to return Playhead (currentTime) of the video, in ms. */
+    getPlayhead(): any;
+    /**
+     * Override to return Language of the video. We recommend using locale notation, ie: en_US.
+     * {@see https://gist.github.com/jacobbubu/1836273}
+     */
+    getLanguage(): any;
+    /** Override to return URL of the resource being played. */
+    getSrc(): any;
+    /** Override to return Playrate (speed) of the video. ie: 1.0, 0.5, 1.25... */
+    getPlayrate(): any;
+    /** Override to return True if the video is currently muted. */
+    isMuted(): any;
+    /** Override to return True if the video is currently fullscreen. */
+    isFullscreen(): any;
+    /** Override to return the CDN serving the content. */
+    getCdn(): any;
+    /** Override to return the Name of the player. */
+    getPlayerName(): string;
+    /** Override to return the Version of the player. */
+    getPlayerVersion(): string;
+    /** Override to return current FPS (Frames per second). */
+    getFps(): any;
+    /**
+     * Override to return if the player was autoplayed. By default: this.tag.autoplay
+     */
+    isAutoplayed(): any;
+    /**
+     * Override to return the player preload attribute. By default: this.tag.preload
+     */
+    getPreload(): any;
+    /**
+     * Override to return Quartile of the ad. 0 before first, 1 after first quartile, 2 after
+     * midpoint, 3 after third quartile, 4 when completed.
+     */
+    getAdQuartile(): any;
+    /**
+     * Override to return the position of the ad. Use {@link Constants.AdPositions} enum
+     * to fill this data.
+     */
+    getAdPosition(): any;
+    /**
+     * Override to return the ad partner. ie: ima, freewheel...
+     */
+    getAdPartner(): any;
+    /**
+     * Override to return the creative id of the ad.
+     */
+    getAdCreativeId(): any;
+    /**
+     * Override to return the instrumentation of the player.
+     */
+    getInstrumentationProvider(): any;
+    getInstrumentationName(): any;
+    getInstrumentationVersion(): any;
+    /**
+     * Do NOT override. This method fills all the appropiate attributes for tracked video.
+     *
+     * @param {object} [att] Collection of key value attributes
+     * @return {object} Filled attributes
+     * @final
+     */
+    getAttributes(att?: Record<string, any>, type?: string): Record<string, any>;
+    /**
+     * Sends custom event and registers a timeSince attribute.
+     * @param {Object} [actionName] Custom action name.
+     * @param {Object} [timeSinceAttName] Custom timeSince attribute name.
+     * @param {Object} [att] Collection of key:value attributes to send with the request.
+     */
+    sendCustom(actionName: string, timeSinceAttName: string, att?: Record<string, any>): void;
+    /**
+     * Sends associated event and changes view state. An internal state machine will prevent
+     * duplicated events. Should be associated to an event using registerListeners.
+     * @param {Object} [att] Collection of key:value attributes to send with the request.
+     */
+    sendPlayerReady(att?: Record<string, any>): void;
+    /**
+     * Sends associated event and changes view state. An internal state machine will prevent
+     * duplicated events. Should be associated to an event using registerListeners. Calls
+     * {@link startHeartbeat}.
+     * @param {Object} [att] Collection of key:value attributes to send with the request.
+     */
+    sendRequest(att?: Record<string, any>): void;
+    /**
+     * Sends associated event and changes view state. An internal state machine will prevent
+     * duplicated events. Should be associated to an event using registerListeners.
+     * @param {Object} [att] Collection of key:value attributes to send with the request.
+     */
+    sendStart(att?: Record<string, any>): void;
+    /**
+     * Sends associated event and changes view state. An internal state machine will prevent
+     * duplicated events. Should be associated to an event using registerListeners. Calls
+     * {@link stopHeartbeat}.
+     * @param {Object} [att] Collection of key:value attributes to send with the request.
+     */
+    sendEnd(att?: Record<string, any>): void;
+    /**
+     * Sends associated event and changes view state. An internal state machine will prevent
+     * duplicated events. Should be associated to an event using registerListeners.
+     * @param {Object} [att] Collection of key:value attributes to send with the request.
+     */
+    sendPause(att?: Record<string, any>): void;
+    /**
+     * Sends associated event and changes view state. An internal state machine will prevent
+     * duplicated events. Should be associated to an event using registerListeners.
+     * @param {Object} [att] Collection of key:value attributes to send with the request.
+     */
+    sendResume(att?: Record<string, any>): void;
+    /**
+     * Sends associated event and changes view state. An internal state machine will prevent
+     * duplicated events. Should be associated to an event using registerListeners.
+     * @param {Object} [att] Collection of key:value attributes to send with the request.
+     */
+    sendBufferStart(att?: Record<string, any>): void;
+    /**
+     * Sends associated event and changes view state. An internal state machine will prevent
+     * duplicated events. Should be associated to an event using registerListeners.
+     * @param {Object} [att] Collection of key:value attributes to send with the request.
+     */
+    sendBufferEnd(att?: Record<string, any>): void;
+    buildBufferAttributes(att: Record<string, any>): Record<string, any>;
+    /**
+     * Sends associated event and changes view state. An internal state machine will prevent
+     * duplicated events. Should be associated to an event using registerListeners.
+     * @param {Object} [att] Collection of key:value attributes to send with the request.
+     */
+    sendSeekStart(att?: Record<string, any>): void;
+    /**
+     * Sends associated event and changes view state. An internal state machine will prevent
+     * duplicated events. Should be associated to an event using registerListeners.
+     * @param {Object} [att] Collection of key:value attributes to send with the request.
+     */
+    sendSeekEnd(att?: Record<string, any>): void;
+    /**
+     * Sends associated event and changes view state. An internal state machine will prevent
+     * duplicated events. Should be associated to an event using registerListeners.
+     * @param {Object} [att] Collection of key:value attributes to send with the request.
+     * @param {String} att.state Download requires a string to distinguish different states.
+     */
+    sendDownload(att?: Record<string, any>): void;
+    /**
+     * Sends associated event and changes view state. An internal state machine will prevent
+     * duplicated events. Should be associated to an event using registerListeners.
+     * @param {Object} [att] Collection of key:value attributes to send with the request.
+     */
+    sendError(att?: Record<string, any>): void;
+    /**
+     * Sends associated event and changes view state. An internal state machine will prevent
+     * duplicated events. Should be associated to an event using registerListeners.
+     * @param {Object} [att] Collection of key:value attributes to send with the request.
+     */
+    sendRenditionChanged(att?: Record<string, any>): void;
+    /**
+     * Sends associated event and changes view state. Heartbeat will automatically be sent every
+     * 10 seconds. There's no need to call this manually.
+     * @param {Object} [att] Collection of key:value attributes to send with the request.
+     * @param {number} att.url Url of the clicked ad.
+     *
+     */
+    sendHeartbeat(att?: Record<string, any>): void;
+    adjustElapsedTimeForPause(elapsedTime: number): number;
+    /**
+     * Sends associated event and changes view state. An internal state machine will prevent
+     * duplicated events. Should be associated to an event using registerListeners.
+     * @param {Object} [att] Collection of key:value attributes to send with the request.
+     */
+    sendAdBreakStart(att?: Record<string, any>): void;
+    /**
+     * Sends associated event and changes view state. An internal state machine will prevent
+     * duplicated events. Should be associated to an event using registerListeners.
+     * @param {Object} [att] Collection of key:value attributes to send with the request.
+     */
+    sendAdBreakEnd(att?: Record<string, any>): void;
+    /**
+     * Sends associated event and changes view state. An internal state machine will prevent
+     * duplicated events. Should be associated to an event using registerListeners.
+     * @param {Object} [att] Collection of key:value attributes to send with the request.
+     * @param {number} att.quartile Number of the quartile.
+     */
+    sendAdQuartile(att?: Record<string, any>): void;
+    /**
+     * Sends associated event and changes view state. An internal state machine will prevent
+     * duplicated events. Should be associated to an event using registerListeners.
+     * @param {Object} [att] Collection of key:value attributes to send with the request.
+     * @param {number} att.url Url of the clicked ad.
+     */
+    sendAdClick(att?: Record<string, any>): void;
+}
+export default VideoTracker;

package/dist/types/videotrackerstate.d.ts

@@ -0,0 +1,228 @@
+import Chrono from "./chrono";
+/**
+ * State machine for a VideoTracker and its monitored video.
+ */
+declare class VideoTrackerState {
+    _viewSession: string | null;
+    _viewCount: number;
+    _isAd: boolean;
+    numberOfErrors: number;
+    numberOfAds: number;
+    numberOfVideos: number;
+    totalPlaytime: number;
+    weightedAverageBitrate: number;
+    totalAdPlaytime: number;
+    isAdBreak: boolean;
+    initialBufferingHappened: boolean;
+    startupTime: number | null;
+    peakBitrate: number;
+    partialAverageBitrate: number;
+    _totalBitrateDuration: number;
+    weightedBitrate: number;
+    _lastBitrate: number | null;
+    _lastBitrateChangeTimestamp: number | null;
+    _downloadBitrates: number[];
+    _lastDownloadBitrate: number | null;
+    totalSwitchUps: number;
+    totalSwitchDowns: number;
+    totalPauseTime: number;
+    _playedRenditions: Set<string>;
+    hadStartupError: boolean;
+    hadPlaybackError: boolean;
+    totalRebufferingTime: number;
+    isPlayerReady: boolean;
+    isRequested: boolean;
+    isStarted: boolean;
+    isPaused: boolean;
+    isSeeking: boolean;
+    isBuffering: boolean;
+    isPlaying: boolean;
+    timeSinceRequested: Chrono;
+    timeSinceStarted: Chrono;
+    timeSincePaused: Chrono;
+    timeSinceSeekBegin: Chrono;
+    timeSinceBufferBegin: Chrono;
+    timeSinceAdBreakStart: Chrono;
+    timeSinceLastDownload: Chrono;
+    timeSinceLastHeartbeat: Chrono;
+    timeSinceLastRenditionChange: Chrono;
+    timeSinceLastAdQuartile: Chrono;
+    timeSinceLastAd: Chrono;
+    timeSinceLastError: Chrono;
+    timeSinceLastAdError: Chrono;
+    timeSinceResumed: Chrono;
+    timeSinceSeekEnd: Chrono;
+    playtimeSinceLastEvent: Chrono;
+    customTimeSinceAttributes: Record<string, Chrono>;
+    elapsedTime: Chrono;
+    bufferElapsedTime: Chrono;
+    _totalAdPlaytime: Chrono;
+    /** @private */
+    _createdAt: number;
+    _hb: boolean;
+    _acc: number;
+    _bufferAcc: number;
+    isError?: boolean;
+    /** Constructor */
+    constructor();
+    /** Resets all flags and chronos. */
+    reset(): void;
+    /** Resets flags. */
+    resetFlags(): void;
+    /** Resets chronos. */
+    resetChronos(): void;
+    /** Returns true if the tracker is currently on ads. */
+    isAd(): boolean;
+    /** Sets if the tracker is currenlty tracking ads */
+    setIsAd(isAd: boolean): void;
+    /**
+     * Set the Chrono for the custom attribute
+     *
+     * @param {object} name Time since attribute name.
+     */
+    setTimeSinceAttribute(name: string): void;
+    /**
+     * Delete a time since attribute
+     *
+     * @param {object} name Time since attribute name.
+     */
+    removeTimeSinceAttribute(name: string): void;
+    /**
+     * Returns a random-generated view Session ID, useful to sort by views.
+     */
+    getViewSession(): string;
+    /**
+     * Returns a random-generated view Session ID, plus a view count, allowing you to distinguish
+     * between two videos played in the same session.
+     */
+    getViewId(): string;
+    /**
+     * Fills given object with state-based attributes.
+     *
+     * @param {object} att Collection fo key value attributes
+     * @return {object} Filled attributes
+     */
+    getStateAttributes(att?: Record<string, any>): Record<string, any>;
+    getQoeAttributes(att?: Record<string, any>): Record<string, any>;
+    /**
+     * Calculate the bufferType attribute.
+     *
+     * @param {boolean} isInitialBuffering Is initial buffering event.
+     */
+    calculateBufferType(isInitialBuffering: boolean): string;
+    /**
+     * Augments view count. This will be called with each *_START and *_END.
+     */
+    goViewCountUp(): void;
+    /**
+     * Checks flags and changes state.
+     * @returns {boolean} True if the state changed.
+     */
+    goPlayerReady(): boolean;
+    /**
+     * Checks flags and changes state
+     * @returns {boolean} True if the state changed.
+     */
+    goRequest(): boolean;
+    /**
+     * Checks flags and changes state
+     * @returns {boolean} True if the state changed.
+     */
+    goStart(): boolean;
+    /**
+     * Checks flags and changes state
+     * @returns {boolean} True if the state changed.
+     */
+    goEnd(): boolean;
+    /**
+     * Checks flags and changes state
+     * @returns {boolean} True if the state changed.
+     */
+    goPause(): boolean;
+    /**
+     * Checks flags and changes state
+     * @returns {boolean} True if the state changed.
+     */
+    goResume(): boolean;
+    /**
+     * Checks flags and changes state
+     * @returns {boolean} True if the state changed.
+     */
+    goBufferStart(): boolean;
+    /**
+     * Checks flags and changes state
+     * @returns {boolean} True if the state changed.
+     */
+    goBufferEnd(): boolean;
+    /**
+     * Checks flags and changes state
+     * @returns {boolean} True if the state changed.
+     */
+    goSeekStart(): boolean;
+    /**
+     * Checks flags and changes state
+     * @returns {boolean} True if the state changed.
+     */
+    goSeekEnd(): boolean;
+    /**
+     * Checks flags and changes state
+     * @returns {boolean} True if the state changed.
+     */
+    goAdBreakStart(): boolean;
+    /**
+     * Checks flags and changes state
+     * @returns {boolean} True if the state changed.
+     */
+    goAdBreakEnd(): boolean;
+    /**
+     * Restarts download chrono.
+     */
+    goDownload(): void;
+    /**
+     * Restarts heartbeat chrono.
+     */
+    goHeartbeat(): void;
+    /**
+     * Restarts rendition change chrono.
+     */
+    goRenditionChange(): void;
+    /**
+     * Restarts ad quartile chrono.
+     */
+    goAdQuartile(): void;
+    /**
+     * Increments error counter and starts appropriate error timer.
+     */
+    goError(): void;
+    /**
+     * Restarts last ad chrono.
+     */
+    goLastAd(): void;
+    /**
+     * Updates peak bitrate and time-weighted average bitrate (content only).
+     * @param {number} bitrate Current content bitrate in bps.
+     */
+    trackContentBitrateState(bitrate: number): void;
+    /**
+     * Records network download bitrate observation. Only tracks values that differ from previous.
+     * @param {number} bps Network throughput in bits per second.
+     */
+    trackDownloadRate(bps: number): void;
+    /**
+     * Records a rendition play event (height x width combination).
+     * @param {number} height Rendition height in pixels.
+     * @param {number} width Rendition width in pixels.
+     */
+    addPlayedRendition(height: number, width: number): void;
+    /**
+     * Resets tracked variable for view id change
+     * */
+    resetViewIdTrackedState(): void;
+    /** Methods to manage total ads time chrono */
+    clearTotalAdsTime(): void;
+    totalAdTime(): number;
+    startAdsTime(): void;
+    stopAdsTime(): number | null;
+    setStartupTime(totalAdTime: number): void;
+}
+export default VideoTrackerState;