Javascript API

The Spiff3D API provides programmatic access to our most important features. The library will be pulled in and available automatically when you have the Spiff3D plugin installed on compatible stores. For all other situations you will have to pull the library in manually by including the script in your page instead.

SpiffApiReady

This event is fired on the window object when the Javascript API is ready to use. If the Javascript API is being loaded asynchronously then you can ensure that your code has access to the API by wrapping it in a callback that waits for this event to fire.

Usage

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

IntegrationProduct

Constructor

new window.Spiff.IntegrationProduct(integrationProductId)

Argument Type Description
integrationProductId string The ID of the integration product. This value will be shown on the product's page in the Spiff Hub.

Usage

const integrationProduct = new window.Spiff.IntegrationProduct("649dfe36-bd0a-447e-a9f9-67bff7bc9a96");

on(eventName: string, callback: (callbackOptions: object) => void): void

Register a callback method on the product object. There are different kinds of callbacks detailed in the table below.

Callback Description
ready The product has been determined to exist in Spiff's database and is enabled.
invalid Spiff could not find the product or it is not enabled.

confirmActive(): void

Confirm that the configured product exists and is enabled. Calling this method and waiting for the "ready" event to fire is required before a transaction may be created.

Product

Constructor

new window.Spiff.Product(productOptions)

ProductOptions

Option Type Description
integrationId string The unique identifier for your integration as known by your ecommerce platform. If you're not sure what this value is you can check it in the Spiff Hub. In the case of Shopify it will be the URL to your store e.g. "store.myshopify.com"
productId string The ID of your product displayed within your ecommerce platform. In the case of Shopify it will be a number like "3584328925261"

Usage

const productOptions = {
    integrationId: "example.myshopify.com",
    productId: "1234"
};
const product = new window.Spiff.Product(productOptions);

on(eventName: string, callback: (callbackOptions: object) => void): void

Register a callback method on the product object. There are different kinds of callbacks detailed in the table below.

Callback Description
ready The product has been determined to exist in Spiff's database and is enabled.
invalid Spiff could not find the product or it is not enabled.

confirmActive(): void

Confirm that the configured product exists and is enabled. Calling this method and waiting for the "ready" event to fire is required before a transaction may be created.

Transaction

When ordering product on spiff a client needs to first create a transaction. A transaction represents all of the the customer's personalisation data for a given item in a given order order. Once created the transaction is saved in the spiff platform and ready for order. If your using the Spiff shopify application this ordering process happens by attaching the spiff transactionId to a line item. Spiff will then listen for orders with spiff transaction Id's and route the order to the approate store / location. The Spiff platfrom also has solutions for many advanced routing options.

Constructor

new window.Spiff.Transaction(transactionOptions: object)

Parameter: Transaction Options

The set of options to create the transaction with. See below table for constructing the options.

Option Type Optional? Description
integrationProduct IntegrationProduct no (unless product is specified instead) A Spiff integration product which has been confirmed to be active.
presentmentCurrency string no The currency that the transaction amount should be calculated in. This should be set to what ever currency the users chooses to pay in. Use standard three letter currency codes such as "USD", "GBP" and "AUD"
product Product no (unless integrationProduct is specified instead) A Spiff product which has been confirmed to be active.
shouldCreateDesignProduct boolean yes A flag that will create a "design product" on your eCommerce. Currently this is only supported on shopify. Note in the on complete callback of the transaction this productId will be returned as designProductId allow you to add it to your cart
embedElement DOMElement yes The JavascriptDOM element you would like the spiff workflow Iframe to be inserted. Note if you don't set this Spiff will add the Iframe with a modal style treatment. Note as well if you do provide a DOM element the on quit callback will never be called. Note that when providing an embed element you will need to make sure that your container element has a height. Currently a height of 0 will result in an error.
pageSessionId string yes Use this to begin the sequence of events of what the user will potentially go through, which allows us to give you all the analytics necessary for that process.

Usage

const transactionOptions = {
    presentmentCurrency: "USD",
    integrationProduct: intgrationProduct, // See Spiff.IntegrationProduct
    shouldCreateDesignProduct: true,
    embedElement: document.querySelector("#spiff-workflow-container")
};
const transaction = new window.Spiff.Transaction(transactionOptions);

on(eventName: string, callback: (callbackOptions: object) => void): void

Registering callback methods with a given transaction is done via the on method. There are different kinds of callbacks detailed in the table below.

Callback Description
complete Called when the user has completed the transaction.
quit Called when the user has stopped the customisation process. Note that in this case no transactionId will be issued.

Complete Callback

When a user has completed their transaction the complete callback provided will be called with a single result parameter detailed below.

Name Type Optional? Description
baseCost number no The base cost of the item. This is based on the price of the spiff item and may be different in the e-Commernce platform. Costs will always be returned in subunits
designProductId string yes This will be set if the transaction has been setup to create a design product. Note this is currently only supported by shopify. If a design product has not been created it is up to the integration to either setup a different means of attaching the transactionId to the order or attaching the transactionId to the meta data of the approate line item.
designProductVariantId string yes This will be set if the transaction has been setup to create a design product and the eCommerce platform supports variants. Note this is currently only supported by shopify. If a design product has not been created it is up to the integration to either setup a different means of attaching the transactionId to the order or attaching the transactionId to the meta data of the approate line item.
exportedData object no The metadata and variant selections recorded during the customisation process. This will vary depending on the configured workflow.
optionsCost number no Options cost will be calculated based on the users selected options. This will differ from product to product. See the options selection in the spiff hub for more details. Will be set to zero if no options are avaiable
previewImage string no A url to a preview image that has been generated from the users design. This can be then hotlinked to from any where in the merchant shop
transactionId string no The transactionId assigned to the created transaction. Note this will only be created if the user completes the workflow process.

The exportedData object has the following structure:

{
    [name: string]: {
        value: string,
        priceModifier: number,
    }
}

Each name-value pair corresponds to a row seen by the customer in the order summary on the final screen of a workflow.

Usage

// called when the user has completed their transaction
transaction.on('complete', (result) => {
    console.log(result.exportedData);
    console.log(result.transactionId);
    console.log(result.designProductId);
    console.log(result.designProductVariantId);
    console.log(result.baseCost);
    console.log(result.optionsCost);
    console.log(result.previewImage);
});

Quit Callback

The quit callback is called if the transaction has been created with out a DOM element and the user as closed the modal before completing the transaction. In the case of quit no design will be created and the resulting transaction should be discarded. If the user wants to customise after this point a new transaction should be created.


// Called if the user quit early
transaction.on('quit', () => {
    console.log("The user exited before completing their design");
});

execute(transactionExecutionOptions: object): Promise<void>

Calling execute will trigger the created transaction to create and render the Iframe according to how the transaction has been configured. If no DOMElement was been provided when setting up the transaction, calling execute will open the spiff modal. If a DOM Element has been added then the workflow will render in that provided element. The promise returned by this method will resolve once the transaction has been set up. Given the user might have a slow connection it might be worth displaying some sort of loading queue at this point. Once the promise resolves hide the loading state. Note as well this method will not timeout so setting a time out of perhaps 10 seconds might be a good idea.

Parameter: transactionExecutionOptions

An optional object which specifies additional data required to execute the transaction. This object has the following attributes:

Name Type Optional? Description
workflowId string yes The ID of the workflow to open. This allows skipping the workflow selection screen for a product linked to multiple workflows.

Usage

transaction.execute({
  workflowId: "b8e12640-c5b0-4f1c-b8ed-6eb025b930ea"
});

Analytics

When beginning the process of analytics on Spiff you first need to access the API that gets placed on the window called Analytics. This allows you to now access the createPageSession() method. First delcare your `pageSessionId outside of the event listener`.

Usage

var pageSessionId;
window.addEventListener('SpiffApiReady', function() {
    // snippet code
});

The createPageSession() method should be called within the ready event listener which will then fire a pageSessionCreate event when the user is on the product page with the rendered customise me button.

Usage

product.on('ready', () => {
    if (pageSessionId === undefined) {
        pageSessionId = window.Spiff.Analytics.createPageSession();
    }
});

You then must pass the pageSessionId into the transaction options to fire off the transactionCreate event which will be called when the user presses the customise me button.

Usage

const transactionOptions = {
       presentmentCurrency: '{{cart.currency.iso_code}}',
       product: product,
       shouldCreateDesignProduct: true,
       pageSessionId
};