Shopping APIs
Firework Shopping APIs can be accessed via
window._fwn.shopping
. It is made available after the Firework SDK is ready. <script async src="//asset.fwcdn3.com/js/fwn.js" type="text/javascript" ></script>
<script>
if (window._fwn?.shopping) {
// if window._fwn?.shopping is loaded before this script tag, use it directly
} else {
document.addEventListener('fw:ready', () => {
// window._fwn.shopping is available within the callback
})
}
</script>
This section explains the Firework Shopping APIs available for you.
Arguments
Configs
{url?: string; currency?: string}
Cart configurations
- url: The URL of the cart page
- currency: The currency used in the cart
- addToCartText: Primary CTA text on product card
Returns
void
Example
window._fwn.shopping.configureCart({
url: 'https://firework.com/cart',
currency: 'USD'
addToCartText: 'Add to Bag'
})
Register a callback that triggers when Firework player finishes loading products. It is recommended to hydrate products in this callback if the product data is updated on the customer e-commerce platform or customized to local users (i.e show discounted price for premium accounts).
Arguments
callback
(productsToHydrate: Product[]) => Promise<Product[]>
The callback to trigger. It returns a list of Firework product objects. They will be merged with the products registered in the Firework CMS with matching
ext_id
. The callback will trigger once per video when the player becomes active. If the callback throws, the error message will be surfaced to users with a player error modal.Returns
void
Example
window._fwn.shopping.onProductsLoaded(async ({products}) => {
const productIds = products.map((product) => product.produce_ext_id);
// Make a server request to get the latest product data.
const remoteProducts = await fetchProductsFromServer(productIds);
return remoteProducts.map((remoteProduct) => createFWProduct(remoteProduct));
});
Register a callback that triggers when the Firework player displays the cart. It is recommended to provide the latest cart items from the website cart in the callback.
Arguments
callback
() => Promise<CartItem[]>
The callback to trigger. It should return the latest product data derived from each cart item, product unit id, and quantity. The product data will be merged with the product in the store if one already exists with matching
ext_id
. The callback can trigger multiple times throughout the lifecycle of the video player. If nothing has changed, you should consider caching and skipping requesting data from the remote server. If the callback throws an error, the error message will be surfaced to users with a player error modal.Returns
void
Example
window._fwn.shopping.onCartDisplayed(async () => {
// Make a request to get the latest cart.
const remoteCart = await fetchCartFromServerOrCache();
// Return cart items.
return remoteCart.items.map((remoteCartItem) => {
const { unitId, quantity, product } = remoteCartItem;
return { product: parseProduct(product), unitId, quantity }
});
});
Register a callback that triggers when the Firework player attempts to update the cart. It is recommended to update the website cart with the player cart data in the callback.
Arguments
callback
(product: Product, productUnit: ProductUnit, quantity: number, previousQuantity: number, playlist: string) => Promise<number>
The callback to trigger. It should return the cart item quantity verified by the server. If the callback throws an error, the error message will be surfaced to users with a player error modal. For example, you can throw an error if the updated item is out of stock.
Returns
void
Example
window._fwn.shopping.onCartUpdated(async ({product, productUnit, quantity}) => {
// Make a request to update the remote cart.
const result = await updateVariant(product, productUnit, quantity);
return result.quantity;
});
Factory method to create a Firework product from an external product object.
Arguments
callback
(builder: ProductBuilder) => void)
The callback function will be used to construct the Firework product.
If you update an existing product in the Firework CMS, you only need to fill in the fields to update. If you add new products outside Firework CMS, all required fields must be filled. It’s recommended to set
validateRequiredFields
to true in this case. The product builder exposes methods to fill the product fields. Please refer to the section Product Factory for more detailed code snippets.validateRequiredFields
boolean
optional, false by default. When set to true, the factory will validate whether all the required fields are set on the output object of the callback. If any field is missing, it will log the error in the console.
Returns
Product
: A Firework productExample
// Returns a hydrated product with only the description field filled.
const hydratedProduct = window._fwn.shopping.productFactory((builder) => {
builder.description('updated description').ext_id(remoteProduct.id);
});
// Logs an error indicating required fields are missing.
const hydratedProduct2 = window._fwn.shopping.productFactory((builder) => {
builder.description('updated description').ext_id(remoteProduct.id);
}, /* validateRequiredFields */ true);
If you want to rehydrate the product after the Firework player loads the products outside of
onProductsLoaded
callback, you can call this method to trigger product hydration at any time.Arguments
products
Products[]
Firework products to hydrate.
Returns
void
Example
function onUserSignedIn() {
const remoteProducts = await fetchUserProductsFromServer();
const fwProducts = remoteProducts.map((remoteProduct) => createFWProduct(remoteProduct));
window._fwn.shopping.hydrateProducts(fwProducts);
}
Last modified 1mo ago