Links

Actions and Factories

Actions

actions is an object provided by event.detail for various player content manipulations.
cart
updateProduct
Update product info for a product in cart. Similar to product hydration but may contain products not related to current video since player cart is just a mirror of storefront cart.
updateProductQuantity
Quick way to update cart product quantity without updating the product itself.
configure
Update the cart's checkout CTA link and currency
shopping
hydrateProduct
Action to provide latest product update via hydration.
video
update
Action to allow storefront to update video info like i18n caption , CTA and more..

actions.cart.updateProductQuantity

Accepts an object of variant ext_id and quantity and updates the cart item
actions.cart.updateProductQuantity({ id: 'xyz', quantity: 3 })

actions.cart.configure

Accepts an object of currency and url for the cart (url will be used for checkout CTA); addToCartText and itemInCartText are used to customize the text on the cart related CTAs and they are optional
actions.cart.configure({ currency: 'USD', url: 'https://shop.com/cart', addToCartText: 'Add to Bag', itemInCartText: 'Item in Bag' })

actions.cart.resetCart

Clears the cart content.

actions.shopping.hydrateProduct

Accepts a callback with productFactory as first argument param expecting a product to be returned.
actions.shopping.hydrateProduct(({ productFactory }) =>
productFactory((p) => p.name("Top secret"))
);

WooCommerce product hydration example

/**
* An example of a product hydration on WooCommerce storefront.
*
* Attach the listener to `fw:shopping:hydrate-products` which gets
* fired with each video/livestream containg a product.
*/
document.addEventListener("fw:shopping:hydrate-products", async (event) => {
/**
* event.detail contains list of `products`
* attached to current video along with set of `actions` which
* can be used to hydrate each individual product
*/
const { products, actions } = event.detail;
products.forEach((p) => {
/**
* product's `product_ext_id` is the ID identifying
* current product within store database.
*/
if (p.product_ext_id) {
/**
* Request for the latest product information
* using your own fetch method `getProductById`
*/
getProductById(p.product_ext_id).then((wooProduct) => {
if (wooProduct.id) {
/**
* `actions.shopping.hydrateProduct` provides
* a factory to update (hydrate) the product with the latest info.
*/
actions.shopping.hydrateProduct(({ productFactory }) =>
productFactory((p) => {
/**
* `productFactory` is a factory function which accepts callback
* function returning a new product object.
*/
const product = p
.description(wooProduct.description)
.ext_id(wooProduct.id)
.name(wooProduct.name);
wooProduct.variations.forEach((wooVariant) => {
/**
* `product.variant` accepts callback which returns
* a new variant object. Please note each product needs
* at least one variant.
*/
product.variant((v) => {
const variant = v
.ext_id(wooVariant.variation_id)
.isAvailable(wooVariant.is_in_stock)
.name(wooVariant.sku)
.price(wooVariant.display_price)
.sku(wooVariant.sku);
/*
* Modify or add images based on your ext_id.
*/
if (wooVariant.image) {
variant.image((i) =>
i
.ext_id(wooVariant.image_id)
.position(0)
.title(wooVariant.image.alt)
.url(wooVariant.image.src)
);
}
/*
* Variant options like "size", "color"
* with their corresponding values.
*/
Object.entries(wooVariant.attributes || {}).forEach(
([name, value]) =>
variant.option({
name: name.replace(/attribute_/, ""),
value,
})
);
return variant;
});
});
return product;
})
);
} else {
console.warn(`Cant fetch product by ext_id "${p.product_ext_id}"`);
}
});
}
});
});

Factories

Product factory

Product factory is a function provided by a product hydration event which expects callback returning new product with associated variants and images. Each factory method returns self so calls can be chained.
productFactory(product => product)
Name
Description
Required
ext_id
External ID. Identifier in a partner database. Value is used to match and update products synced with Firework using various e-commerce integration tools.
Yes
name
Product name
Yes
description
Product description. Markdown for rich formating is allowed.
Yes
currency
Currency code. e.g. "USD"
Yes
variant
Variant factory, see below.
Yes
// Example of product hydration using product factory.
actions.shopping.hydrateProduct(({ productFactory }) =>
productFactory((product) => {
return product.ext_id("1").name("First Product");
})
);

Variant factory

Variant factory used to feed product with multiple variants (e.g. different size or colors). Please note each product needs at least one variant.
Name
Description
Required
ext_id
External ID. Variant identifier in a partner database. Value is used to match and update variants synced with Firework using various e-commerce integration tools.
Yes (If this is only created to satisfy product requirement where every product needs a variant, this can be the same as product's ext_id )
sku
SKU identifier.
Optional
name
Variant name.
Optional
url
URL to product/variant detail page.
Yes
price
Numeric value of current price
Yes
originalPrice
Numeric value of original price
Optional
isAvailable
Boolean indicating whether variant is currently available (out of stock).
Optional
image
Image factory, see below.
Optional
option
Accepts {name, value} object with variant option.
Optional
// Example of providing multiple variants.
actions.shopping.hydrateProduct(({ productFactory }) =>
productFactory((product) => {
return product
.ext_id("123")
.name("T-Shirt")
.variant((variant) => {
return variant
.ext_id("123redxl")
.name("Red XL")
.price(10.0)
.originalPrice(20)
.option({
name: "Color",
value: "Red"
})
.option({
name: "Size",
value: "XL"
});
})
.variant((variant) => {
return variant
.ext_id("123bluexl")
.name("Blue XL")
.price(10.0)
.option({
name: "Color",
value: "Blue"
})
.option({
name: "Size",
value: "XL"
});
});
})
);

Image factory

Image factory to provide product (or variant) images.
Name
Description
Required
ext_id
External ID of an image in partner database used to match images between partner and Firework database.
Yes
title
Alt title for an image.
Optional
position
Numeric value used to sort multiple images.
Optional
url
URL location of an image.
Yes
// Example of providing multiple images to the variant.
actions.shopping.hydrateProduct(({ productFactory }) =>
productFactory((product) => {
return product
.ext_id("123")
.name("T-Shirt")
.variant((variant) => {
return variant
.ext_id("123blue")
.name("Blue XL")
.price(10.0)
.option({
name: "Color",
value: "Blue"
})
.option({
name: "Size",
value: "XL"
})
.image((image) => {
return image
.ext_id("img1")
.position(1)
.title("T-Short, Blue, XL, front view")
.url("https://example.com/image.jpg");
})
.image((image) => {
return image
.ext_id("img2")
.position(2)
.title("T-Short, Blue, XL, back view")
.url("https://example.com/another-image.jpg");
});
});
})
);