Integrating Pinning with Brightcove Web & Smart TV SDK

Overview

The Pinning integration allows viewers to pin videos on the screen, ensuring that the video player stays visible while users scroll through the rest of the page. This enhances the user experience by allowing continuous viewing without interruption.

Prerequisites

A Brightcove account with access to Video Cloud.
The Brightcove Web & Smart TV SDK installed in your project.

Usage Example

Import the Player (with UI) class from the Brightcove SDK.

import { Player, IntegrationsManager } from '@brightcove/web-sdk/ui';

Import the Pinning integration class from the Brightcove SDK.

import { PinningIntegrationFactory } from '@brightcove/web-sdk/integrations/pinning';

Import the Pinning integration CSS from the Brightcove SDK.

import '@brightcove/web-sdk/integrations/pinning/styles';

Register the Pinning Integration Factory with the Integrations Manager.

IntegrationsManager.registerPinningIntegrationFactory(PinningIntegrationFactory);

Create and Configure the Player.

const player = new Player({ accountId: '<your-account-id>' });

 player.updateConfiguration({
   integrations: {
       pinning: {
           posX: 'left', 
           posY: 'top',  
           closeable: true, 
           // Add any other configurations as needed
       },
   },
 });

Attach the player to a mount root (DOM element in the page):

const root = document.querySelector('#player-mount-root');
 player.attach(root);

Access the Pinning Integration API via the Integrations Manager.

const { pinningIntegration } = player.getIntegrationsManager();

Call Pinning-specific method.

pinningIntegration.togglePinning(); // Example method to toggle pinning

Configuration Summary

This section provides detailed information about the various configuration options available for Pinning when using the Web & Smart TV SDK.

Configuration Option	Type	Default	Description
`allowOnMobile`	boolean	false	By default, pinning mode will not work on Android or iOS mobile devices.
`closeable`	boolean	true	By default, pinning mode will include a close button, which the user can click to disable pinning mode.
`height`	number \| null	null	By default, the plugin will scale down the player's dimensions by a factor determined by the `scale` option. However, providing a `height` (or `width`) will override the default scaling and set the size of the scaled-down player explicitly. If only one dimension is provided, the other will be scaled down to maintain the aspect ratio. If both dimensions are provided, the player will be set to the exact, specified size.
`width`	number \| null	null	By default, the plugin will scale down the player's dimensions by a factor determined by the `scale` option. However, providing a `width` (or `height`) will override the default scaling and set the size of the scaled-down player explicitly.
`scale`	number	2/3	The scaling factor applied to the player when it is in pinning mode. Must be a number greater than `0` and less than or equal to `1`.
`manualContainerSize`	boolean	false	By default, a player with this plugin enabled will keep the physical dimensions of the special container element in sync with the player's dimensions. However, this doesn't work for all cases, so it can be disabled by setting this option to `false`. When doing so, the container element will behave like a normal block element. This means that users of the plugin will need to manage its size on their own.
`posX`	'right' \| 'left'	right	The horizontal alignment of the player when it is in pinning mode.
`posY`	'top' \| 'bottom'	bottom	The vertical alignment of the player when it is in pinning mode.
`viewable`	number	0.8	The threshold at which the player is considered viewable. In other words, when this percentage of the player is visible in the browser's viewport, it is considered viewable. For example, with the default of `0.8`, the player is not considered viewable unless 80% of it is visible in the viewport. Must be a number greater than or equal to `0` or less than or equal to `1`.

Public Methods Summary

Method	Description	Parameters	Parameter Type	Returns
`togglePinning`	Activate or deactivate pinning mode based on the current state.	None	N/A	void

Event Summary

Event Name	Attribute	Description
`BeforePin`	Readonly	Triggered just before a pin action is performed.
`BeforePinClose`	Readonly	Triggered just before a pin close action is performed.
`BeforePinningDisabled`	Readonly	Triggered just before pinning is disabled.
`BeforePinningEnabled`	Readonly	Triggered just before pinning is enabled.
`BeforeUnpin`	Readonly	Triggered just before an unpin action is performed.
`Pin`	Readonly	Triggered when a pin action is performed.
`PinClose`	Readonly	Triggered when a pin close action is performed.
`PinningDisabled`	Readonly	Triggered when pinning is disabled.
`PinningEnabled`	Readonly	Triggered when pinning is enabled.
`Unpin`	Readonly	Triggered when an unpin action is performed.