Shoppable videos (Alpha)

You can use shoppable videos to define a set of products that appear in your videos and display product images alongside in a product bar. This allows your users to visit your product detail pages and make a purchase.

Important
Shoppable video functionality is currently in Alpha. Some implementation details are likely to change. We invite you to try it out and share any feedback via our support team.

Adding Shoppable video functionality

Shoppable video functionality is included in the standard video player package.

You can add Shoppable video functionality to your video source using the shoppable parameter. The shoppable parameter is an object containing all the shoppable video configuration. This can be broken down into two sections:

  1. Configuration for the shoppable UI and functionality.
  2. The products array which contains the configuration for the products listed and any video hotspots you want to include.

Here's a simple example of the shoppable configuration for the "ShoppableDemoVideo" player source:

Copy to clipboard
var source = {
    shoppable: {    
        transformation: {
            crop: "pad",
            aspect_ratio: "1"
        },
        products: [
        {
            productId: 1,
            productName: "Sunglasses",
            startTime: 0,
            endTime: 2,
            publicId:
            "docs/shoppable_sunglasses",
            hotspots: [
            {
                time: "00:02",
                x: "50%",
                y: "50%",
                tooltipPosition: "left",
                clickUrl: "https://slo-fashion.com/"
            }
            ],
            onHover: {
            action: "overlay",
            args: "Click to see this product in the video"
            },
            onClick: {
            action: "seek",
            pause: 5,
            args: {
                time: "00:01"
                }
            }
        },
        {
            productId: 2,
            productName: "Green Dress",
            startTime: 2,
            endTime: 5,
            publicId: "docs/shoppable_dress",
            onClick: {
            action: "goto",
            pause: true,
            args: {
                url: "https://slo-fashion.com/"
                }
            }
        },
        {
            productId: 3,
            productName: "Brown Bag",
            startTime: 7,
            endTime: 11,
            publicId:
            "docs/shoppable_bag",
            onHover: {
            action: "switch",
            args: {
                publicId:
                "docs/shoppable_bag2"
                }
            },
            onClick: {
            action: "goto",
            pause: true,
            args: {
                url:
                "https://slo-fashion.com/"
                }
            }
        }
        ]
    }
}

player.source("docs/shoppable_demo", source)

Configuring the shoppable UI

The shoppable object supports a number of properties to configure the shoppable video component look and feel. This allows you to customize the shoppable component of the video player to match your brand and also to standardize all of your product images. See video player customization for more information on how to customize the player as a whole.

  • Set the products bar startState as well as the icon used to toggle it (toggleIcon) and the width once open. You can also configure how long you want the bar to stay open for using the autoClose property.
  • Define any transformations that are applied to all of the product images in the products bar. You can use this to standardize the size, format and quality or add brand overlays and effects.
  • Set the message to display before the video starts (bannerMsg) and whether to show a product carousel overlay once the video has finished playing (showPostPlayOverlay).

Here's an example of configuring the clothes example to better match the brand:

Copy to clipboard
shoppable: {
    startState: "openOnPlay",
    autoClose: 2,
    showPostPlayOverlay: true,
    width: "15%",
    bannerMsg: "Start shopping for your outfit",
    toggleIcon:
    "https://res.cloudinary.com/demo/image/upload/docs/trolley",
    transformation: {
    quality: "auto:eco",
    fetch_format: "auto",
    crop: "pad",
    aspect_ratio: "1"
    },
    products: [ /*products array*/ ]

Defining products

You can define all of the products you want to appear in the products bar using the products array. For each product you need to specify the relevant information:

  • Set the productId and productName of the product as well as the publicId of the product image to show.
  • Set the startTime and endtime for when the product appears in video.
  • Define what happens when a user interacts with the product in products bar. You can configure onClick and onHover behavior (available options are different for each).
  • Define your hotspots for the video. This allows you to add a clickable hotspot for a product on the video itself. You can use this to highlight the location of the product in the frame.

For example, using the sunglasses from the example above:

Copy to clipboard
{
    productId: 1,
    productName: "Sunglasses",
    startTime: 0,
    endTime: 2,
    publicId:
    "docs/shoppable_sunglasses",
    hotspots: [
    {
        time: "00:02",
        x: "50%",
        y: "50%",
        tooltipPosition: "left",
        clickUrl: "https://slo-fashion.com/"
    }
    ],
    onHover: {
    action: "overlay",
    args: "Click to see this product in the video"
    },
    onClick: {
    action: "seek",
    pause: 5,
    args: {
        time: "00:01"
        }
    }
}

Reference

Properties

ShoppableProps

Param Type Description
autoClose Number (in seconds) The length of time in seconds, after there's no interaction that the products bar automatically closes. Default: 2.
bannerMsg String The message displayed alongside the play button when the video first loads. Default: Shop the Video.
products Array of Products The list of products to show in the products bar and the configuration for each.
showPostPlayOverlay Boolean Whether to show a product carousel overlay after the video has finished. Default: false.
startState StartState The state of the product bar when the video loads. Default: openOnPlay.
toggleIcon String URL The URL of the icon used to toggle the product bar.
transformation cloudinary.Transformation, Object, Array, or String Transformations to apply to all product images shown in the product bar. Default: {"quality": "auto", "width": "auto", "fetch_format": "auto", "crop": "scale"}.
width String Percentage The width of the product bar as a percentage of the total width of the player. Default: 20%.

ProductsProps

Param Type Description
hotspots Array of Hotspots The hotspots on the video for this product. Allows the user to click in a certain location and at a certain time to take them to the product description page.
onClick OnClickProps The behavior when the user clicks on the product.
onHover OnHoverProps The behavior when the user hovers over the product.
productId Number The ID of the product.
productName String The name of the product.
publicId String The public ID of the product image.
startTime String The start time (in seconds) where the product appears in the video. Used to highlight the product in the bar while visible in the video.
endTime String The end time (in seconds) where the product no longer appears in the video.

HotspotProps

Param Type Description
clickUrl String URL The URL for the user to visit when clicking the hotspot.
time String (mm:ss) The exact time to display the hotspot.
tooltipPosition TooltipPosition The position of the hotspot tooltip displaying product information.
x String Percentage The X coordinate for positioning the hotspot.
y String Percentage The Y coordinate for positioning the hotspot.

OnHoverProps

Param Type Description
action OnHoverAction The action to perform when hovering over the product in the product bar.
args String or publicId If action is set to overlay, the text string to overlay.
If action is set to switch, an object setting the publicId of the image to switch to, for example {"publicId": "different_product_image"}

OnClickProps

Param Type Description
action OnClickAction The action to perform when clicking on the product in the product bar.
args OnClickArgsProps The arguments to configure the action.
pause Boolean or Number (seconds) Whether to pause the video or a number of seconds to pause the video for. Relevant when action is set to seek.

OnClickArgsProps

Param Type Description
time String (mm:ss) The time to seek the video to. Relevant when action is set to seek.
url String URL The URL to navigate the user to. Relevant when action is set to goto.

Enums

StartState

A string value setting the state of the product bar when the video loads.

Value Description
closed The product bar is closed when the video loads.
open The product bar is open when the video loads.
openOnPlay Opens the product bar when the play button is clicked. Default.

TooltipPosition

A string value setting the position of the hotspot tooltip.

Value Description
top Positions the tooltip above the hotspot.
bottom Positions the tooltip below the hotspot.
left Positions the tooltip to the left of the hotspot.
right Positions the tooltip to the right of the hotspot.

OnHoverAction

A string value setting the action to perform when a user hovers over the product.

Value Description
overlay Overlays text on the product image.
switch Switches the product image for a different one.

OnClickAction

A string value setting the action to perform when a user clicks on the product.

Value Description
goto Opens a URL in a new tab.
seek Jumps to a specific position in the video (and optionally shows a hotspot).

Events

Event Description
productHover Triggered when a user hovers over a product in the products bar.
productClick Triggered when a user clicks on a product in the products bar.
productBarMin Triggered when the products bar is minimized.
productBarMax Triggered when the products bar is maximized.
productHoverPost Triggered when a user hovers over a product in the post-play overlay.
productClickPost Triggered when a user clicks on a product in the post-play overlay.
replay Triggered when the video is replayed.