Javascript SDK API Reference

This reference documents objects and methods available in Purple Dot's browser-side JavaScript SDK.

Looking for a step-by-step guide? Learn how to use the SDK to create a placement.

Including the SDK

Include the purpledot.js script on your product pages. It should always be loaded directly from purpledotprice.com rather than in a bundle or hosted by yourself.

Before you start using the SDK, initialize it with your store's API key, which you can find in your Merchant Portal.

<script src="https://www.purpledotprice.com/api/v1/purpledot.js"></script>

<script>
  window.PurpleDot.init({ apiKey: '78596eb5-2ff3-473f-a23f-f31126309c62' });
</script>

If the script is included in the <head> element, it must be loaded without async or defer attributes. Any code using the SDK must be placed after the script tag.

If the script is included elsewhere, it can be loaded with async or defer attributes. Any code using the SDK must be wrapped in the PurpleDot:Ready event callback and placed before the script tag.

To best leverage Purple Dot's reporting capabilities, include the SDK on every page, not just the product display page.

Placing elements

To show a Purple Dot element, you need to specify a container element which the SDK uses to inject the element's iframe.

The container element must have a data-purple-dot-placement-type attribute set.

<div data-purple-dot-placement-type="button"></div>

Using the SDK

The SDK attaches a PurpleDot object to the global window object, which exposes the SDK's public API.

Before accessing window.PurpleDot, you must make sure it's ready.

Loading the script synchronously

If you're loading the script synchronously, include any code using the SDK after the purpledot.js script tag and any placements and access the SDK object directly.

<!-- Loading the SDK synchronously -->
<script src="https://www.purpledotprice.com/api/v1/purpledot.js"></script>

<!-- A placement -->
<div data-purple-dot-placement-type="button"></div>

<!-- Code using the SDK placed after purpledot.js and any placements -->
<script>
  // Initialize the SDK
  window.PurpleDot.init({ apiKey: '78596eb5-2ff3-473f-a23f-f31126309c62' });
  
  // Configure and load a placement
  window.PurpleDot.load({
    placementType: 'button',
    productId: '{% product.id %}',
    skuId: '{% current_variant.id %}',
    style: {
      fontFamily: '"Helvetica", sans-serif',
    },
  });
</script>

Loading the script asynchronously

If you're loading the script asynchronously, include any code using the SDK before the purpledot.js script tag and listen to the PurpleDot:Ready event which indicates that the SDK is loaded and ready.

<!-- Code using the SDK placed before purpledot.js -->
<script>
  // Listen for the ready event
  window.addEventListener('PurpleDot:Ready', () => {
    // Initialize the SDK
    window.PurpleDot.init({ apiKey: '78596eb5-2ff3-473f-a23f-f31126309c62' });

    // Configure and load a placement
    window.PurpleDot.load({
      placementType: 'button',
      productId: '{% product.id %}',
      skuId: '{% current_variant.id %}',
      style: {
        fontFamily: '"Helvetica", sans-serif',
      },
    });
  });
</script>

<!-- Loading the SDK asynchronously -->
<script src="https://www.purpledotprice.com/api/v1/purpledot.js" async></script>

`PurpleDot`

`init({ apiKey })`

Initialise the SDK with your store's public API key, which you can find in your Merchant Portal.

You only have to call init once.

// Replace the API key with your own
window.PurpleDot.init({ apiKey: '78596eb5-2ff3-473f-a23f-f31126309c62' });

`load({ placementType, productId, skuId, ... })`

Configure and load a Purple Dot element. Requires an element with a matching data-purple-dot-placement-type attribute to be present on the page when called.

placementType (required) - The type of the placement you want to load.
instanceId (optional) - Used in conjunction with a data-purple-dot-instance-id attribute if there are multiple instances of the same type.
productId (required) - The Shopify ID of the product.
skuId (optional) - The Shopify ID of the selected variant, if any.
lineItemProperties (optional) - Any custom properties to pass to Shopify with the pre-order.
fallbackToSoldOut (optional) - If set to true, the button will show as Sold Out when there isn't a waitlist configured for the product.
style (optional) - An object specifying the custom style to be applied the placement. See below for the possible values.
hoverStyle (optional) - Custom :hover style.
disabledStyle (optional) - Custom :disabled style.
labelStyle (optional) - Custom style for the label underneath the pre-order button.

window.PurpleDot.load({
    placementType: 'button',
    productId: product.id,
    skuId: selectedVariant.id,
    style: {
      fontFamily: '"Helvetica", sans-serif',
    },
  });

`update({ placementType, productId, skuId, lineItemProperties })`

Updates the pre-order button on variant change. Requires an element with data-purple-dot-placement-type that's been previously loaded to be present on the page when called.

placementType (required) - The type of the placement you want to update.
productId (optional) - The Shopify ID of a newly selected product.
skuId (optional) - The Shopify ID of a newly selected variant.
lineItemProperties (optional) - Any custom properties to pass to Shopify with the pre-order.

window.PurpleDot.update({
    placementType: 'button',
    productId: product.id,
    skuId: selectedVariant.id,
  });

`on(eventName, callback)`

Subscribe to an event emitted by the SDK. See the list of available events.

window.PurpleDot.on('PreorderCreated', ({ reference, email, shippingAddress, lineItems }) => {
  // Your callback
  analytics.track('Pre-order Created', { reference, email, shippingAddress, lineItems });
});

`off(eventName, callback)`

Unsubscribe from an event emitted by the SDK.

const trackPreorder = () => {
  analytics.track('Pre-order Created', { reference, email, shippingAddress, lineItems });
};

window.PurpleDot.on('PreorderCreated', trackPreorder);

window.PurpleDot.off('PreorderCreated', trackPreorder);

`setCustomerData(data)`

Provide customer data that will be used to pre-fill the checkout form. Currently only supported by the pre-orders checkout.

Accepts an object, a function or an async function that return an object. If given a function, it will be called when the checkout modal opens.

You can call setCustomerData() at any point before the checkout opens.

window.PurpleDot.setCustomerData({
  email: 'test@example.com',
  consentedToMarketing: true,
  address: {
    firstName: 'Test',
    lastName: 'Testington',
    line1: '5 Test House',
    line2: '123 Test St',
    city: 'Testville',
    postalCode: 'E14 1TT',
    country: 'GB',
    phoneNumber: '07123 45678',
  },
});

`fetchAvailability({ productId })`

productId - The store's ID of the product.

Wrapper for the GET /availability endpoint.

`fetchWaitlists()`

Wrapper for the GET /waitlists endpoint.

`loadPreorderStatusPage({ mode, token })`

mode - Must be either logged_in or guest.
token - A JWT containing the email, signed with your shared secret (logged_in mode only).

Loads the pre-order status iframe that shows the pre-orders history for a customer. Targets an element with data-purple-dot-placement-type set to pre-order-status-placement.

In logged_in mode, it shows the pre-order history for a customer based on their email address. The logged in customer's email is passed in as a token signed with your shared secret.

In guest mode, it lets the customer look up a pre-order using the pre-order number and the postcode associated with that pre-order.

These events are emitted by the pre-order status iframe:

ArrangeReturnClicked - the user clicked "Arrange Return" on a pre-order that has already been fulfilled.
PreorderCancelled - the user cancelled a pre-order before it was fulfilled.

<!-- Example of logged in mode integration for logged in customers -->
<div data-purple-dot-placement-type="pre-order-status-placement"></div>

<script>
  window.PurpleDot.init({ apiKey: '78596eb5-2ff3-473f-a23f-f31126309c62' });
  window.PurpleDot.loadPreorderStatusPage({
    mode: 'logged_in',
    token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6InRlc3RAdGVzdC5jb20iLCJpYXQiOjE2MDM5ODQ2Mjd9.usYrsQefcosDxGITzDBrVHCGyXAj5NBgOrsPOjHVQs0',
  });
  
  window.PurpleDot.on('ArrangeReturnClicked', ({ preorderReference }) => {
    // The customer clicked "arrange return"
  });
</script>

<!-- Example of guest mode integration for non-logged in customers -->
<div data-purple-dot-placement-type="pre-order-status-placement"></div>

<script>
  window.PurpleDot.init({ apiKey: '78596eb5-2ff3-473f-a23f-f31126309c62' });
  window.PurpleDot.loadPreorderStatusPage({
    mode: 'guest',
  });
  
  window.PurpleDot.on('ArrangeReturnClicked', ({ preorderReference }) => {
    // The customer clicked "arrange return"
  });
</script>

Generating the token

To keep the customer's pre-order history private, we verify that the request came from a trusted source based on the token passed in.

To generate the token, you need to create a JWT (JSON Web Token) with the email address of the customer and sign it with your shared secret (found in your Merchant Portal).

Before showing the pre-order history, we check that the signature matches the shared secret of your store and that the token is at most 1 hour old.

Example implementation in Node:

npm install jsonwebtoken

const jwt = require('jsonwebtoken');

const token = jwt.sign({ email: 'test@example.com' }, '<your_shared_secret>');

Keep in mind that the token should be generated by your backend only after you've verified that the user is logged in. Never generate the token in your client-side code so the shared secret is not leaked in your frontend.

The style object

Purple Dot lets you customise the look and feel of the price and button placements to match the visual design of your site.

Supported properties of the style object passed to the load() or update() functions:

fontFamily: The font-family applied to the placement.
fontSize: The base font-size applied to the placement. Some text elements are scaled relative to this size.
fontWeight: The font-weight applied to the placement.
color: The color applied to the placement.
lineHeight: The line-height applied to the placement.
letterSpacing: The letter-spacing applied to the placement.
textTransform: The text-transform applied to the placement.
textDecoration: The text-decoraction applied to the placement.
textAlign: (text only) The text-align applied to the placement.
height: The height of the placement.
width: The width of the placement.
border (button only): The border of the button.
borderRadius (button only): The border-radius of the button.
backgroundColor (button only): The background-color of the button;

window.PurpleDot.load({
  placementType: button',
  sku: 'SKU-123',
  style: {
    fontFamily: '"My Custom Font", Helvetica, sans-serif', // Use the custom font
    fontSize: '1 rem', // Set the font size
    height: '42px', // Set the placement's height
  },
});

Events

Events emitted by the SDK:

`PlacementLoaded`

A placement has finished loading or updating.

placementType - The type of the placement, e.g. button.
instanceId - The instance id of the placement.
sku - The SKU the placement is showing.
disabled - Whether the placement is disabled. Applicable to buttons.

`LearnMoreClicked`

The user opened the "Learn more" modal.

placementType - The type of the placement, e.g. button.
instanceId - The instance id of the placement.
sku - The SKU the placement is showing.

`ButtonClicked`

The user clicked the CTA and opened the checkout modal.

placementType - The type of the placement, e.g. button.
instanceId - The instance id of the placement.
sku - The SKU the placement is showing.

`PreorderCheckoutStep`

The user has seen a given step of the pre-order checkout.

stepName - The name of the step, e.g. 'Shipping' or 'Payment'
stepNumber - The index of the step.

`PreorderCheckoutSubmitted`

The user has submitted the checkout form. At this point, a pre-order hasn't been created yet, and it may fail, for example if the payment fails.

`PreorderCreated`

A pre-order has been created successfully.

reference - Purple Dot's reference for the pre-order, shown to the customer.
email - The customer's email.
shippingAddress - The shipping address used with the pre-order.
- firstName
- lastName
- addressLine1
- addressLine2
- city
- postalCode
- country
lineItems - An array of items that were pre-ordered.
- id - A unique ID of the line item.
- sku - The SKU of the item.
- properties - lineItemProperties, which were optionally passed to the checkout.
total - The total price of the pre-order.
- amount
- currency

`PreorderFailed`

A pre-order has failed, for example because the payment failed.

errorMessage - The error message that was shown to the user.

`PreorderCancelled`

A pre-order has been cancelled by the customer in the embedded pre-order history page.