bitmovin-player-react-native 0.4.0 → 0.5.0

package/lib/index.d.ts

@@ -148,6 +148,300 @@ interface AdBreak {
     scheduleTime: number;
 }
 
+interface NativeInstanceConfig {
+    /**
+     * Optionally user-defined string `id` for the native instance.
+     * Used to access a certain native instance from any point in the source code then call
+     * methods/properties on it.
+     *
+     * When left empty, a random `UUIDv4` is generated for it.
+     * @example
+     * Accessing or creating the `Player` with `nativeId` equal to `my-player`:
+     * ```
+     * const player = new Player({ nativeId: 'my-player' })
+     * player.play(); // call methods and properties...
+     * ```
+     */
+    nativeId?: string;
+}
+declare abstract class NativeInstance<Config extends NativeInstanceConfig> {
+    /**
+     * Optionally user-defined string `id` for the native instance, or UUIDv4.
+     */
+    readonly nativeId: string;
+    /**
+     * The configuration object used to initialize this instance.
+     */
+    readonly config?: Config;
+    /**
+     * Generate UUID in case the user-defined `nativeId` is empty.
+     */
+    constructor(config?: Config);
+    /**
+     * Flag indicating whether the native resources of this object have been created internally
+     * .i.e `initialize` has been called.
+     */
+    abstract isInitialized: boolean;
+    /**
+     * Create the native object/resources that will be managed by this instance.
+     */
+    abstract initialize(): void;
+    /**
+     * Flag indicating whether the native resources of this object have been disposed .i.e
+     * `destroy` has been called.
+     */
+    abstract isDestroyed: boolean;
+    /**
+     * Dispose the native object/resources created by this instance during `initialize`.
+     */
+    abstract destroy(): void;
+}
+
+/**
+ * Available cdn provider options for AnalyticsConfig.
+ */
+declare enum CdnProvider {
+    BITMOVIN = "bitmovin",
+    AKAMAI = "akamai",
+    FASTLY = "fastly",
+    MAXCDN = "maxcdn",
+    CLOUDFRONT = "cloudfront",
+    CHINACACHE = "chinacache",
+    BITGRAVITY = "bitgravity"
+}
+/**
+ * Object used to configure a new `AnalyticsCollector` instance.
+ */
+interface AnalyticsConfig extends NativeInstanceConfig, CustomDataConfig {
+    /**
+     * CDN Provide that the video playback session is using.
+     */
+    cdnProvider?: CdnProvider;
+    /**
+     * User ID of the customer.
+     */
+    customUserId?: string;
+    /**
+     * Experiment name needed for A/B testing.
+     */
+    experimentName?: string;
+    /**
+     * ID of the video in the CMS system.
+     */
+    videoId?: string;
+    /**
+     * Human readable title of the video asset currently playing.
+     */
+    title?: string;
+    /**
+     * Analytics key.
+     */
+    key: string;
+    /**
+     * Player key.
+     */
+    playerKey?: string;
+    /**
+     * Breadcrumb path to show where in the app the user is.
+     */
+    path?: string;
+    /**
+     * Flag to see if stream is live before stream metadata is available (default: false).
+     */
+    isLive?: boolean;
+    /**
+     * Flag to enable Ad tracking (default: false).
+     */
+    ads?: boolean;
+    /**
+     * Flag to use randomised userId not depending on device specific values (default: false).
+     */
+    randomizeUserId?: boolean;
+}
+interface CustomDataConfig {
+    /**
+     * Optional free-form custom data
+     */
+    customData1?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData2?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData3?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData4?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData5?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData6?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData7?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData8?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData9?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData10?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData11?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData12?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData13?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData14?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData15?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData16?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData17?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData18?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData19?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData20?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData21?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData22?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData23?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData24?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData25?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData26?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData27?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData28?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData29?: string;
+    /**
+     * Optional free-form custom data
+     */
+    customData30?: string;
+}
+
+/**
+ * Analytics collector that can be attached to a player object in order to collect and send
+ * its analytics information.
+ */
+declare class AnalyticsCollector extends NativeInstance<AnalyticsConfig> {
+    /**
+     * Whether the native `AnalyticsCollector` object has been created.
+     */
+    isInitialized: boolean;
+    /**
+     * Whether the native `AnalyticsCollector` object has been disposed.
+     */
+    isDestroyed: boolean;
+    /**
+     * Initializes a native `BitmovinPlayerCollector` object.
+     */
+    initialize: () => void;
+    /**
+     * Disposes the native `BitmovinPlayerCollector` object that has been created
+     * during initialization.
+     */
+    destroy: () => void;
+    /**
+     * Attach a player instance to this analytics plugin. After this is completed, BitmovinAnalytics
+     * will start monitoring and sending analytics data based on the attached player instance.
+     *
+     * @param playerId - Native Id of the player to attach this collector instance.
+     */
+    attach: (playerId: string) => void;
+    /**
+     * Detach a player instance from this analytics plugin if there's any attached. If no player is attached,
+     * nothing happens.
+     */
+    detach: () => void;
+    /**
+     * Dynamically updates analytics custom data information. Use this method
+     * to update your custom data during runtime.
+     *
+     * @param customData - Analytics custom data config.
+     */
+    setCustomDataOnce: (customData: CustomDataConfig) => void;
+    /**
+     * Sets the internal analytics custom data state.
+     *
+     * @param customData - Analytics custom data config.
+     */
+    setCustomData: (customData: CustomDataConfig) => void;
+    /**
+     * Gets the current custom data config from the native `BitmovinPlayerCollector` instance.
+     *
+     * @returns The current custom data config.
+     */
+    getCustomData: () => Promise<CustomDataConfig>;
+    /**
+     * Gets the current user id used by the native `BitmovinPlayerCollector` instance.
+     *
+     * @returns The current user id.
+     */
+    getUserId: () => Promise<string>;
+}
+
 /**
  * An audio session category defines a set of audio behaviors.
  * Choose a category that most accurately describes the audio behavior you require.
@@ -250,6 +544,40 @@ interface SubtitleTrack {
  */
 declare type SideLoadedSubtitleTrack = MakeRequired<SubtitleTrack, 'url' | 'label' | 'language' | 'format'>;
 
+/**
+ * Quality definition of a video representation.
+ */
+interface VideoQuality {
+    /**
+     * The id of the media quality.
+     */
+    id: string;
+    /**
+     * The label of the media quality that should be exposed to the user.
+     */
+    label?: string;
+    /**
+     * The bitrate of the media quality.
+     */
+    bitrate?: number;
+    /**
+     * The codec of the media quality.
+     */
+    codec?: string;
+    /**
+     * The frame rate of the video quality. If the frame rate is not known or not applicable a value of -1 will be returned.
+     */
+    frameRate?: number;
+    /**
+     * The height of the video quality.
+     */
+    height?: number;
+    /**
+     * The width of the video quality.
+     */
+    width?: number;
+}
+
 /**
  * Base event type for all events.
  */
@@ -518,6 +846,34 @@ interface PictureInPictureEnteredEvent extends Event {
  */
 interface PictureInPictureExitedEvent extends Event {
 }
+/**
+ * Emitted when the fullscreen functionality has been enabled.
+ *
+ * @platform iOS, Android
+ */
+interface FullscreenEnabledEvent extends Event {
+}
+/**
+ * Emitted when the fullscreen functionality has been disabled.
+ *
+ * @platform iOS, Android
+ */
+interface FullscreenDisabledEvent extends Event {
+}
+/**
+ * Emitted when the player enters fullscreen mode.
+ *
+ * @platform iOS, Android
+ */
+interface FullscreenEnterEvent extends Event {
+}
+/**
+ * Emitted when the player exits fullscreen mode.
+ *
+ * @platform iOS, Android
+ */
+interface FullscreenExitEvent extends Event {
+}
 /**
  * Emitted when the availability of the Picture in Picture mode changed on Android.
  *
@@ -672,6 +1028,19 @@ interface AdManifestLoadedEvent extends Event {
      */
     downloadTime: number;
 }
+/**
+ * Emitted when the current video playback quality has changed.
+ */
+interface VideoPlaybackQualityChangedEvent extends Event {
+    /**
+     * The new quality
+     */
+    newVideoQuality: VideoQuality;
+    /**
+     * The previous quality
+     */
+    oldVideoQuality: VideoQuality;
+}
 
 /**
  * Type that defines all event props supported by `PlayerView` and `NativePlayerView`.
@@ -691,6 +1060,10 @@ interface EventProps {
     onAdStarted: AdStartedEvent;
     onDestroy: DestroyEvent;
     onEvent: Event;
+    onFullscreenEnabled: FullscreenEnabledEvent;
+    onFullscreenDisabled: FullscreenDisabledEvent;
+    onFullscreenEnter: FullscreenEnterEvent;
+    onFullscreenExit: FullscreenExitEvent;
     onMuted: MutedEvent;
     onPaused: PausedEvent;
     onPictureInPictureAvailabilityChanged: PictureInPictureAvailabilityChangedEvent;
@@ -719,6 +1092,7 @@ interface EventProps {
     onSubtitleRemoved: SubtitleRemovedEvent;
     onTimeChanged: TimeChangedEvent;
     onUnmuted: UnmutedEvent;
+    onVideoPlaybackQualityChanged: VideoPlaybackQualityChangedEvent;
 }
 /**
  * Event props for `PlayerView`.
@@ -730,55 +1104,6 @@ declare type PlayerViewEvents = {
     [Prop in keyof EventProps]?: (event: EventProps[Prop]) => void;
 };
 
-interface NativeInstanceConfig {
-    /**
-     * Optionally user-defined string `id` for the native instance.
-     * Used to access a certain native instance from any point in the source code then call
-     * methods/properties on it.
-     *
-     * When left empty, a random `UUIDv4` is generated for it.
-     * @example
-     * Accessing or creating the `Player` with `nativeId` equal to `my-player`:
-     * ```
-     * const player = new Player({ nativeId: 'my-player' })
-     * player.play(); // call methods and properties...
-     * ```
-     */
-    nativeId?: string;
-}
-declare abstract class NativeInstance<Config extends NativeInstanceConfig> {
-    /**
-     * Optionally user-defined string `id` for the native instance, or UUIDv4.
-     */
-    readonly nativeId: string;
-    /**
-     * The configuration object used to initialize this instance.
-     */
-    readonly config?: Config;
-    /**
-     * Generate UUID in case the user-defined `nativeId` is empty.
-     */
-    constructor(config?: Config);
-    /**
-     * Flag indicating whether the native resources of this object have been created internally
-     * .i.e `initialize` has been called.
-     */
-    abstract isInitialized: boolean;
-    /**
-     * Create the native object/resources that will be managed by this instance.
-     */
-    abstract initialize(): void;
-    /**
-     * Flag indicating whether the native resources of this object have been disposed .i.e
-     * `destroy` has been called.
-     */
-    abstract isDestroyed: boolean;
-    /**
-     * Dispose the native object/resources created by this instance during `initialize`.
-     */
-    abstract destroy(): void;
-}
-
 /**
  * Represents a FairPlay Streaming DRM config.
  */
@@ -1077,6 +1402,10 @@ interface SourceConfig extends NativeInstanceConfig {
      * External subtitle tracks to be added into the player.
      */
     subtitleTracks?: SideLoadedSubtitleTrack[];
+    /**
+     * External thumbnails to be added into the player.
+     */
+    thumbnailTrack?: string;
 }
 /**
  * Represents audio and video content that can be loaded into a player.
@@ -1131,6 +1460,93 @@ declare class Source extends NativeInstance<SourceConfig> {
     loadingState: () => Promise<LoadingState>;
 }
 
+/**
+ * Contains config values which can be used to alter the visual presentation and behaviour of the player UI.
+ */
+interface StyleConfig {
+    /**
+     * Sets if the UI should be enabled or not. Default value is true.
+     * @example
+     * ```
+     * const player = new Player({
+     *   styleConfig: {
+     *     isUiEnabled: false,
+     *   },
+     * });
+     * ```
+     */
+    isUiEnabled?: boolean;
+    /**
+     * Set the CSS file that will be used for the UI. The default CSS file will be completely replaced by the CSS file set with this property.
+     * @example
+     * ```
+     * const player = new Player({
+     *   styleConfig: {
+     *     playerUiCss: 'https://domain.tld/path/to/bitmovinplayer-ui.css',
+     *   },
+     * });
+     * ```
+     * @platform iOS, Android
+     */
+    playerUiCss?: string;
+    /**
+     * Set a CSS file which contains supplemental styles for the player UI. These styles will be added to the default CSS file or the CSS file set with StyleConfig#playerUiCss.
+     * @example
+     * ```
+     * const player = new Player({
+     *   styleConfig: {
+     *     supplementalPlayerUiCss: 'https://domain.tld/path/to/bitmovinplayer-supplemental-ui.css',
+     *   },
+     * });
+     * ```
+     * @platform iOS, Android
+     */
+    supplementalPlayerUiCss?: string;
+    /**
+     * Sets the JS file that will be used for the UI. The default JS file will be completely replaced by the JS file set with this property.
+     * @example
+     * ```
+     * const player = new Player({
+     *   styleConfig: {
+     *     playerUiJs: 'https://domain.tld/path/to/bitmovinplayer-ui.js',
+     *   },
+     * });
+     * ```
+     * @platform iOS, Android
+     */
+    playerUiJs?: string;
+    /**
+     * Determines how the video content is scaled or stretched within the parent container’s bounds.  Possible values are defined in ScalingMode.
+     * Default value is ScalingMode.fit.
+     * @example
+     * ```
+     * const player = new Player({
+     *   styleConfig: {
+     *     scalingMode: ScalingMode.Zoom,
+     *   },
+     * });
+     * ```
+     */
+    scalingMode?: ScalingMode;
+}
+/**
+ * Specifies how the video content is scaled or stretched.
+ */
+declare enum ScalingMode {
+    /**
+     * Specifies that the player should preserve the video’s aspect ratio and fit the video within the container's bounds.
+     */
+    Fit = "Fit",
+    /**
+     * Specifies that the video should be stretched to fill the container’s bounds. The aspect ratio may not be preserved.
+     */
+    Stretch = "Stretch",
+    /**
+     * Specifies that the player should preserve the video’s aspect ratio and fill the container’s bounds.
+     */
+    Zoom = "Zoom"
+}
+
 /**
  * This configuration is used as an incubator for experimental features. Tweaks are not officially
  * supported and are not guaranteed to be stable, i.e. their naming, functionality and API can
@@ -1312,6 +1728,10 @@ interface PlayerConfig extends NativeInstanceConfig {
      * Configures playback behaviour. A default PlaybackConfig is set initially.
      */
     playbackConfig?: PlaybackConfig;
+    /**
+     * Configures the visual presentation and behaviour of the player UI. A default StyleConfig is set initially.
+     */
+    styleConfig?: StyleConfig;
     /**
      * Configures advertising functionality. A default AdvertisingConfig is set initially.
      */
@@ -1320,6 +1740,10 @@ interface PlayerConfig extends NativeInstanceConfig {
      * Configures experimental features. A default TweaksConfig is set initially.
      */
     tweaksConfig?: TweaksConfig;
+    /**
+     * Configures analytics functionality.
+     */
+    analyticsConfig?: AnalyticsConfig;
 }
 /**
  * Configures the playback behaviour of the player.
@@ -1411,6 +1835,10 @@ declare class Player extends NativeInstance<PlayerConfig> {
      * Currently active source, or `null` if none is active.
      */
     source?: Source;
+    /**
+     * Analytics collector currently attached to this player instance.
+     */
+    analyticsCollector?: AnalyticsCollector;
     /**
      * Whether the native `Player` object has been created.
      */
@@ -1541,6 +1969,24 @@ declare class Player extends NativeInstance<PlayerConfig> {
     isAd: () => Promise<boolean>;
 }
 
+/**
+ * Handles the UI state change when fullscreen should be entered or exited.
+ */
+interface FullscreenHandler {
+    /**
+     * Indicates if the UI is currently in fullscreen mode
+     */
+    isFullscreenActive: boolean;
+    /**
+     * Is called by the `PlayerView` when the UI should enter fullscreen mode.
+     */
+    enterFullscreen(): void;
+    /**
+     * Is called by the `PlayerView` when the UI should exit fullscreen mode.
+     */
+    exitFullscreen(): void;
+}
+
 /**
  * Base `PlayerView` component props. Used to stablish common
  * props between `NativePlayerView` and `PlayerView`.
@@ -1559,12 +2005,13 @@ interface PlayerViewProps extends BasePlayerViewProps, PlayerViewEvents {
      * and render audio/video inside the `PlayerView`.
      */
     player: Player;
+    fullscreenHandler?: FullscreenHandler;
 }
 /**
  * Component that provides the Bitmovin Player UI and default UI handling to an attached `Player` instance.
  * This component needs a `Player` instance to work properly so make sure one is passed to it as a prop.
  */
-declare function PlayerView({ style, player, ...props }: PlayerViewProps): JSX.Element;
+declare function PlayerView({ style, player, fullscreenHandler, ...props }: PlayerViewProps): JSX.Element;
 
 /**
  * React hook that creates and returns a reference to a `Player` instance
@@ -1572,4 +2019,4 @@ declare function PlayerView({ style, player, ...props }: PlayerViewProps): JSX.E
  */
 declare function usePlayer(config?: PlayerConfig): Player;
 
-export { Ad, AdBreak, AdBreakFinishedEvent, AdBreakStartedEvent, AdClickedEvent, AdConfig, AdData, AdErrorEvent, AdFinishedEvent, AdItem, AdManifestLoadEvent, AdManifestLoadedEvent, AdQuartile, AdQuartileEvent, AdScheduledEvent, AdSkippedEvent, AdSource, AdSourceType, AdStartedEvent, AdvertisingConfig, AudioSession, AudioSessionCategory, BasePlayerViewProps, DestroyEvent, Drm, DrmConfig, ErrorEvent, Event, EventSource, FairplayConfig, LoadingState, MutedEvent, PausedEvent, PictureInPictureAvailabilityChangedEvent, PictureInPictureEnterEvent, PictureInPictureEnteredEvent, PictureInPictureExitEvent, PictureInPictureExitedEvent, PlayEvent, PlaybackConfig, PlaybackFinishedEvent, Player, PlayerActiveEvent, PlayerConfig, PlayerErrorEvent, PlayerView, PlayerViewProps, PlayerWarningEvent, PlayingEvent, ReadyEvent, SeekEvent, SeekedEvent, SideLoadedSubtitleTrack, Source, SourceConfig, SourceErrorEvent, SourceLoadEvent, SourceLoadedEvent, SourceType, SourceUnloadedEvent, SourceWarningEvent, StallEndedEvent, StallStartedEvent, SubtitleAddedEvent, SubtitleChangedEvent, SubtitleFormat, SubtitleRemovedEvent, SubtitleTrack, TimeChangedEvent, UnmutedEvent, WidevineConfig, usePlayer };
+export { Ad, AdBreak, AdBreakFinishedEvent, AdBreakStartedEvent, AdClickedEvent, AdConfig, AdData, AdErrorEvent, AdFinishedEvent, AdItem, AdManifestLoadEvent, AdManifestLoadedEvent, AdQuartile, AdQuartileEvent, AdScheduledEvent, AdSkippedEvent, AdSource, AdSourceType, AdStartedEvent, AdvertisingConfig, AnalyticsCollector, AnalyticsConfig, AudioSession, AudioSessionCategory, BasePlayerViewProps, CdnProvider, CustomDataConfig, DestroyEvent, Drm, DrmConfig, ErrorEvent, Event, EventSource, FairplayConfig, FullscreenDisabledEvent, FullscreenEnabledEvent, FullscreenEnterEvent, FullscreenExitEvent, LoadingState, MutedEvent, PausedEvent, PictureInPictureAvailabilityChangedEvent, PictureInPictureEnterEvent, PictureInPictureEnteredEvent, PictureInPictureExitEvent, PictureInPictureExitedEvent, PlayEvent, PlaybackConfig, PlaybackFinishedEvent, Player, PlayerActiveEvent, PlayerConfig, PlayerErrorEvent, PlayerView, PlayerViewProps, PlayerWarningEvent, PlayingEvent, ReadyEvent, ScalingMode, SeekEvent, SeekedEvent, SideLoadedSubtitleTrack, Source, SourceConfig, SourceErrorEvent, SourceLoadEvent, SourceLoadedEvent, SourceType, SourceUnloadedEvent, SourceWarningEvent, StallEndedEvent, StallStartedEvent, StyleConfig, SubtitleAddedEvent, SubtitleChangedEvent, SubtitleFormat, SubtitleRemovedEvent, SubtitleTrack, TimeChangedEvent, UnmutedEvent, VideoPlaybackQualityChangedEvent, WidevineConfig, usePlayer };