Javascript SDK
This reference documents objects and methods available in Purple Dot's browser-side JavaScript SDK used in the Platform integrations.
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, initialise it with your Purple Dot store's public 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>
To add an item to the cart when the Purple Dot 'pre-order' button is clicked, you need to provide an implementation for
pdListeners.addItemToCart. This function takes one argument, which is the body of the request, and should handle adding to cart, and any other functionality that you want to execute when the 'pre-order' button is clicked, such as analytics.window.pdListeners = {
addItemToCart: (body) => {
// Your add-to-cart callback function here
}
}
For reference, this should be the shape of the request body:
{
items: [
{
id: data.externalId,
properties: {
...ShopifyBehaviour.hideProperties({
releaseId: data.releaseId,
presaleId: data.presaleId,
}),
'Purple Dot Pre-order': data.shipDates,
},
},
],
};
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 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>
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>
Initialise the SDK with your Purple Dot store's public API key, which you can find at the bottom of the Integration settings page 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' });
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 adata-purple-dot-instance-idattribute 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:hoverstyle.disabledStyle(optional) - Custom:disabledstyle.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',
},
});
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,
});
window.PurpleDot.on('PreorderCreated', ({ reference, email, shippingAddress, lineItems }) => {
// Your callback
analytics.track('Pre-order Created', { reference, email, shippingAddress, lineItems });
});
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);
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: '[email protected]',
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',
},
});
productId- The store's ID of the product.
mode- Must be eitherlogged_inorguest.token- A JWT containing the email, signed with your shared secret (logged_inmode 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 at the bottom of the Integration settings page in the 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: '[email protected]' }, '<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:afontFamily: Thefont-familyapplied to the placement.fontSize: The basefont-sizeapplied to the placement. Some text elements are scaled relative to this size.fontWeight: Thefont-weightapplied to the placement.color: Thecolorapplied to the placement.lineHeight: Theline-heightapplied to the placement.letterSpacing: Theletter-spacingapplied to the placement.textTransform: Thetext-transformapplied to the placement.textDecoration: Thetext-decoractionapplied to the placement.textAlign: (text only) Thetext-alignapplied to the placement.height: The height of the placement.width: The width of the placement.border(button only): Theborderof the button.borderRadius(button only): Theborder-radiusof the button.backgroundColor(button only): Thebackground-colorof 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 emitted by the SDK:
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.
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.
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.
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.
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.firstNamelastNameaddressLine1addressLine2citypostalCodecountry
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.amountcurrency
A pre-order has failed, for example because the payment failed.
errorMessage- The error message that was shown to the user.
A pre-order has been cancelled by the customer in the embedded pre-order history page.