Add shoppable video overlays

Learn how to integrate FastPix Shoppable Video features to embed product links, configure interactive hotspots, and sync eCommerce data through API.

FastPix Player now supports shoppable video themes, giving you the ability to embed interactive shopping experiences directly inside your videos. Instead of just watching, viewers can click, explore, and even purchase products while engaging with your content.

There are two themes you can choose from, depending on the type of video experience you want to build:

• Shoppable video player - a full-featured player with a product sidebar, catalog browsing, and timeline-aware product activations.
• Shoppable shorts - a lightweight, mobile-first option optimized for single products and social video formats.

Both themes allow you to add clickable products, hotspots, and calls-to-action seamlessly. The main difference lies in how product data is configured and displayed.

Theme behavior

• shoppable-video-player expects product data passed programmatically through the addShoppableData() method. Any product-link attribute you set will be ignored.
• shoppable-shorts only uses the product-link attribute. No product data configuration is needed or processed.

Shoppable video player theme

A full, interactive shopping experience with an expandable sidebar and detailed product catalog. This theme is best suited for multi-product or long-form content where viewers can browse items while watching.

Use cases

• E-commerce showcases: Display multiple products with detailed info and links.
• Fashion & lifestyle content: Highlight clothing, accessories, or styling products with hover effects.
• Educational content: Reference books, tools, or course material mentioned in video.
• Long-form content: Manage many products across extended timelines with an organized sidebar.
• Product demos: Highlight specific items precisely at the moment they’re being demonstrated.

Shoppable shorts theme

A simplified, call-to-action driven theme for quick, single-product experiences. Designed for mobile-first and social platforms.

Use cases

• Social media shorts: Quick promos across TikTok, Instagram, YouTube Shorts.
• Mobile-first campaigns: Videos consumed primarily on phones.
• Single-product promos: Focused campaigns where one link drives conversions.
• Fast purchase flows: Low-friction buying experiences.
• Simple CTA campaigns: “Tap to shop” videos pointing to a single destination.
• Influencer marketing: Creators linking directly to sponsored products.

Theme comparison

Setting up shoppable video player

This theme is the full-featured option, designed for multi-product or catalog-style experiences. It requires a little configuration, but gives you far more control over how products are displayed and how they interact with the video timeline.

1. Basic setup

At the most basic level, you only need to include the FastPix player with the correct theme and a playback ID:

1
<fastpix-player  
2
  theme="shoppable-video-player" 
3
  playback-id="your-playback-id"> 
4
</fastpix-player> 

This creates a player with shoppable capability, but it won’t show any products yet. To make the sidebar and hotspots come alive, you’ll need to pass product data to the player.

2. Add product data

To load product information, use the addShoppableData() method. This method expects a JSON configuration that defines both sidebar behavior and the product catalog.

1
const player = document.querySelector('fastpix-player'); 
2
 
3
const cartData = { 
4
  productSidebarConfig: { 
5
    startState: "closed",        // "closed" or "openOnPlay" 
6
    autoClose: 4,               // Auto-close after 4 seconds 
7
    showPostPlayOverlay: true   // Show overlay when video ends 
8
  }, 
9
  products: [ 
10
    { 
11
      id: 1,                    // Unique product ID 
12
      name: "Product Name",     // Product display name 
13
      thumbnail: "https://example.com/product.jpg",  // Product image URL 
14
      description: "Product description",  // Optional description 
15
      startTime: 0,             // When product becomes active (seconds) 
16
      endTime: 5,               // When product becomes inactive (seconds) 
17
       
18
      // Click action configuration 
19
      onProductClick: { 
20
        type: "seek",           // "seek" or "openLink" 
21
        waitTillPause: 6,       // Wait 6 seconds then play 
22
        params: { 
23
          seekTime: 5           // Seek to 5 seconds 
24
        } 
25
      }, 
26
       
27
      // Hover action configuration 
28
      onProductHover: { 
29
        type: "overlay",        // "overlay" or "swap" 
30
        params: { 
31
          description: "Product description appears on hover" 
32
        } 
33
      }, 
34
       
35
      // Hotspot markers (optional) 
36
      markers: [ 
37
        { 
38
          x: 175,               // X position as percentage (0-100) 
39
          y: 60,                // Y position as percentage (0-100) 
40
          tooltipPosition: "left",  // "top", "bottom", "left", "right" 
41
          link: "https://store.com/product"  // URL when hotspot clicked 
42
        } 
43
      ] 
44
    } 
45
  ] 
46
}; 
47
 
48
player.addShoppableData(cartData); 
49
 

With this setup:

• The sidebar starts closed but opens when playback begins.
• Products appear only during the times you specify with startTime and endTime.
• Clicking a product either seeks the video or opens an external link, depending on configuration.
• Hovering over a product reveals extra details or swaps the product image.
• Optional hotspots can be placed directly on the video itself.

Setting up shoppable shorts

This theme is the lightweight option, optimized for single products and mobile-first consumption (e.g., TikTok, Instagram Reels). Unlike shoppable video player, it doesn’t need a product catalog. Instead, it only requires a single link.

Basic setup

Add the FastPix player with the theme set to shoppable-shorts, plus a product-link attribute. When the video plays, a cart button will automatically appear. Tapping it redirects viewers to the specified product link.

1
<fastpix-player  
2
  theme="shoppable-shorts" 
3
  product-link="https://your-store.com" 
4
  playback-id="your-playback-id"> 
5
</fastpix-player> 

PLEASE NOTE

For shoppable-shorts, only the product-link attribute is required. No additional JavaScript configuration needed.

Summary of setup differences

shoppable-video-player:

• Requires calling addShoppableData(config) with a product array.
• Supports multiple products, sidebars, overlays, hotspots, and time-based activation.
• Ignores the product-link attribute.

shoppable-shorts:

• Requires only the product-link attribute.
• Supports a single product with a clean “shop” button.
• Ignores product data configuration.

JSON structure explained

The data is structured as a JSON object with two main parts:

1. productSidebarConfig - defines how the sidebar behaves (when it opens, closes, and whether overlays appear).
2. products - an array of product objects, each representing a clickable product inside your video.

Here’s the complete structure:

1
{ 
2
  productSidebarConfig: { 
3
    startState: "closed",        // Sidebar initial state 
4
    autoClose: 4,               // Auto-close timer (seconds) 
5
    showPostPlayOverlay: true   // Show overlay when video ends 
6
  }, 
7
  products: [ 
8
    { 
9
      id: 1,                    // Product ID (number or string) 
10
      name: "Product Name",     // Product display name 
11
      thumbnail: "image-url",   // Product image URL 
12
      description: "Description", // Optional description 
13
      startTime: 0,             // Product active start time (seconds) 
14
      endTime: 5,               // Product active end time (seconds) 
15
       
16
      onProductClick: {         // Click action (optional) 
17
        type: "seek",           // Action type 
18
        waitTillPause: 6,       // Wait time before playing 
19
        params: {               // Action parameters 
20
          seekTime: 5           // Target time for seek 
21
        } 
22
      }, 
23
       
24
      onProductHover: {         // Hover action (optional) 
25
        type: "overlay",        // Action type 
26
        params: {               // Action parameters 
27
          description: "Text to show on hover" 
28
        } 
29
      }, 
30
       
31
      markers: [                // Hotspot markers (optional) 
32
        { 
33
          x: 175,               // X position (0-100%) 
34
          y: 60,                // Y position (0-100%) 
35
          tooltipPosition: "left", // Tooltip position 
36
          link: "url"           // Link when clicked 
37
        } 
38
      ] 
39
    } 
40
  ] 
41
} 

Product configuration

Products are defined inside the products array. Each product has required fields (which the player needs to function) and optional fields (to enrich interactivity).

Required fields

Optional fields

Product actions reference

Products can trigger two types of interactivity:

Click actions

Defines what happens when a product is selected in the sidebar or overlay.

Click action configuration example:

1
// Open external link with video pause 
2
onProductClick: { 
3
  type: "openLink", 
4
  params: { 
5
    targetUrl: "https://store.com/product", 
6
    shouldPause: true 
7
  } 
8
} 
9
 
10
// Seek to specific time with wait 
11
onProductClick: { 
12
  type: "seek", 
13
  params: { 
14
    seekTime: 45, 
15
    waitTillPause: 10 
16
  } 
17
} 

Hover actions

Hover actions control what happens when a user moves their mouse over a product in the sidebar.

Hover action configuration example:

1
// Show text overlay on hover 
2
onProductHover: { 
3
  type: "overlay", 
4
  params: { 
5
    description: "Premium product with excellent quality" 
6
  } 
7
} 
8
 
9
// Switch image on hover 
10
onProductHover: { 
11
  type: "swap", 
12
  params: { 
13
    switchImage: "https://example.com/product-alt-view.jpg" 
14
  } 
15
}

Sidebar configuration

The productSidebarConfig object customizes how the sidebar behaves during playback.

Example:

1
productSidebarConfig: { 
2
  startState: "openOnPlay",  // Sidebar opens when video starts  
3
  autoClose: 30,             // Auto-close after 30 seconds 
4
  showPostPlayOverlay: true  // Show overlay when video ends 
5
}

Hotspot marker configuration

Hotspot markers let you place clickable pins directly inside the video frame. These markers can appear at specific times during playback, linking viewers to products or external pages. They’re a powerful way to make your video feel more interactive - imagine a furniture demo where pins appear directly on the chair or table being shown.

Each marker is defined inside the markers array of a product object.

Marker object structure

Example:

1
markers: [ 
2
  { 
3
    seekTime: 15,           // Appear at 15 seconds 
4
    x: 25,                  // 25% from left 
5
    y: 30,                  // 30% from top 
6
    tooltipPosition: "bottom", // See below table for tooltip positioning 
7
    link: "https://store.com/product" 
8
  } 
9
]

In this example:

• A marker appears 15 seconds into the video.
• It’s positioned at 25% from the left and 30% from the top of the player.
• When hovered, the tooltip shows up below the marker.
• Clicking the marker takes the viewer to an external product page.

Tooltip position options

Tooltips help keep the UI intuitive by making it clear what a marker represents without overwhelming the video with too much text.

CSS customization

By default, the shoppable themes follow FastPix’s built-in styles, ensuring the sidebar, buttons, and overlays adapt well across devices. But in most real-world cases, you’ll want the player to match your brand identity.

FastPix Player supports CSS custom properties (variables) that let you tweak the look and feel without digging into the player’s internals.

Available custom properties:

You can apply these variables directly to the <fastpix-player> element in your stylesheet:

1
fastpix-player { 
2
  --shoppable-sidebar-width: 30%; 
3
  --shoppable-sidebar-background-color: rgba(255, 255, 255, 0.75); 
4
  --accent-color: #ff6b35; 
5
} 

Events

Beyond displaying products, the shoppable player emits events you can listen for in JavaScript. These events allow you to:

• Track user interactions (clicks, hovers, replays).
• Build custom analytics pipelines.
• Trigger custom UI or backend logic based on how viewers interact with products.

Events are emitted both for sidebar interactions and for the post-play overlay. Some events also indicate sidebar state changes and video lifecycle actions (like replay).

Available events:

Event usage examples

Listening to product events is straightforward - attach event listeners to the player element:

1
// Product interaction events (with product data) 
2
player.addEventListener('productHover', (e) => { 
3
  console.log('Product hovered:', e.detail.product.name); 
4
  // Track analytics: product hover in sidebar 
5
}); 
6
 
7
player.addEventListener('productClick', (e) => { 
8
  console.log('Product clicked:', e.detail.product.id); 
9
  // Track analytics: product click in sidebar 
10
}); 
11
 
12
// Sidebar state events (no event detail) 
13
player.addEventListener('productBarMax', () => { 
14
  console.log('Sidebar opened'); 
15
  // Track analytics: sidebar opened 
16
}); 
17
 
18
player.addEventListener('productBarMin', () => { 
19
  console.log('Sidebar closed'); 
20
  // Track analytics: sidebar closed 
21
}); 
22
 
23
// Post-play overlay events (with product data) 
24
player.addEventListener('productHoverPost', (e) => { 
25
  console.log('Post-play hover:', e.detail.product.name); 
26
  // Track analytics: product hover in post-play overlay 
27
}); 
28
 
29
player.addEventListener('productClickPost', (e) => { 
30
  console.log('Post-play click:', e.detail.product.id); 
31
  // Track analytics: product click in post-play overlay 
32
}); 
33
 
34
// Video replay event (no event detail) 
35
player.addEventListener('replay', () => { 
36
  console.log('Video replayed'); 
37
  // Track analytics: video replay 
38
}); 

Complete example

Here’s a single snippet that wires up the shoppable player, passes product data, customizes CSS, and listens to events.

1
<!DOCTYPE html>
2
<html lang="en">
3
<head>
4
    <meta charset="UTF-8" />
5
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
    <script src="https://cdn.jsdelivr.net/npm/@fastpix/fp-player@latest/dist/player.js"></script>
7
    <title>FastPix Player</title>
8
    <style>
9
        #player-playlist {
10
            --shoppable-sidebar-width: 30%;
11
        }
12
    </style>
13
</head>
14
<body>
15
    <h3>FastPix Player - Shoppable player & Navigation Demo</h3>
16
    <fastpix-player id="player-playlist" theme="shoppable-video-player"
17
        playback-id="919ec265-f409-4dd8-ac3d-366181e12e7a" 
18
        custom-domain="stream.fastpix.app" 
19
        min-resolution="480p"
20
        max-resolution="720p">
21
    </fastpix-player>
22
    <script>
23
24
        // Wait until the custom element is defined 
25
        customElements.whenDefined('fastpix-player').then(() => {
26
            const player = document.getElementById('player-playlist');
27
            const cartData = {// Instead of cartProducts and productSidebarConfig as separate properties, combine them: 
28
                productSidebarConfig: {
29
                    startState: "openOnPlay",
30
                    autoClose: 4,
31
                    showPostPlayOverlay: true,
32
                },
33
                products: [
34
                    {
35
                        id: 1,
36
                        thumbnail:
37
                            "https://in.zohocommercecdn.com/product-images/JNW+Shajahan+Sofa+Set+Single+Rosewood+1.jpg/431189000086560983/600x600?storefront_domain=www.jfa.in",
38
                        name: "chair",
39
                        description: "Description 1",
40
                        startTime: 0,
41
                        endTime: 5,
42
                        markers: [
43
                            {
44
                                x: 175,
45
                                y: 60,
46
                                tooltipPosition: "left",
47
                                link: "https://www.jfa.in/products/JNW-Shajahan-Sofa-Set-Single-Rosewood-Dx-Premium-Wooden-Sofa-Set/431189000029424510",
48
                            },
49
                        ],
50
                        onProductClick: {
51
                            type: "seek",
52
                            waitTillPause: 6,
53
                            params: {
54
                                seekTime: 5,
55
                            },
56
                        },
57
                        onProductHover: {
58
                            type: "overlay",
59
                            params: {
60
                                description: "see this product in the video",
61
                            },
62
                        },
63
                    },
64
                    {
65
                        id: 2,
66
                        thumbnail:
67
                            "https://in.zohocommercecdn.com/product-images/FDI+Treviso+Sofa+3+Seater+1.jpg/431189000087278412/600x600?storefront_domain=www.jfa.in",
68
                        name: "Treviso Sofa",
69
                        description: "Description 1",
70
                        startTime: 6,
71
                        endTime: 10,
72
                        markers: [
73
                            {
74
                                x: 60,
75
                                y: 50,
76
                                tooltipPosition: "left",
77
                                link: "https://www.jfa.in/products/aa55d60413/431189000071080281",
78
                            },
79
                        ],
80
                        onProductClick: {
81
                            type: "seek",
82
                            waitTillPause: 3,
83
                            params: {
84
                                seekTime: 7,
85
                            },
86
                        },
87
                        onProductHover: {
88
                            type: "overlay",
89
                            params: {
90
                                description: "see this product in the video",
91
                            },
92
                        },
93
                    },
94
                    {
95
                        id: 3,
96
                        thumbnail:
97
                            "https://in.zohocommercecdn.com/product-images/1400x1400-Photoroom+%281%29.jpg/431189000076435150/600x600?storefront_domain=www.jfa.in",
98
                        name: "Product 2",
99
                        description: "Description 2",
100
                        startTime: 11,
101
                        endTime: 18,
102
                        onProductClick: {
103
                            type: "openLink",
104
                            shouldPause: true,
105
                            params: {
106
                                targetUrl:
107
                                    "https://www.jfa.in/products/guru-ct-01-computer-table-30x18x30-walnut-computer-study-table/431189000070278273",
108
                            },
109
                        },
110
                        onProductHover: {
111
                            type: "overlay",
112
                            params: {
113
                                description: "Click to view the product",
114
                            },
115
                        },
116
                    },
117
                    {
118
                        id: 4,
119
                        thumbnail:
120
                            "https://in.zohocommercecdn.com/product-images/AMM+Topaz+Plastic+Chair+W+Metal+Leg+and+Seat+Cushion+YellowOffice+Chair+3.jpg/431189000087691668/300x300?storefront_domain=www.jfa.in",
121
                        name: "AMM Topaz Plastic Chair",
122
                        description: "Description 3",
123
                        markers: [
124
                            {
125
                                x: 50,
126
                                y: 50,
127
                                tooltipPosition: "top",
128
                                link: "https://www.jfa.in/products/JNW-DT-Heart-Jali-Dining-Table-60X36-Walnut-Dining-Table/431189000029421080",
129
                            },
130
                        ],
131
                        onProductClick: {
132
                            type: "seek",
133
                            waitTillPause: 30,
134
                            params: {
135
                                seekTime: 32,
136
                            },
137
                        },
138
                        onProductHover: {
139
                            type: "swap",
140
                            params: {
141
                                switchImage:
142
                                    "https://in.zohocommercecdn.com/product-images/AMM+Topaz+Plastic+Chair+W+Metal+Leg+and+Seat+Cushion+YellowOffice+Chair+1.jpg/431189000087691662/600x600?storefront_domain=www.jfa.in",
143
                            },
144
                        },
145
                    },
146
                ],
147
            };
148
149
            // Provide your shoppable JSON 
150
            player.addShoppableData(cartData);
151
152
            // Optional: listen to events 
153
            player.addEventListener('productHover', (e) => console.log('hover:', e.detail.product));
154
            player.addEventListener('productClick', (e) => console.log('click:', e.detail.product));
155
            player.addEventListener('productBarMax', () => console.log('bar opened'));
156
            player.addEventListener('productBarMin', () => console.log('bar closed'));
157
            player.addEventListener('productHoverPost', (e) => console.log('overlay hover:', e.detail.product));
158
            player.addEventListener('productClickPost', (e) => console.log('overlay click:', e.detail.product));
159
            player.addEventListener('replay', () => console.log('replay'));
160
        });
161
    </script>
162
</body>
163
</html>

PLEASE NOTE

1. In examples elsewhere you may see markers include seekTime. If present, it controls when a marker appears. If omitted, the marker’s visibility can be inferred from the product’s startTime/endTime. Your implementation can support either pattern, but keep it consistent within your project.

2. If both markers and onProductClick are used, onProductClick takes precedence.

3. FastPix Player automatically handles responsiveness.

Troubleshooting

Cart Button Not Displaying

If the cart button isn’t appearing, check these common issues:

1. Theme not set correctly

1
<!-- CORRECT --> 
2
<fastpix-player theme="shoppable-video-player" ...> 
3
 
4
<!-- INCORRECT --> 
5
<fastpix-player theme="default" ...>

2. Player not initialized

Make sure the player is fully loaded before adding shoppable data:

1
// Wait for player to be ready 
2
customElements.whenDefined('fastpix-player').then(() => { 
3
  const player = document.getElementById('my-player'); 
4
   
5
  // Wait for player to be fully initialized 
6
  player.addEventListener('loadedmetadata', () => { 
7
    // Now add shoppable data 
8
    player.addShoppableData(cartData); 
9
  }); 
10
});

3. Missing product data

For shoppable-video-player, you must call addShoppableData():

1
// REQUIRED for shoppable-video-player 
2
player.addShoppableData({ 
3
  productSidebarConfig: { ... }, 
4
  products: [ ... ] 
5
})

Note: The product-link attribute is ignored for shoppable-video-player theme. Only shoppable-shorts theme uses the product-link attribute.

4. CSS Conflicts

Ensure no CSS is hiding the cart button:

1
/* Check if cart button is hidden */ 
2
.cartButton { 
3
  display: none; /* This would hide the button */ 
4
} 
5
 
6
/* Check for other potential conflicts */ 
7
.cartButton { 
8
  visibility: hidden; /* This would hide the button */ 
9
  opacity: 0; /* This would make the button invisible */ 
10
  z-index: -1; /* This would put the button behind other elements */ 
11
} 
12
 
13
/* Check for responsive hiding */ 
14
@media (max-width: 150px) { 
15
  .cartButton { 
16
    display: none; /* This hides cart button on very small screens */ 
17
  } 
18
}

Common CSS issues:

• CSS Variable syntax: Ensure CSS variables use double dashes (e.g., —shoppable-sidebar-width, not -shoppable-sidebar-width)
• Theme-specific behavior: shoppable-shorts cart button is always visible regardless of screen size

5. Force show cart button (Debug)

If the cart button still doesn’t appear, you can force it to show:

1
// Debug method to force show cart button 
2
const player = document.getElementById('my-player'); 
3
player.showCartButton(); 
4
 
5
// For shoppable-shorts specifically 
6
if (player.getAttribute('theme') === 'shoppable-shorts') { 
7
  player.ensureShoppableShortsCartButton(); 
8
}

Debug steps

1. Check console: Look for JavaScript errors
2. Verify theme: Ensure theme="shoppable-video-player" or theme="shoppable-shorts" is set. When using shoppable-video-player, the correct method to pass configuration must be used player.addShoppableData(cartData);
3. Check network: Ensure player.js is loading correctly (no 404/CORS).
4. Inspect element: Check if cart button exists in DOM but is hidden