Developer

Introduction

Welcome to Spiff Development. This section of our help is primarily aimed at developers who are looking to build integrations with the Spiff platform. If you’re a merchant you might consider starting on a different page which provides a higher-level overview of spiff with less of a technical focus.

While Spiff is aimed at eCommerce the platform has been built from the ground up to be as flexible as possible. Any customer-facing HTML interface should be able to support a Spiff integration. It’s also possible to integrate with Spiff even if your platform is not geared towards eCommerce.

A Spiff integration consists of two components. First, there is a Javascript API that is hosted within the Spiff CDN. A Restful API which is available at api.spiff.com.au makes up the second part of the integration. The Javascript API can be accessed publicly while the Rest API is secured with a key and secret. The key and secret will be issued to you from the Spiff Hub and requires server to server requests. More detail on the key and secret can be found below. Both Spiff APIs need to be utilized to create a full end to end integration.

Before You Begin

Before you begin building any integration you will need to understand some key concepts of Spiff. The following list provides a summary of these concepts and acts as a checklist detailing what needs to be set up within the Spiff Hub.

  1. Spiff Account. You can sign up at hub.spiff.com.au
  2. Product. A product in Spiff should form a 1 to 1 relationship with the products you have set up in your existing platform. Note: there is no explicit link between your platform and Spiff. You will only need to create Spiff products for products within your site that you intend to make available for customisation.
  3. Workflow. This can be set up in the Spiff Hub which is accessed after signing up. Spiff Workflows are a detailed topic and more information can be found on their documentation page.
  4. Integration. To integrate with Spiff you will need to create an integration. For this list of ecommerce platforms, you can follow the step by step instructions. For all other platforms there are two concepts you need to be aware of which are covered in the Integration page. This process will show you how to create a public transaction and will provide you with the key and secret necessary to place a secure order.
  5. Integration Product. An integration product provides the link between a product and an integration. This can be created in SpiffHub from either the integration page or the product page. Copy the integration product id from the vertical ellipsis to the right of the integration product you want to link. For more detailed information

Integration Overview

As mentioned above, two phases constitute a Spiff integration. First is creating a public transaction with the Spiff Javascript API and second is creating an order based on that transaction with the Spiff Rest API. The Javascript portion of the integration would be ideally implemented within the templating system of your merchant frontend while the order portion should be implemented using backend code. In the case of popular eCommerce platforms such as Shopify and Bigcommerce this would be accomplished using a webhook.

Code Examples

The following is an example of a typical Javascript API integration. Note the comments in the code. They explain and link back to key concepts that have been outlined above. In the below all user variables are denotedt by two sets of curly brackets {{}}. See the table below for detals explaining each variable. Also remember to check the JavascriptAPI page for full details of the API.

// This function could run when the user clicks a customise button on your page.
function instantiateSpiffTransaction() {
    const integrationProduct = new window.Spiff.IntegrationProduct('{{integrationProductId}}');

    integrationProduct.on('ready', function() {
        const transaction = new window.Spiff.Transaction({
            presentmentCurrency: "AUD",
            integrationProduct: integrationProduct,
            embedElement: document.querySelector("#query-selector-on-my-product-page")
        });

        // We recommend displaying a spinner to the user at this point.
        document.querySelector('#a-spinner-for-the-button').style.visibility = 'visible';

        transaction.on('complete', function(event) {
            // In this case the user would provide the implementation for this function.
            addProductToMyCart(event.transactionId);
        })

        transaction.execute();
    })

    integrationProduct.on('invalid', function() {
        console.error("Spiff product could not be found")
    })

    integrationProduct.confirmActive()
}
variable explanation
integrationProductId This is the ID of the integration product. If you're customising more than one product we recommend extending your product backend entity so that this ID can be injected into the script automatically. To find the integration product ID login to the Spiff Hub and visit the product page.