@illumix-inc/hyperion-websdk v0.6.0
Illumix Hyperion Web SDK
Table of Contents:
Installation
NPM Module
Use npm to install the Illumix module:
npm install @illumix-inc/hyperion-websdkEnsuring Illumix is available everywhere
By default, this module will insert a <script> tag that loads illumix.umd.js. This happens as a side effect immediately upon importing this module. If you utilize code splitting or only include your JavaScript app on your checkout page, the illumix.umd.js script will only be available in parts of your site. To ensure Illumix is available everywhere, you can perform either of the following steps:
Import as a side effect
Import @illumix-inc/hyperion-websdk as a side effect in code that will be included throughout your site (e.g. your root module). This will make sure the illumix.umd.js script tag is inserted immediately upon page load.
import "@illumix-inc/hyperion-websdk";Manually include the script tag
Manually add the illumix.umd.js script tag to the <head> of each page on your site. If an existing script tag is already present, this module will not insert a new one. When you call initializeSDK, it will use the existing script tag.
<!-- Somewhere in your site's <head> -->
<script src="https://dist.illumix.com/web-sdk-shared/illumix.umd.js"></script>Getting Started
The initialization of the SDK differs slightly depending on whether you've included it via NPM or via Script Tag. Refer to the usage documentation below depending on your setup.
NPM Usage
The Illumix Hyperion Web SDK for JavaScript bundles TypeScript definition files for use in TypeScript projects and to support tools that can read .d.ts files. Also note that when imported via NPM, initializing the SDK is an asynchronous process.
initializeSDK
This function returns a Promise that resolves with a newly created IllumixSDK object once illumix.umd.js has loaded. If necessary, it will load illumix.umd.js for you by inserting the illumix.umd.js script tag. If you call initializeSDK in a server environment it will resolve to null.
Parameters
Takes an IllumixSDKConfig object with the following fields:
project_id <string>required: Project ID for the Product Try-On experiences this instance of the SDK will manage.app_key <string>required: App Key associated with this Project.user_id <string>optional: Set to the unique identifier used by your system to identify your users.auto_dispose <boolean>optional: If set to true, the SDK will automatically dispose of the iframe when the Try-On experience is stopped (ie. when the user clicks our "Close" button). Defaults to false.on_experience_closed <() => void>optional: Callback function that will be executed when users click our "Close" button to close the Try-On experience. Use this to implement custom functionality, such as redirecting users to another webpage.
Typescript Code Example
import { initializeSDK } from "@illumix-inc/hyperion-websdk";
// async/await example
const yourRedirectUrl = "http://your-redirect";
const IllumixSDK = await initializeSDK({
project_id: "89g3qh89q8heha8gha9hbta0",
app_key: "FVdsb_s_RXbdge1yB_30zV",
user_id: "ghArvcgLx",
on_experience_closed: () => {
// Do something on close, for example redirect users to another webpage
window.location.replace(yourRedirectUrl)
}
});
// promise example
const yourRedirectUrl = "http://your-redirect";
let IllumixSDK: IllumixSDK | null;
initializeSDK({
project_id: "89g3qh89q8heha8gha9hbta0",
app_key: "FVdsb_s_RXbdge1yB_30zV",
user_id: "ghArvcgLx",
on_experience_closed: () => {
// Do something on close, for example redirect users to another webpage
window.location.replace(yourRedirectUrl)
}
}).then((sdk) => {
IllumixSDK = sdk;
/* ... */
})
.catch((reason) => { /* ... */ });We’ve placed random credentials key in this example. Replace it with your actual publishable API keys to test this code through your Illumix account.
Script Tag Usage
When including the Illumix script tag in your HTML document, initializing the SDK is a synchronous process accessed via the window.Illumix global object.
window.Illumix.initializeSDK
This function returns a newly created IllumixSDK object.
Parameters
Takes an IllumixSDKConfig object with the following fields:
project_id <string>required: Project ID for the Product Try-On experiences this instance of the SDK will manage.app_key <string>required: App Key associated with this Project.user_id <string>optional: Set to the unique identifier used by your system to identify your users.auto_dispose <boolean>optional: If set to true, the SDK will automatically dispose of the iframe when the Try-On experience is stopped (ie. when the user clicks our "Close" button). Defaults to false.on_experience_closed <() => void>optional: Callback function that will be executed when users click our "Close" button to close the Try-On experience. Use this to implement custom functionality, such as redirecting users to another webpage.
Code Example
const yourRedirectUrl = "http://your-redirect";
let IllumixSDK = window.Illumix.initializeSDK({
project_id: "89g3qh89q8heha8gha9hbta0",
app_key: "FVdsb_s_RXbdge1yB_30zV",
on_experience_closed: () => {
// Do something on close, for example redirect users to another webpage
window.location.replace(yourRedirectUrl)
}
});
IllumixSDK.start({ sku: "E2c3af572311a23109df0f76" });We’ve placed random credentials key in this example. Replace it with your actual publishable API keys to test this code through your Illumix account.
API
Once you've initialied the SDK, the IllumixSDK object has a consistent API outlined below.
start
You can begin the Try-On experience by invoking the start function with the SKU (item ID) parameter. This will open a full-screen window showing the experience.
Parameters
Takes a configuration object with the following fields:
sku <string>required: Product unique identifier for the Virtual Try-On item.mountNode <string | HTMLElement>optional: If an element ID string or HTMLElement is provided, the Virtual Try-On iframe will be appended to the given element. Otherwise, the iframe will be appended to the document body as a full-screen window.relatedSKUs <string[]>optional: Array of related SKUs to show in a recommendations UI. When a related SKU is selected by the user, it will be loaded for viewing within the same Try-On instance.
Code Example
// async/await example
await IllumixSDK.start({ sku: "3134-5254-153", relatedSKUs: ["1111-1111-111", "2222-2222-222"] });
// promise example
IllumixSDK.start({ sku: "3134-5254-153", relatedSKUs: ["1111-1111-111", "2222-2222-222"] })
.then(() => { /* ... */})
.catch((reason) => { /* ... */ });stop
The Try-On experience window will have an "X" button to close the experience. If you need to close the experience programmatically, you can invoke the stop function.
Parameters
This function takes no parameters.
Code Example
IllumixSDK.stop();preload
Each item experience will require asset(s) when started. You can improve the start up time by downloading the necessary item assets ahead of time by invoking preload function with appropriate SKU parameter.
Parameters
Takes a configuration object with the following fields:
sku <string>required: Product unique identifier for the Virtual Try-On item.relatedSKUs <string[]>optional: Array of related SKUs to show in a recommendations UI. When a related SKU is selected by the user, it will be loaded for viewing within the same Try-On instance.
Code Example
// async/await example
await IllumixSDK.preload({ sku: "3134-5254-153", relatedSKUs: ["1111-1111-111", "2222-2222-222"] });
// promise example
IllumixSDK.preload({ sku: "3134-5254-153", relatedSKUs: ["1111-1111-111", "2222-2222-222"] })
.then(() => { /* ... */})
.catch((reason) => { /* ... */ });onPurchase
Callback to track when items are purchased. Each object provided should have a unique sku, if multiple of the same item were purchased then use the quantity field.
Parameters
Takes an array of PurchasedItem objects with the following fields:
sku <string>required: Purchased item’s SKU.price <number>required: The price of the purchased item after discount and promotions but before any taxes, fees and shipping.currency <string>optional: 3-letter ISO 4217 currency code. Defaults to “USD” if not provided.quantity <number>optional: Number of items purchased. Defaults to 1 if not provided.
Code Example
// async/await example
await IllumixSDK.onPurchase([{ sku: "diamond-ring-1", price: 888.88 }, {sku: "gold-ring-1", price: 500.00, currency: "USD", quantity: 2}]);
// promise example
IllumixSDK.onPurchase([{ sku: "diamond-ring-1", price: 888.88 }, {sku: "gold-ring-1", price: 500.00, currency: "USD", quantity: 2}])
.then(() => { /* ... */})
.catch((reason) => { /* ... */ });getClientId
Accessor to get your Illumix ClientId.
Parameters
This function takes no parameters.
Code Example
const clientId = IllumixSDK.getClientId();