Add API to switch UI variants

[protyposis]

Currently it is possible to define different UI variants that are switched according to criteria provided by the UIConditionContext object when certain player events happen. This means it is only possible to set the criteria for certain UI variants at setup, but switching is done autonomously and internally in the UIManager without any means to interfere from outside. Desired is an API that also allows to trigger switching from outside at any desired time.

The UIConditionContext upon which the target UI variant is evaluated:

bitmovin-player-ui/src/ts/uimanager.ts

Lines 80 to 118 in d8a6978

	/**
	* The context that will be passed to a {@link UIConditionResolver} to determine if it's conditions fulfil the context.
	*/
	export interface UIConditionContext {
	/**
	* Tells if the player is loading or playing an ad.
	*/
	isAd: boolean;
	/**
	* Tells if the ad allows a UI. This is currently only true for VAST ads and cannot be used to differentiate between
	* different ad clients (i.e. to display different UIs for different ad clients).
	* @deprecated Will be removed in an upcoming major release, use {@link #adClientType} instead.
	*/
	isAdWithUI: boolean;
	/**
	* Tells the ad client (e.g. 'vast, 'ima') if {@link #isAd} is true.
	*/
	adClientType: string;
	/**
	* Tells if the player is currently in fullscreen mode.
	*/
	isFullscreen: boolean;
	/**
	* Tells if the UI is running in a mobile browser.
	*/
	isMobile: boolean;
	/**
	* Tells if the player is in playing or paused state.
	*/
	isPlaying: boolean;
	/**
	* The width of the player/UI element.
	*/
	width: number;
	/**
	* The width of the document where the player/UI is embedded in.
	*/
	documentWidth: number;
	}

Example UI variants and criteria setup:

bitmovin-player-ui/src/ts/uimanager.ts

Lines 654 to 672 in d8a6978

	return new UIManager(player, [{
	ui: modernSmallScreenAdsUI(),
	condition: (context: UIConditionContext) => {
	return context.isMobile && context.documentWidth < smallScreenSwitchWidth && context.isAdWithUI;
	},
	}, {
	ui: modernAdsUI(),
	condition: (context: UIConditionContext) => {
	return context.isAdWithUI;
	},
	}, {
	ui: modernSmallScreenUI(),
	condition: (context: UIConditionContext) => {
	return context.isMobile && context.documentWidth < smallScreenSwitchWidth;
	},
	}, {
	ui: modernUI(),
	}], config);
	}

The events that trigger the evaluation of the context and potentially switch the UI variant:

bitmovin-player-ui/src/ts/uimanager.ts

Lines 339 to 349 in d8a6978

	// Listen to the following events to trigger UI variant resolution
	this.managerPlayerWrapper.getPlayer().addEventHandler(this.player.EVENT.ON_READY, resolveUiVariant);
	this.managerPlayerWrapper.getPlayer().addEventHandler(this.player.EVENT.ON_PLAY, resolveUiVariant);
	this.managerPlayerWrapper.getPlayer().addEventHandler(this.player.EVENT.ON_PAUSED, resolveUiVariant);
	this.managerPlayerWrapper.getPlayer().addEventHandler(this.player.EVENT.ON_AD_STARTED, resolveUiVariant);
	this.managerPlayerWrapper.getPlayer().addEventHandler(this.player.EVENT.ON_AD_FINISHED, resolveUiVariant);
	this.managerPlayerWrapper.getPlayer().addEventHandler(this.player.EVENT.ON_AD_SKIPPED, resolveUiVariant);
	this.managerPlayerWrapper.getPlayer().addEventHandler(this.player.EVENT.ON_AD_ERROR, resolveUiVariant);
	this.managerPlayerWrapper.getPlayer().addEventHandler(this.player.EVENT.ON_PLAYER_RESIZE, resolveUiVariant);
	this.managerPlayerWrapper.getPlayer().addEventHandler(this.player.EVENT.ON_FULLSCREEN_ENTER, resolveUiVariant);
	this.managerPlayerWrapper.getPlayer().addEventHandler(this.player.EVENT.ON_FULLSCREEN_EXIT, resolveUiVariant);

[protyposis]

Since the UI variants do not have distinct IDs, it is not possible to directly switch to a specific variant, e.g. uimanager.switchToVariant(UIVariant.Ads). The API will thus somehow have to work with the UIConditionContext and allow setting the conditions so the switching code evaluates to the desired UI variant.

[protyposis]

Since the UI variants do not have distinct IDs, it is not possible to directly switch to a specific variant

Solved by using variant references.

[protyposis]

Released in 2.15.0