MP4E — Interactive video that travels in the file

Overview

Cart (mp4e:cart, an official plugin) keeps what the viewer chose to buy. A badge in the top corner counts the items; a tap on it opens a panel beside the video — the items with their price and quantity, the total, and Checkout — while the video keeps playing. Items usually come from Product card's Add to cart button.

Cart is a family plugin: it has the family's five themes, its common style settings, its minimum readable size and its keyboard and TV-remote navigation. What happens at checkout — and how your page takes the order — is on In-video shopping.

Adding a cart to a video

Make interactive does all of this when the video's products have prices (the Shopping cart feature). By hand:

Install Cart from the marketplace.
Add one Cart overlay covering the whole timeline. It covers the whole frame and places its own badge and panel, so do not resize it. Use one Cart per video: a second one would take every item a second time.
Turn on Add to cart in your Product cards and give each product a price as a number and its currency.
Send the cards' addToCart event to the cart: a rule on plugin:mp4e:product-card:addToCart running the cart's addItem with the product from the event.
Pick a theme and a size. Lean-back is for a TV across the room.

Anything that can run an action can add to the cart — a button, a hotspot, another plugin:

Add an item from a rule or a button

{ "type": "pluginAction", "pluginId": "mp4e:cart", "actionId": "addItem",
  "config": { "name": "Travel case", "price": 24.5, "currency": "USD" } }

The cart

Adding a product that is already in the cart (the same objectId, else the same name) raises its quantity; the first name and price stay.
One currency per cart — the currency setting, else the first item's. An item in another currency is refused and the viewer sees "This cart is in USD" for a few seconds. An item without a currency takes the cart's.
Prices and the total are shown in the cart's currency, formatted for the viewer's language. A price of 0 is a free item.
The cart lasts for the viewing session; it is not kept when the page is reloaded.

Each line of the cart:

Prop	Type	Default	Description
`key`	`string`	-	The objectId, else the name — what removeItem and setQuantity take.
`objectId`	`string`	-	The tracked product the item came from, when it came from one.
`name`	`string`	-	The product name.
`price`	`number`	-	The unit price.
`currency`	`string`	-	The cart's currency.
`quantity`	`number`	-	1 to 99.

Settings

Cart's own settings, plus the family's common style settings (theme, accent, size, surface, textColor, font, radius, motion):

Prop	Type	Default	Description
`currency`	`string`	`''`	The cart's currency, a three-letter code (USD, EUR, GBP…). Empty: the first item's currency. Items in another currency are refused.
`checkout`	`'host' \| 'plugin'`	`'host'`	Who takes the payment: your site (the cart emits checkout and your page answers) or a payment plugin (the cart calls its pay action). See In-video shopping.
`checkoutPlugin`	`string`	`''`	The payment plugin's key (namespace:identifier) when checkout is 'plugin'. The cart calls its pay action with { order, replyTo }, and the plugin answers through replyTo's checkoutResult.
`showEmpty`	`boolean`	`false`	Show the badge while the cart is empty. Off: the badge appears with the first item.

How it behaves

Tappable while the video plays. Only the badge and the open panel take the pointer (through clickable regions); every click elsewhere goes through to the video, your hotspots, other overlays and the player's controls.
The badge pulses once when an item is added (not when the viewer prefers reduced motion). A tap on it opens or closes the panel; the video keeps playing. Escape or Back closes the panel.
In the panel the viewer changes quantities (− and +) and removes items. The list scrolls on its own so the total and Checkout stay in view. On a phone-sized player the panel spans the frame.
The panel stays clear of the player's controls bar.
A keyboard or TV remote reaches the badge with Tab; Enter opens the panel.
Product names are always shown as plain text.

Actions

Through pluginAction from rules, other plugins and input shortcuts, or callPluginAction from your page:

Prop	Type	Default	Description
`addItem`	`{ objectId?, name, price, currency?, quantity? }`	-	Add a product. The same product again (the same objectId, else the same name) raises its quantity. price is a number of 0 or more (numeric text is read; "$49" is refused); quantity defaults to 1. Answers { added: true, item, count, total }, or { added: false, reason } — reason is name, price, currency (another currency than the cart's) or quantity.
`removeItem`	`{ key }`	-	Remove a line (key is the line's objectId, else its name). Answers { removed, count, total }.
`setQuantity`	`{ key, quantity }`	-	Set a line's quantity, a whole number up to 99; 0 or less removes it. Answers { updated, count, total }.
`clear`	`—`	-	Empty the cart. Answers { cleared: true }.
`open`	`—`	-	Open the panel. Answers { opened: true }.
`close`	`—`	-	Close the panel. Answers { closed: true }.
`checkoutResult`	`{ orderId, status, message? }`	-	The checkout's outcome — handled, completed or failed — from your page or from the payment plugin. See In-video shopping.

While a checkout is open, addItem, removeItem, setQuantity and clear are refused with { accepted: false, reason: "pending" } and the viewer is told "Finish or cancel your checkout first".

Events and variables

Prop	Type	Default	Description
`itemAdded`	`{ item }`	-	An item went into the cart (a new line, or one more of a line already there); item is the line after the add.
`cartChanged`	`{ items, count, total, currency }`	-	Every change to the lines: an add, a quantity, a removal, a clear, a completed checkout.
`checkout`	`{ order }`	-	The viewer pressed Checkout, with checkout on your site only.
`checkoutCompleted`	`{ orderId }`	-	A completed result arrived; the cart emptied.
`checkoutFailed`	`{ orderId, message }`	-	A failed result arrived, or a payment plugin could not start the payment.

Rules hear them as plugin:mp4e:cart:<event> (for example plugin:mp4e:cart:checkoutCompleted); your page hears them through onEvent.

Installing Cart creates three variables, which the cart keeps current for your rules, other plugins and your page: mp4e:cart:items (the lines), mp4e:cart:count (the number of items — the total quantity) and mp4e:cart:total. Read them; leave the writing to the cart. A new list written to mp4e:cart:items is taken over by the cart, which then sets the count and the total to match.

Checkout

Checkout pauses the video and hands the order — { orderId, items, total, currency } — to your site or to a payment plugin, one order at a time. The order, the checkout event, the checkoutResult answer and the payment-plugin contract are on In-video shopping. A payment plugin implements pay { order, replyTo } and answers with mp4e.callAction(replyTo, 'checkoutResult', …) — no rule in the video.

Cart Plugin