JavaScript Integration

Also see the SDK reference docs.

1. Load the SDK on your pages

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, nitialize 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.

2. Add the Purple Dot Button

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>

Positioning a placement

You can style the container element to position the button. The SDK will inject an iframe inside the container element to display the button and any positioning will be respected.

// Example of placing a Purple Dot button
<div class="add-to-cart-section">
<div data-purple-dot-placement-type="button" style="margin-top: 8px">
// This is where the button will be injected
</div>
</div>

Styling a placement

Because the placement is rendered inside an iframe, you cannot style the placement itself from your page. You can customise placements by passing a style object when loading or updating a placement (see below).

For a detailed guide on styling placements, see custom styling.

3. Configure the button

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>

Call the load() function and pass in the placementType of the placement you want to configure and the ID of the current product and optionally the currently selected variant, or null if no variant is selected by default.

4. Update the button when a variant is selected

When the selected variant changes, call the update() function to update the skuId.

// Example of updating the SKU on size change
function onSizeChange() {
// Your existing logic
// Call the SDK to update your placements
window.PurpleDot.update({ placementType: 'button', skuId: selectedVariant.id });
}

5. Subscribe to events

You can subscribe to events emitted by the SDK and forward them to your analytics and CRM integrations.

window.PurpleDot.on('OrderSubmitted', ({ sku }) => {
analytics.track('Purple Dot Order Submitted', { sku });
});

Next Steps