Launching an experience on your site with the Hosted Experience API

Hosted experiences are a way to launch a workflow 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. You can configure your hosted experience using workflows and themes.

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 initialize a workflow experience refer to the following example.

const product = new window.Spiff.IntegrationProduct("<Enter your integration product ID here>");
product.on("ready", () => {
    const hostedExperienceOptions = {
        presentmentCurrency: "<Enter a valid ISO currency here.>",
        product: product,
    };
    const hostedExperience = new window.Spiff.HostedExperience(hostedExperienceOptions);
    hostedExperience.on("complete", async (result) => {
        // Handle the result of the workflow experience..
    });
    hostedExperience.execute();
});
product.confirmActive();

hostedExperience.on('complete', workflowCompleteHandler) is the most important part of this example. This is where you will receive the result of the workflow experience. The result will be an object containing important metadata about the customer design. One of the properties provided is a transaction ID. You must store this ID against the line item added to your cart as it will act as a reference to the design created by the customer.

Classes

These are the available classes. This should give you an idea of how they are used for the samples above.

IntegrationProduct

The IntegrationProduct class is used to represent a product from the Spiff Hub integration. It is used to initialize a workflow experience.

This is the standard class to use when retrieving a product from the Spiff Hub integration.

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

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

integrationProduct.on("invalid", callback: (callbackOptions: object) => {
    // 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.
integrationProduct.confirmActive();
// or
integrationProduct.confirmActive().then((isValid) => {
    // isValid will be true if the product is valid.
});
// or
const isValid = await integrationProduct.confirmActive();

Product

The Product class is used to represent a product in your store. It is used to initialize a workflow experience.

This 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: string;
    // The identifier of the product on your e-commerce store.
    productId: string;
});

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

product.on("invalid", callback: (callbackOptions: object) => {
    // 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.
product.confirmActive();
// or
product.confirmActive().then((isValid) => {
    // isValid will be true if the product is valid.
});
// or
const isValid = await product.confirmActive();

HostedExperience

A hosted experience represents a single workflow experience for a customer. It's used as a handle by Spiff Commerce to the design of the customer.

const hostedExperience = new window.Spiff.HostedExperience({
    applicationKey: "<Required: You can pull this key from the e-commerce integration in Hub>",
    presentmentCurrency: "<Insert your desired presentment currency>",
    product: "<Your Product or IntegrationProduct, as above.>",
    embedElement: undefined, // Optional. The element to embed the workflow experience into. Modal otherwise.
    transactionId: undefined, // Optional. The ID of an existing transaction to load. This will allow the user to continue their design.
});
hostedExperience.on("complete", (result) => {
    // Called when the user has completed a design.
});
hostedExperience.on("quit", () => {
    // Called when the user has abandoned the experience.
});

// Returns a promise that resolves when the iframe has loaded.
hostedExperience.execute({
    workflowId: "<Insert optional workflow ID here>", // Optional. Provide a workflow ID to override selection screen.
    backdrop: "<Insert optional backdrop configuration here>", // Optional. Provide a backdrop ID to override selection screen.
});

Backdrop configuration

The backdrop can be used to modify the appearance of the background surrounding the modal. This value is ignored when running in embed mode. If providing a backdrop configuration all values must be included.

hostedExperience.execute({
    backdrop: {
        opacity: 0.5, // The opacity of the backdrop. Where 0 is totally invisible and 1 is fully opaque.
        color: "#000000", // The color of the backdrop. This can be any valid CSS color value.
    }
});

The result input for a HostedExperience complete callback has the following arguments:

Name	Type	Optional?	Description
baseCost	number	n	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.
exportedData	object	n	The metadata and variant selections recorded during the customization process.
optionsCost	number	n	Cumulative price of the variants selected by the consumer, in the subunits of the partner's currency.
previewImage	string	n	A URL to a preview image of the consumer's design.
processExecutionId	string	y	If a flow in flight was spawned, this is its ID.
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 hosted experience in the workflow viewer

Getting started​

Classes​

IntegrationProduct​

Product​

HostedExperience​

Backdrop configuration​