Getting Started

To start using our SDK you must first construct a client. The client is the main entry point for interacting with Workflow Experiences. This object acts as a factory for building workflows & validating your access to the products and workflows you want to use.

Constructing a Client

The process for building a client is simple. First you'll need to pull the core SDK into your package. Check out the NPM package here

yarn add @spiffcommerce/core@latest

You can then construct a client and initialize a workflow experience. You'll need an application key to do this. You can get one by by creating an account on Spiff Commerce Hub and creating a new integration to represent your new application.

import { SpiffCommerceClient } from "@spiffcommerce/core";

// This constructs a new client with the given API Key
const client = new SpiffCommerceClient({ applicationKey: "0123456789" });

Once built the client should be stored for the lifetime of the users current visit. The client will manage authentication, initialization of product details and workflows.

Requesting a Workflow Experience

Before requesting an experience it's important to begin familiarizing yourself with the terminology we use. Workflows represent a core concept of our platform, make sure you understand their purpose before continuing. Other important concepts include scenes, steps and conditions.

You may use the client to get a Workflow Experience. Be sure to await the call. Failing to do so may mean that interactions with the design will error or cause issues with correctly displaying the initial state.

Be sure to have your product associated with your integration, and that the workflow you want to use is associated with that product. You'll need the product's integration ID, as well as the workflow's to request an experience. You can find the product's integration ID on the integration page, under the "Products" section. See the API reference for more details.

const experience = await client.getWorkflowExperience(
    undefined, // Deprecated: workflowId
    undefined, // Deprecated: workflowState
    undefined, // Optional: previewServiceConstructor
    {
        integrationProductId: "0123456789",
        workflowId: "0123456789",
        type: "integration",
    }
);

Requesting Multiple Workflow Experiences

note

This functionality is only available in version 14.13.0 and above.

There may be times when you wish to create many workflow experiences, particularly when combined with Bundles. Rather than calling getWorkflowExperience multiple times, you can use the function getWorkflowExperiences to create multiple workflow experiences at once. This function does not accept any of the previously deprecated parameters, nor does it accept a preview service constructor. Instead, you must pass an array of GetWorkflowOptions objects.

This function will return an array of workflow experiences, in the same order as the array of options you passed in. You may also mix the types of workflow experiences you request, for example: you may request to create a new workflow experience from an integration product, you may request to create one from an external integration, and you may request to read an existing transaction.

All options that request to create a new Transaction will be batched together. If any of these fail, no Transactions will be created.

Note that unlike getWorkflowExperience, the graphql options are passed in as a separate object, rather than being included in the GetWorkflowOptions object.

const experiences = await client.getWorkflowExperiences([
    {
        integrationProductId: "0123456789",
        workflowId: "0123456789",
        type: "integration",
    },
    {
        integrationProductId: "0123456789",
        workflowId: "0123456789",
        type: "integration",
    },
], {
    assets: {
        metaData: true, // Optional: Whether to include metadata in the response. Defaults to false.
    }
});

Getting Active Steps

Once you have a workflow experience you can get the steps that are available to the user. These steps represent the individual customizations a user can make to the product.

As the user makes selections the list of available steps can change. This is due to a system we call conditions. To know when the list of steps has changed due to a condition you can attach a listener to the experience. You should only render steps that are listed here to ensure the user can't interact with steps that are conditonally inactive.

// This listener will be called each time a change occurs to the list of steps that are active.
const onScenesChange = (scenes: RenderableScene[]) => {
    const renderableSteps = scenes.flatMap((s) => s.renderableSteps);
    const steps = workflowExperience.getSteps().filter((s) => renderableSteps.includes(s.getId()));
    this.steps = steps;
};

// Attach the listener right after the experience is constructed.
workflowExperience.attachRenderableSceneListener(onScenesChange);

// Later on...

// Detach when you no longer want to be updated or before disposing of a function.
workflowExperience.detachRenderableSceneListener(onScenesChange);

Rendering steps

Each step should map to a UI component in your frontend system. Typically you will loop over the list of renderable steps in fashion similar to below. An example is included of how this may look in react. Step handles contain a number of functions that can be used to interact with the step. Each type of step also has specific functionality as well.

See here for more information on handles and what kind of functionality you can use.

const steps = this.steps.map((step) => {
    return <StepComponent step={step} />;
});

Most steps have variants that the user may choose from. You can get the list of variants for a step by calling getAvailableVariants on the step. You can also get the currently selected variant by calling getCurrentVariant on the step.

// To list the currently available variants for a step.
const variants = step.getAvailableVariants();

// To select a variant, this will update the user selection for that step and change the design.
step.selectVariant(variant);

Often you will want to display a configured thumbnail for each variant on the step in some form of list or gallery. You can get the thumbnail for a variant by calling getThumbnail on the step handle.

const thumbnail = variant.getThumbnail();
// What you get is a href value similar to this "https://assets.us.spiffcommerce.com/my-cool-asset.png" You may use it like this.
<img href={thumbnail} />;

To learn more about the step interface see the step handles documentation.

Finishing a Design

When you're ready to submit a finished workflow to our platform you may use the following command on your workflow experience. You may also pass a callback to this function that will be called with a progress string as the design is submitted. This is useful for updating a progress bar.

const metadata = await workflowExperience.onDesignFinished((progressText: string) => {
    console.log(progressString);
});

This function returns a promise resolving to a metadata object. This object contains the metadata for the design that was submitted. Of all the data here the most important is the transaction ID. When you place an order into your store you need to annotate the line item representing this design with that transaction ID. When your e-commerce platform calls us about an order being place we'll look for that transaction ID and use it to associate the order with the design in our back end. If we don't have an official integration with your chosen e-commerce platform then you will need to store the transaction ID yourself and make a call to our server API with the transaction ID when you know the order was placed.

Placing an Order

Once you have finished a design you should store it as metadata on the line item representing the product in your e-commerce platform. For platforms we officially support we'll do this for you. But for any custom integration you'll need to do so yourself. When you're ready to place an order manually, you can call us using the GraphQL to make it known.