Launching an experience on your site with the Hosted Experience API

Hosted experiences are a way to launch a customer's bundle from your own website using our cloud infrastructure. This is a great way to integrate Spiff Commerce into your existing website without having to worry about implementing the UI. The experience is defined by an activation, which links a theme to the product collections your customers can choose from.

Getting started

For compatible e-commerce stores the hosted API will be loaded automatically into your store on page load. If you need to load the API manually you can do so by inserting the following snippet into the <head> section of your webpage.

<script src="https://assets.us.spiffcommerce.com/api.js"></script>
<!-- Non-US users also use the US URL. -->

Once you have the script loading, you must listen for the load process to complete. This can be done by listening for the event SpiffApiReady as below.

window.addEventListener("SpiffApiReady", function () {
    // Code using the API goes here.
});

Within the handler of this event you may place all remaining required initialization code. To give a rough idea of how you might use the API to launch an experience, refer to the following example.

const hostedExperience = new window.Spiff.HostedExperience({
    bundleMode: true,
    applicationKey: "<Enter your application key here>",
    presentmentCurrency: "<Enter a valid ISO currency here.>",
    queryParams: { activationId: "<Enter your activation ID here>" },
});
hostedExperience.on("complete", async (result) => {
    // Handle the customer's finished bundle.
});
hostedExperience.on("quit", () => {
    // The customer left without finishing.
});
hostedExperience.execute();

hostedExperience.on("complete", handler) is the most important part of this example. This is where you will receive the result of the experience: the customer's bundle, containing the bundleId and an items array with one entry for each design the customer created. Each item includes a transactionId. You must store these IDs against the line items added to your cart as they act as a reference to the designs created by the customer.

Classes

HostedExperience

A hosted experience represents a customer's session building a bundle of designs, launched within an activation.

const hostedExperience = new window.Spiff.HostedExperience({
    bundleMode: true, // Required. Launches the bundle experience.
    applicationKey: "<Required: You can pull this key from the e-commerce integration in Hub>",
    presentmentCurrency: "<Insert your desired presentment currency>",
    queryParams: { activationId: "<Required: The activation to launch>" },
    product: undefined, // Optional. A Product or IntegrationProduct (see below) to preselect.
    embedElement: undefined, // Optional. The element to embed the experience into. Modal otherwise.
    forceFullscreen: false, // Optional. Mobile devices are always fullscreen.
    finishButtonText: "Add to Cart", // Optional. The text of the button that completes the experience.
    loadingOptions: {
        // Optional. Customizes the loading screen shown while the experience loads.
        background: "linear-gradient(#ffffff, #ffffff)",
        fadeOutTimeMs: 0,
        image: "<Image URL>",
        imageStyles: "<Inline CSS for the image>",
    },
});
hostedExperience.on("complete", (result) => {
    // Called when the customer has finished their bundle.
});
hostedExperience.on("quit", () => {
    // Called when the customer has abandoned the experience.
});

// Returns a promise that resolves when the iframe has loaded.
hostedExperience.execute();

The result for a HostedExperience complete callback is a BundleDesignCreationMessage (its type is "bundle") with the following arguments:

Name	Type	Optional?	Description
bundleId	string	n	The ID of the bundle.
bundleOwnerId	string	y	The ID of the user who owns the bundle.
cartAddMode	string	y	How items should be added to the cart: Default, FirstTransaction or OneToOne.
collectionId	string	n	The ID of the product collection the bundle is using.
collectionName	string	n	The name of the product collection the bundle is using.
dispatchDate	string	n	The date the bundle is expected to be dispatched.
items	array	n	The designs in the bundle, as described below.
name	string	n	The name assigned by the user for this bundle.
purchaseOrder	string	n	The purchase order associated with the bundle.

Each entry in items has the following arguments:

Name	Type	Optional?	Description
baseCost	number	y	The base price of the product in Spiff, in the subunits of the partner's currency. May be different to the price of the product in the eCommerce system.
designProductVariantId	string	y	This will be set if the product has been configured to produce design products. Currently only supported on Shopify.
designProductId	string	y	This will be set if the product has been configured to produce design products. Currently only supported on Shopify.
externalCartProductId	string	y	The ID of the product in your e-commerce system to add to the cart.
externalCartProductVariantId	string	y	The ID of the variant in your e-commerce system to add to the cart.
exportedData	object	n	The metadata and variant selections recorded during the customization process.
lineItemImageUrl	string	n	A URL to a preview image of the consumer's design.
optionsCost	number	n	Cumulative price of the variants selected by the consumer, in the subunits of the partner's currency.
processExecutionId	string	y	If a flow in flight was spawned, this is its ID.
quantity	number	y	The quantity of this design to order.
sku	string	y	This will be set if the corresponding workflow is configured to generate dynamic SKUs.
transactionId	string	n	The ID of this transaction entity.
workflowViewerLink	string	n	A URL to visit this design in the workflow viewer

IntegrationProduct

The IntegrationProduct class represents a product from the Spiff Hub integration. Pass it as the product option of a HostedExperience to preselect it, or to check that a product is enabled before showing a button.

const integrationProduct = new window.Spiff.IntegrationProduct("<Insert your integration product ID>");

integrationProduct.on("ready", (callbackOptions) => {
    // The product has been determined to exist in Spiff Commerce's database and is enabled.
});

integrationProduct.on("invalid", (callbackOptions) => {
    // Spiff Commerce could not find the product or it is not enabled.
});

// This will trigger the "ready" or "invalid" callbacks
// It will also return a promise that resolves with a boolean indicating if the product is valid.
const isValid = await integrationProduct.confirmActive();

Product

The Product class represents a product in your store, identified by your store's own IDs. It is typically only used by Shopify stores.

const product = new window.Spiff.Product({
    // The external integration ID. This is likely either your domain or a unique identifier for your store.
    // This is not the same as the regular integration ID that you will find in the Spiff Hub.
    integrationId: "<Your store's external integration ID>",
    // The identifier of the product on your e-commerce store.
    productId: "<Your store's product ID>",
});

product.on("ready", (callbackOptions) => {
    // The product has been determined to exist in Spiff Commerce's database and is enabled.
});

product.on("invalid", (callbackOptions) => {
    // Spiff Commerce could not find the product or it is not enabled.
});

// This will trigger the "ready" or "invalid" callbacks
// It will also return a promise that resolves with a boolean indicating if the product is valid.
const isValid = await product.confirmActive();