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.
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.
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>
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.
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 SDKwindow.PurpleDot.init({ apiKey: '78596eb5-2ff3-473f-a23f-f31126309c62' });// Configure and load a placementwindow.PurpleDot.load({placementType: 'button',productId: '{% product.id %}',skuId: '{% current_variant.id %}',style: {fontFamily: '"Helvetica", sans-serif',},});</script>
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 eventwindow.addEventListener('PurpleDot:Ready', () => {// Initialize the SDKwindow.PurpleDot.init({ apiKey: '78596eb5-2ff3-473f-a23f-f31126309c62' });// Configure and load a placementwindow.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 ownwindow.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 callbackanalytics.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>
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.
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 fontfontSize: '1 rem', // Set the font sizeheight: '42px', // Set the placement's height},});
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.