Skip to main content

JavaScript SDK

The PulpoAR SDK (@pulpoar/plugin-sdk) is a JavaScript library that lets your page communicate with the PulpoAR plugin running in an iframe. You can use it to:

  • Control the experience: apply variants, navigate between screens and manage the camera.
  • Listen to events: react to user actions such as selecting a shade or clicking Add to Cart.
  • Manage the catalog per user: update availability, visibility, prices and links for the current session.

Installation​

<script src="https://cdn.jsdelivr.net/npm/@pulpoar/plugin-sdk@latest/dist/index.iife.js"></script>
<script>
// The SDK is available as the global `pulpoar` object
pulpoar.onReady((project) => {
console.log('PulpoAR ready', project);
});

pulpoar.onVariantSelect((variant) => {
console.log('Variant selected', variant);
});

function applyMakeup() {
pulpoar.applyVariants(['lipstick-red', 'eyeshadow-brown']);
}
</script>

You can also load the SDK from other CDNs, such as unpkg.

Pin a version in production

The examples use @latest. In production, pin an exact version (for example @pulpoar/[email protected]) so updates can't change your integration unexpectedly.

How it works​

The SDK has two concepts:

  • Actions are functions you call to control the plugin, for example pulpoar.applyVariants([...]).
  • Events are callbacks the plugin fires when something happens, for example pulpoar.onAddToCart(callback).
// Event: register a callback
pulpoar.onAddToCart((variants) => {
variants.forEach((variant) => addToCart(variant));
});

// Action: send a command
pulpoar.applyVariants(['lipstick-red-001']);

Calls are queued​

You can call actions and register events right after loading the SDK. You don't need to wait for the iframe to load: calls made before the plugin is ready are queued and run once it is.

Using the SDK in a mobile WebView​

In a WebView, inject the SDK script into the loaded plugin page and forward events to native code. See WebView integration.

Next steps​