Selektable

https://docs.selektable.com
Admin
Selektable is an AI-powered product visualization platform for e-commerce that enables customers to...
Tokens:32,072
Snippets:160
Trust Score:4.8
Update:7 months ago
Show doc for...
Tokens:
Raw
### Full Product Page Integration with Selektable HTML and JavaScript

Source: https://docs.selektable.com/guides/custom-store

A complete example of integrating Selektable into a product page. It includes basic HTML for product display, a button to trigger the visualizer, and JavaScript to initialize Selektable with product details and cart callbacks.

```html
<!DOCTYPE html>
<html>
<head>
  <title>Modern Blue Sofa - My Shop</title>
</head>
<body>
  <h1>Modern Blue Sofa</h1>
  <img src="https://myshop.com/images/sofa.jpg" alt="Modern Blue Sofa" />
  <p>$899.00</p>

  <button onclick="addToCart()">Add to Cart</button>
  <button onclick="openVisualizer()">View in Your Room</button>

  <script src="https://app.selektable.com/widgets/embed.js" data-store-id="store_xxx" async></script>
  <script>
    function openVisualizer() {
      Selektable.open('widget_abc123', {
        productId: 'sofa-001',
        productTitle: 'Modern Blue Sofa',
        productImage: 'https://myshop.com/images/sofa.jpg',
        productImages: [
          { id: 1, src: 'https://myshop.com/images/sofa.jpg', alt: 'Front view' }
        ],
        productUrl: window.location.href,

        onAddToCart: async function (product, quantity) {
          const res = await fetch('/api/cart/add', {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({ productId: product.id, quantity })
          });
          return { success: res.ok };
        },

        onViewCart: function () {
          window.location.href = '/cart';
        },

        onCheckout: function () {
          window.location.href = '/checkout';
        }
      });
    }
  </script>
</body>
</html>
```

--------------------------------

### Customer Identification

Source: https://docs.selektable.com/guides/custom-store

Associates a visitor with their user ID for enhanced tracking.

```APIDOC
## Selektable.identify(userId, userProperties)

### Description
Identifies a customer with a unique user ID and associated properties.

### Method
JavaScript Function Call

### Parameters
- **userId** (string) - Required - The unique identifier for the user.
- **userProperties** (object) - Optional - An object containing user properties.
  - **name** (string) - The name of the user.
  - **email** (string) - The email address of the user.

### Request Example
```javascript
Selektable.identify('user-123', {
  name: 'John Doe',
  email: 'john@example.com'
});
```
```

--------------------------------

### Trigger Widget via Data Attributes

Source: https://docs.selektable.com/guides/custom-store

Use HTML data attributes for a declarative setup. Elements are registered via Selektable.discover(), though the widget must still be opened via a trigger.

```html
<div
  data-selektable-widget="widget_abc123"
  data-product-id="prod-456"
  data-product-title="Modern Blue Sofa"
  data-product-images='[{"id":1,"src":"https://myshop.com/images/sofa.jpg","alt":"Sofa"}]'
  data-product-url="https://myshop.com/products/modern-blue-sofa"
>
  <button type="button">View in your room</button>
</div>

<script>
  Selektable.discover();
</script>
```

--------------------------------

### Open Selektable Widget with Product Data (HTML/JavaScript)

Source: https://docs.selektable.com/quickstart

This HTML button, when clicked, triggers the Selektable widget to open using JavaScript. It requires the Widget ID and can optionally pass product details such as ID, title, image, and URL. Ensure the Selektable library is loaded before this button is clicked.

```html
<button onclick="Selektable.open('widget_abc123', {
  productId: 123,
  productTitle: 'Blue Sofa',
  productImage: 'https://example.com/product.jpg',
  productUrl: 'https://example.com/products/blue-sofa'
})">
  View in your room
</button>
```

--------------------------------

### Cart Integration Callbacks

Source: https://docs.selektable.com/guides/custom-store

Callbacks for handling 'Add to Cart', 'View Cart', and 'Checkout' actions within the Selektable widget.

```APIDOC
## POST /api/cart/add

### Description
Handles the addition of a product to the shopping cart.

### Method
POST

### Endpoint
/api/cart/add

### Parameters
#### Request Body
- **productId** (string) - Required - The unique identifier for the product.
- **quantity** (number) - Required - The number of units to add to the cart.
- **variation** (array) - Optional - An array of objects specifying product variations, e.g., `[{ attribute: 'color', value: 'blue' }]`.

### Request Example
```json
{
  "productId": "prod-456",
  "quantity": 1,
  "variation": [
    { "attribute": "color", "value": "blue" }
  ]
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the add to cart operation was successful.
- **error** (string) - An error message if the operation failed.
- **cartUrl** (string) - Optional URL to redirect the user to after adding the item to the cart.

#### Response Example
```json
{
  "success": true,
  "error": null,
  "cartUrl": "/cart"
}
```
```

```APIDOC
## GET /cart

### Description
Redirects the user to the shopping cart page.

### Method
GET

### Endpoint
/cart
```

```APIDOC
## GET /checkout

### Description
Redirects the user to the checkout page.

### Method
GET

### Endpoint
/checkout
```

--------------------------------

### JavaScript Example: Opening Selektable with Product Options

Source: https://docs.selektable.com/sdk/product-options

Demonstrates how to open the Selektable widget with specific product information, including dimensions for accurate AI rendering. This example shows setting product ID, title, image, and physical measurements.

```javascript
Selektable.open('widget_abc123', {
  productId: 'sofa-001',
  productTitle: 'Modern Blue Sofa',
  productImage: 'https://myshop.com/images/sofa.jpg',
  dimensions: {
    width: 220,
    height: 85,
    depth: 95,
    unit: 'cm'
  }
});
```

--------------------------------

### Initialize and open Selektable widget

Source: https://docs.selektable.com/sdk/examples/basic-usage

Demonstrates the minimal setup required to load the SDK and trigger the widget using a button click with basic product metadata.

```html
<script src="https://app.selektable.com/widgets/embed.js" async></script>

<button onclick="Selektable.open('widget_abc123', {
  productId: 'sofa-001',
  productTitle: 'Modern Blue Sofa',
  productImage: 'https://myshop.com/images/sofa.jpg'
})">
  View in your room
</button>
```

--------------------------------

### Order Webhooks API

Source: https://docs.selektable.com/guides/custom-store

Endpoint for receiving order data from your store to track conversions.

```APIDOC
## POST https://app.selektable.com/api/webhooks/orders

### Description
Receives order data to enable conversion attribution in Selektable analytics.

### Method
POST

### Endpoint
https://app.selektable.com/api/webhooks/orders

### Parameters
#### Request Body
- **orderId** (string) - Required - The unique identifier for the order.
- **storeId** (string) - Required - The identifier for the store.
- **customerEmail** (string) - Required - The email address of the customer.
- **items** (array) - Required - An array of items included in the order.
  - **productId** (string) - Required - The identifier for the product.
  - **quantity** (number) - Required - The quantity of the product ordered.
  - **price** (number) - Required - The price of the product.
- **total** (number) - Required - The total amount of the order.
- **currency** (string) - Required - The currency of the order (e.g., 'EUR').

### Request Example
```json
{
  "orderId": "order-789",
  "storeId": "store_xxx",
  "customerEmail": "customer@example.com",
  "items": [
    {
      "productId": "prod-456",
      "quantity": 1,
      "price": 899.00
    }
  ],
  "total": 899.00,
  "currency": "EUR"
}
```

### Response
#### Success Response (200)
- (No specific response body defined, typically an acknowledgment of receipt)

#### Response Example
(Empty or a simple success status)
```

--------------------------------

### Handle Asynchronous SDK Loading

Source: https://docs.selektable.com/sdk/installation

Demonstrates safe patterns for interacting with the SDK methods, ensuring the library is loaded before execution via conditional checks or event listeners.

```html
<script>
  // Option 1: Check before calling
  function openWidget() {
    if (window.Selektable) {
      Selektable.open('widget_abc123', { ... });
    }
  }
</script>
```

```html
<script>
  // Option 2: Wait for load event
  window.addEventListener('load', function () {
    Selektable.preload('widget_abc123');
  });
</script>
```

--------------------------------

### Verify SDK Installation

Source: https://docs.selektable.com/sdk/installation

Checks if the Selektable SDK has successfully initialized in the browser environment by inspecting the global window object.

```javascript
console.log(window.Selektable);
```

--------------------------------

### Manage Multiple Widgets

Source: https://docs.selektable.com/sdk/installation

Shows how to trigger different widget instances from a single page using the shared Selektable SDK registry.

```html
<!-- One script tag -->
<script src="https://app.selektable.com/widgets/embed.js" data-store-id="store_xxx" async></script>

<!-- Multiple widgets -->
<button onclick="Selektable.open('widget_room')">Room Visualizer</button>
<button onclick="Selektable.open('widget_tryon')">Virtual Try-On</button>
```

--------------------------------

### Troubleshoot Selektable SDK Loading JavaScript

Source: https://docs.selektable.com/guides/custom-store

Provides a JavaScript snippet to check if the Selektable SDK has loaded before attempting to use its functions. This prevents errors if the `Selektable` object is undefined due to asynchronous script loading.

```javascript
if (window.Selektable) {
  Selektable.open('widget_abc123', { ... });
} else {
  console.error('Selektable SDK not loaded yet');
}
```

--------------------------------

### Trigger Widget via JavaScript API

Source: https://docs.selektable.com/guides/custom-store

Use the Selektable.open() method to programmatically trigger the widget. This approach requires passing product metadata, including IDs, titles, and image arrays.

```javascript
<button id="try-on-btn" type="button">View in your room</button>

<script>
  document.getElementById('try-on-btn').addEventListener('click', function () {
    Selektable.open('widget_abc123', {
      productId: 'prod-456',
      productTitle: 'Modern Blue Sofa',
      productImage: 'https://myshop.com/images/sofa-main.jpg',
      productImages: [
        { id: 1, src: 'https://myshop.com/images/sofa-front.jpg', alt: 'Front view' },
        { id: 2, src: 'https://myshop.com/images/sofa-side.jpg', alt: 'Side view' },
        { id: 3, src: 'https://myshop.com/images/sofa-back.jpg', alt: 'Back view' }
      ],
      productUrl: 'https://myshop.com/products/modern-blue-sofa'
    });
  });
</script>
```

--------------------------------

### Vue Integration with Selektable Widget

Source: https://docs.selektable.com/sdk/examples/advanced

This Vue 3 component demonstrates integrating the Selektable widget. It defines a `setup` script to handle opening the widget when a button is clicked. The `openWidget` function checks for the Selektable API, configures the widget with product data, and includes an `onAddToCart` handler that makes a POST request to an API endpoint.

```vue
<template>
  <button @click="openWidget">View in your room</button>
</template>

<script setup>
const props = defineProps(['product']);

function openWidget() {
  if (!window.Selektable) return;

  window.Selektable.open('widget_abc123', {
    productId: props.product.id,
    productTitle: props.product.name,
    productImage: props.product.images[0]?.url,
    productImages: props.product.images.map((img, i) => ({
      id: i,
      src: img.url,
      alt: img.alt
    })),
    productUrl: window.location.href,

    async onAddToCart(product, quantity) {
      const res = await fetch('/api/cart', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ productId: product.id, quantity })
      });
      return { success: res.ok };
    }
  });
}
</script>
```

--------------------------------

### Install Selektable SDK via Script Tag

Source: https://docs.selektable.com/sdk/installation

Embeds the Selektable SDK into a webpage. The script should be placed before the closing body tag and requires a unique Store ID.

```html
<script src="https://app.selektable.com/widgets/embed.js" data-store-id="store_xxx" async></script>
```

--------------------------------

### Webhook POST Request Example

Source: https://docs.selektable.com/guides/conversion-tracking

This example demonstrates how to construct a POST request to the Selektable webhook endpoint for order notifications. It includes the necessary URL, Authorization header, and Content-Type.

```http
POST https://app.selektable.com/api/webhooks/orders
Authorization: Bearer sel_your_api_key
Content-Type: application/json
```

--------------------------------

### Add Products to Cart with Selektable JavaScript

Source: https://docs.selektable.com/guides/custom-store

Implements cart functionality by providing callback functions to Selektable.open(). The onAddToCart callback handles adding products to the cart via a POST request and returns success status and an optional cart URL. onViewCart and onCheckout handle navigation.

```javascript
Selektable.open('widget_abc123', {
  productId: 'prod-456',
  productTitle: 'Modern Blue Sofa',
  productImage: 'https://myshop.com/images/sofa.jpg',

  // Cart callbacks
  onAddToCart: async function (product, quantity, variation) {
    // product: { id, title, price?, image? }
    // quantity: number
    // variation: [{ attribute: 'color', value: 'blue' }] (optional)

    const response = await fetch('/api/cart/add', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        productId: product.id,
        quantity: quantity,
        variation: variation
      })
    });

    return {
      success: response.ok,
      error: response.ok ? undefined : 'Failed to add to cart',
      cartUrl: '/cart'  // Optional: URL to redirect after adding
    };
  },

  onViewCart: function () {
    window.location.href = '/cart';
  },

  onCheckout: function () {
    window.location.href = '/checkout';
  }
});
```

--------------------------------

### Open Selektable Widget with Initial Product Data

Source: https://docs.selektable.com/sdk/examples/multi-product

This JavaScript code snippet demonstrates how to open a Selektable widget with initial product details. It's used when starting a multi-product visualization session, providing the first product for the customer to view.

```javascript
Selektable.open('widget_room', {
  productId: 'sofa-001',
  productTitle: 'Modern Blue Sofa',
  productImage: 'https://myshop.com/images/sofa.jpg',
  productImages: [
    { id: 1, src: 'https://myshop.com/images/sofa.jpg', alt: 'Blue Sofa' }
  ]
});
```

--------------------------------

### Identify Customers with Selektable JavaScript

Source: https://docs.selektable.com/guides/custom-store

Associates a website visitor with their user ID for enhanced tracking. This function should be called after a user logs in or when the page loads with an authenticated user, providing their unique ID, name, and email.

```javascript
// After login or page load with authenticated user
Selektable.identify('user-123', {
  name: 'John Doe',
  email: 'john@example.com'
});
```

--------------------------------

### Selektable Widget Data Attributes Example

Source: https://docs.selektable.com/sdk/methods

An example of an HTML element configured with Selektable data attributes to define widget context. These attributes, such as `data-selektable-widget`, `data-product-id`, `data-product-title`, and `data-product-images`, are used by the `Selektable.discover()` method.

```html
<div data-selektable-widget="widget_abc123"
     data-product-id="456"
     data-product-title="Blue Sofa"
     data-product-images='[{"id":1,"src":"https://example.com/sofa.jpg","alt":"Sofa"}]'>
</div>
```

--------------------------------

### Full Example: Product Page Tracking Widget Events to GA4

Source: https://docs.selektable.com/guides/analytics-events

This HTML example demonstrates a product page that includes the Selektable widget embed script and a JavaScript listener to track all widget events to Google Analytics 4. It includes a button to open the widget and sends events like 'selektable_widget_open', 'selektable_add_to_cart', etc., to GA4.

```html
<button onclick="openWidget()">View in your room</button>

<script src="https://app.selektable.com/widgets/embed.js" async></script>

<script>
  function openWidget() {
    Selektable.open('widget_abc123', {
      productId: 'prod-456',
      productTitle: 'Modern Blue Sofa',
      productImage: 'https://myshop.com/images/sofa.jpg'
    });
  }

  // Track all widget events
  window.addEventListener('message', function (event) {
    var data = event.data;
    if (!data || !data.type || data.type.indexOf('widget:') !== 0) return;

    // Send every widget event to GA4
    gtag('event', 'selektable_' + data.type.replace('widget:', ''), {
      store_id: data.storeId,
      product_id: data.product ? data.product.id : undefined,
      product_name: data.product ? data.product.title : undefined,
      error_message: data.error || undefined
    });
  });
</script>
```

--------------------------------

### React Integration with Selektable Widget

Source: https://docs.selektable.com/sdk/examples/advanced

This React component demonstrates how to integrate the Selektable widget into a product page. It uses the `useCallback` hook to create a memoized function that opens the widget with product details and handles the `onAddToCart` event, ensuring the Selektable API is available before attempting to open the widget.

```jsx
import { useCallback } from 'react';

function ProductPage({ product }) {
  const openWidget = useCallback(() => {
    if (!window.Selektable) return;

    window.Selektable.open('widget_abc123', {
      productId: product.id,
      productTitle: product.name,
      productImage: product.images[0]?.url,
      productImages: product.images.map((img, i) => ({
        id: i,
        src: img.url,
        alt: img.alt
      })),
      productUrl: window.location.href,

      onAddToCart: async (cartProduct, quantity) => {
        const res = await addToCart(cartProduct.id, quantity);
        return { success: res.ok };
      }
    });
  }, [product]);

  return (
    <button onClick={openWidget}>
      View in your room
    </button>
  );
}
```

--------------------------------

### Svelte Integration with Selektable Widget

Source: https://docs.selektable.com/sdk/examples/advanced

This Svelte component shows how to integrate the Selektable widget. It defines a reactive prop `product` and an `openWidget` function that is triggered by a button's `onclick` event. The function ensures the Selektable API is loaded, configures the widget with product details, and includes an `onAddToCart` callback for handling add-to-cart actions via a fetch request.

```svelte
<script>
  let { product } = $props();

  function openWidget() {
    if (!window.Selektable) return;

    window.Selektable.open('widget_abc123', {
      productId: product.id,
      productTitle: product.name,
      productImage: product.images[0]?.url,
      productImages: product.images.map((img, i) => ({
        id: i,
        src: img.url,
        alt: img.alt
      })),
      productUrl: window.location.href,

      async onAddToCart(cartProduct, quantity) {
        const res = await fetch('/api/cart', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ productId: cartProduct.id, quantity })
        });
        return { success: res.ok };
      }
    });
  }
</script>

<button onclick={openWidget}>View in your room</button>
```

--------------------------------

### Handle Add to Cart with Simple REST API (JavaScript)

Source: https://docs.selektable.com/guides/cart-integration

An example of implementing the `onAddToCart` callback using a simple REST API POST request. It sends product details and quantity to a server endpoint and returns a success status along with an optional cart URL.

```javascript
onAddToCart: async function (product, quantity) {
  const response = await fetch('/api/cart', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      productId: product.id,
      quantity: quantity
    })
  });

  if (!response.ok) {
    return { success: false, error: 'Could not add to cart' };
  }

  return { success: true, cartUrl: '/cart' };
}
```

--------------------------------

### Listening for Widget Close Event

Source: https://docs.selektable.com/sdk/events

This example demonstrates how to listen for the 'widget:modal-close' event using the browser's postMessage API to detect when a customer closes the Selektable widget.

```APIDOC
## Listening for Widget Close

### Description
Listen for the `widget:modal-close` event to detect when a customer closes the Selektable widget. This can be useful for triggering analytics or other custom actions.

### Method
Event Listener (JavaScript)

### Endpoint
`window.addEventListener('message', ...)`

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
window.addEventListener('message', function (event) {
  if (
    event.data &&
    event.data.type === 'widget:modal-close'
  ) {
    // Customer closed the widget
    console.log('Widget closed');
  }
});
```

### Response
#### Success Response (Event Triggered)
- **event.data.type** (string) - The type of the event, expected to be `'widget:modal-close'`.

#### Response Example
```json
{
  "type": "widget:modal-close"
}
```

### Security
The Selektable SDK validates the origin and structure of all incoming messages. Messages from untrusted sources are silently ignored.
```

--------------------------------

### Open Different Selektable Widgets Based on Product Category

Source: https://docs.selektable.com/sdk/examples/advanced

This JavaScript function dynamically selects and opens a Selektable widget based on the product's category. It uses a conditional check to determine whether to open the 'widget_tryon' for clothing items or the 'widget_room' for other categories, passing relevant product details to the widget.

```javascript
function openVisualizer(product) {
  // Choose widget based on product category
  var widgetId = product.category === 'clothing'
    ? 'widget_tryon'   // Virtual Try-On
    : 'widget_room';   // Room Visualizer

  Selektable.open(widgetId, {
    productId: product.id,
    productTitle: product.name,
    productImage: product.image,
    productUrl: product.url
  });
}
```

--------------------------------

### Selektable User Identity Management

Source: https://docs.selektable.com/sdk/examples/advanced

This JavaScript code illustrates how to manage user identity with the Selektable SDK. It includes functions for identifying a user upon login (`onLogin`) and resetting identity upon logout (`onLogout`). It also shows how to restore a user's identity on page load if they are already authenticated.

```javascript
// On login
async function onLogin(user) {
  Selektable.identify(user.id, {
    name: user.name,
    email: user.email
  });
}

// On logout
function onLogout() {
  Selektable.reset();
}

// On page load: restore identity for logged-in users
window.addEventListener('load', function () {
  var user = getAuthenticatedUser();
  if (user) {
    Selektable.identify(user.id, {
      name: user.name,
      email: user.email
    });
  }
});
```

--------------------------------

### Handle Add to Cart with Shopify AJAX (JavaScript)

Source: https://docs.selektable.com/guides/cart-integration

An example of implementing the `onAddToCart` callback for Shopify using its AJAX cart API. It sends a POST request with product ID and quantity to the `/cart/add.js` endpoint and returns a success status along with the cart URL.

```javascript
onAddToCart: async function (product, quantity) {
  const response = await fetch('/cart/add.js', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      id: product.id,
      quantity: quantity
    })
  });

  return { success: response.ok, cartUrl: '/cart' };
}
```

--------------------------------

### Track Appointment Conversion via Server-Side Webhook

Source: https://docs.selektable.com/guides/conversion-tracking

This section provides server-side code examples for handling form submissions and sending conversion data to Selektable. After saving the appointment details in your system, a webhook is sent to Selektable's API with the necessary tracking information, including visitor and session IDs, and conversion details. This ensures that lead generation activities are accurately tracked.

```javascript
app.post('/appointment/book', async (req, res) => {
    const { visitorId, sessionId, name, email, phone } = req.body;

    // Save the appointment in your system
    const appointment = await saveAppointment({ name, email, phone });

    // Track the conversion in Selektable
    await fetch('https://app.selektable.com/api/webhooks/orders', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer sel_your_api_key'
      },
      body: JSON.stringify({
        orderId: 'appt-' + appointment.id,
        storeId: 'store_xxx',
        organizationId: 'org_xxx',
        visitorId: visitorId,
        sessionId: sessionId,
        totalCents: 0,
        currency: 'USD',
        platform: 'custom',
        status: 'completed',
        orderCreatedAt: new Date().toISOString(),
        items: []
      })
    });

    res.redirect('/thank-you');
  });
```

```php
$visitor_id = $_POST['visitorId'];
  $session_id = $_POST['sessionId'];

  // Save the appointment in your system
  $appointment_id = save_appointment($_POST);

  // Track the conversion in Selektable
  $payload = json_encode([
      'orderId' => 'appt-' . $appointment_id,
      'storeId' => 'store_xxx',
      'organizationId' => 'org_xxx',
      'visitorId' => $visitor_id,
      'sessionId' => $session_id,
      'totalCents' => 0,
      'currency' => 'USD',
      'platform' => 'custom',
      'status' => 'completed',
      'orderCreatedAt' => date('c'),
      'items' => [],
  ]);

  $ch = curl_init('https://app.selektable.com/api/webhooks/orders');
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'Content-Type: application/json',
      'Authorization: Bearer sel_your_api_key',
  ]);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_exec($ch);
  curl_close($ch);
```

--------------------------------

### Configure Product Images for Selektable Widget (JavaScript)

Source: https://docs.selektable.com/guides/product-image

Demonstrates how to use Selektable.open() to pass specific images for AI generation (`productImage`) and the full gallery (`productImages`) in custom store integrations. Requires the Selektable library.

```javascript
Selektable.open('widget_abc123', {
  productId: 'sofa-001',
  productTitle: 'Modern Blue Sofa',

  // Use the clean product photo for AI generation
  productImage: 'https://myshop.com/images/sofa-isolated.jpg',

  // The full gallery (including lifestyle shots) displayed in the widget
  productImages: [
    { id: 1, src: 'https://myshop.com/images/sofa-isolated.jpg', alt: 'Product photo' },
    { id: 2, src: 'https://myshop.com/images/sofa-lifestyle.jpg', alt: 'In living room' },
    { id: 3, src: 'https://myshop.com/images/sofa-detail.jpg', alt: 'Fabric detail' }
  ]
});
```

--------------------------------

### Configure product gallery and metadata

Source: https://docs.selektable.com/sdk/examples/basic-usage

Shows how to pass multiple product images and a product URL to the widget, allowing users to visualize different angles of a product.

```javascript
Selektable.open('widget_abc123', {
  productId: 'sofa-001',
  productTitle: 'Modern Blue Sofa',
  productImage: 'https://myshop.com/images/sofa-front.jpg',
  productImages: [
    { id: 1, src: 'https://myshop.com/images/sofa-front.jpg', alt: 'Front view' },
    { id: 2, src: 'https://myshop.com/images/sofa-side.jpg', alt: 'Side view' },
    { id: 3, src: 'https://myshop.com/images/sofa-top.jpg', alt: 'Top view' }
  ],
  productUrl: 'https://myshop.com/products/modern-blue-sofa'
});
```

--------------------------------

### Preload Widget with JavaScript

Source: https://docs.selektable.com/guides/widgets

Demonstrates how to preload the Selektable widget using JavaScript for faster opening. This involves calling the `Selektable.preload()` function on page load and then `Selektable.open()` when needed. It's useful for product pages with expected high engagement.

```javascript
Selektable.preload('widget_abc123');

Selektable.open('widget_abc123', { ... });
```

--------------------------------

### Get Identity

Source: https://docs.selektable.com/sdk/identity

Returns the current identity object, including visitor ID, session ID, anonymous ID, and optionally user ID and traits.

```APIDOC
## `getIdentity()`

### Description
Returns the current identity object.

### Method
`getIdentity`

### Request Example
```javascript
const identity = Selektable.getIdentity();
```

### Response
#### Success Response (200)
- **visitorId** (string) - Persistent browser ID
- **sessionId** (string) - Current session ID
- **anonymousId** (string) - Anonymous ID (initially same as visitorId)
- **userId** (string) - Optional - Set after identify() is called
- **traits** (Record<string, unknown>) - Optional - Set after identify() is called
```

--------------------------------

### Handle dynamic product updates in SPAs

Source: https://docs.selektable.com/sdk/examples/basic-usage

Demonstrates how to update product data dynamically within a single-page application context when the product state changes.

```javascript
function onProductChange(product) {
  document.getElementById('try-on-btn').onclick = function () {
    Selektable.open('widget_abc123', {
      productId: product.id,
      productTitle: product.name,
      productImage: product.image,
      productImages: product.images.map(function (img, i) {
        return { id: i, src: img.url, alt: img.alt };
      }),
      productUrl: window.location.href
    });
  };
}
```

--------------------------------

### Get Current Identity - JavaScript

Source: https://docs.selektable.com/sdk/identity

Retrieves the current identity object, which includes visitorId, sessionId, anonymousId, and optionally userId and traits if identify() has been called. This is useful for inspecting the current state of user identification.

```javascript
const identity = Selektable.getIdentity();
```

--------------------------------

### Open Selektable Widget with Cart Callbacks (JavaScript)

Source: https://docs.selektable.com/guides/cart-integration

Demonstrates how to open a Selektable widget and configure cart-related callbacks. This includes handling product additions, viewing the cart, and initiating checkout. The `onAddToCart` callback is crucial for implementing custom cart logic.

```javascript
Selektable.open('widget_abc123', {
  productId: 'prod-456',
  productTitle: 'Modern Sofa',
  productImage: 'https://myshop.com/sofa.jpg',

  onAddToCart: async function (product, quantity, variation) {
    // Your cart logic here
    return { success: true };
  },

  onViewCart: function () {
    window.location.href = '/cart';
  },

  onCheckout: function () {
    window.location.href = '/checkout';
  }
});
```

--------------------------------

### Conditionally Load Widget Script

Source: https://docs.selektable.com/sdk/examples/advanced

This HTML snippet demonstrates how to conditionally load the Selektable embed script only on pages that contain a product identifier. It checks for the presence of an element with the 'data-product-id' attribute before appending the script to the document's body.

```html
<script>
  // Only load embed script on product pages
  if (document.querySelector('[data-product-id]')) {
    var script = document.createElement('script');
    script.src = 'https://app.selektable.com/widgets/embed.js';
    script.async = true;
    document.body.appendChild(script);
  }
</script>
```

--------------------------------

### Listen for Selektable Widget Close Event

Source: https://docs.selektable.com/sdk/examples/advanced

This JavaScript snippet demonstrates how to listen for the `widget:modal-close` event from the Selektable widget. By adding an event listener to the `window` for messages, you can detect when a customer closes the widget and trigger custom actions, such as tracking the event in analytics.

```javascript
window.addEventListener('message', function (event) {
  if (
    event.data &&
    event.data.type === 'widget:modal-close'
  ) {
    // Customer closed the widget
    analytics.track('widget_closed');
  }
});
```

--------------------------------

### Integrate Simple REST API with Selektable

Source: https://docs.selektable.com/sdk/examples/cart-integration

Demonstrates how to initialize the Selektable widget and handle the add-to-cart event using a standard REST API fetch request. It returns a success status and navigation URLs for the cart and checkout pages.

```javascript
Selektable.open('widget_abc123', {
  productId: 'sofa-001',
  productTitle: 'Modern Blue Sofa',
  productImage: 'https://myshop.com/images/sofa.jpg',

  onAddToCart: async function (product, quantity) {
    const response = await fetch('/api/cart', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        productId: product.id,
        quantity: quantity
      })
    });

    const data = await response.json();

    return {
      success: response.ok,
      error: response.ok ? undefined : data.message,
      cartUrl: '/cart'
    };
  },

  onViewCart: function () {
    window.location.href = '/cart';
  },

  onCheckout: function () {
    window.location.href = '/checkout';
  }
});
```

--------------------------------

### Client-Side SDK Integration

Source: https://docs.selektable.com/integrations/custom-platform

Methods for initializing the Selektable widget and handling product data on the client side.

```APIDOC
## Selektable.open(widgetId, options)

### Description
Opens the Selektable widget with specific product context and optional cart callbacks.

### Parameters
- **widgetId** (string) - Required - The ID of the specific widget instance
- **options** (object) - Required - Configuration object containing product details and event handlers

### Options Object
- **productId** (number/string) - Required - Unique product ID
- **productTitle** (string) - Required - Name of the product
- **productImage** (string) - Required - URL of the primary product image
- **onAddToCart** (function) - Optional - Callback triggered when adding to cart
- **onViewCart** (function) - Optional - Callback triggered to navigate to cart
- **onCheckout** (function) - Optional - Callback triggered to navigate to checkout

### Request Example
Selektable.open('widget_abc123', {
  productId: 123,
  productTitle: 'Product Name',
  productImage: 'https://example.com/product.jpg',
  onAddToCart: async (product, quantity) => { /* logic */ }
});
```

--------------------------------

### Initialize Selektable Widget with API Data

Source: https://docs.selektable.com/integrations/custom-platform

This snippet demonstrates fetching product data from a remote API and passing the required fields to the Selektable open method. It maps API response data to the expected widget configuration object.

```javascript
// Fetch product data from your API
const product = await fetch('/api/products/123').then(r => r.json());

// Open widget with fetched data
Selektable.open('widget_abc123', {
  productId: product.id,
  productTitle: product.name,
  productImage: product.images[0].url,
  productImages: product.images.map((img, i) => ({
    id: i,
    src: img.url,
    alt: img.alt || product.name
  })),
  productUrl: window.location.href
});
```

--------------------------------

### Preload widget for performance

Source: https://docs.selektable.com/sdk/examples/basic-usage

Optimizes user experience by preloading the widget iframe during the window load event, ensuring faster interaction when the user clicks the trigger.

```html
<script src="https://app.selektable.com/widgets/embed.js" async></script>

<script>
  window.addEventListener('load', function () {
    Selektable.preload('widget_abc123');
  });
</script>

<button onclick="Selektable.open('widget_abc123', {
  productId: 'sofa-001',
  productTitle: 'Modern Blue Sofa',
  productImage: 'https://myshop.com/images/sofa.jpg'
})">
  View in your room
</button>
```

--------------------------------

### Set Custom Selektable Visitor ID

Source: https://docs.selektable.com/sdk/examples/advanced

This JavaScript code shows how to set a custom visitor ID for Selektable, useful when integrating with existing analytics systems like Segment or Amplitude. By calling `Selektable.setVisitorId` with your analytics system's visitor ID, you ensure that Selektable's conversion data can be correlated with your existing tracking data.

```javascript
// Use your existing visitor ID
var myVisitorId = getMyAnalyticsVisitorId();
Selektable.setVisitorId(myVisitorId);
```

--------------------------------

### Handle Variable Products in Selektable

Source: https://docs.selektable.com/sdk/examples/cart-integration

Shows how to configure the Selektable widget for products with variations like size or color. It includes logic to parse selected attributes and send them to the backend during the add-to-cart process.

```javascript
Selektable.open('widget_abc123', {
  productId: 'tshirt-001',
  productTitle: 'Classic T-Shirt',
  productImage: 'https://myshop.com/images/tshirt-blue.jpg',
  type: 'variable',

  variations: [
    {
      id: 101,
      attributes: [
        { name: 'Color', value: 'Blue' },
        { name: 'Size', value: 'M' }
      ],
      is_in_stock: true
    },
    {
      id: 102,
      attributes: [
        { name: 'Color', value: 'Red' },
        { name: 'Size', value: 'L' }
      ],
      is_in_stock: true
    }
  ],

  attributes: [
    {
      id: 1,
      name: 'Color',
      taxonomy: 'pa_color',
      has_variations: true,
      terms: [
        { id: 10, name: 'Blue', slug: 'blue' },
        { id: 11, name: 'Red', slug: 'red' }
      ]
    },
    {
      id: 2,
      name: 'Size',
      taxonomy: 'pa_size',
      has_variations: true,
      terms: [
        { id: 20, name: 'M', slug: 'm' },
        { id: 21, name: 'L', slug: 'l' }
      ]
    }
  ],

  onAddToCart: async function (product, quantity, variation) {
    const body = {
      productId: product.id,
      quantity: quantity
    };

    if (variation) {
      body.attributes = {};
      variation.forEach(function (v) {
        body.attributes[v.attribute.toLowerCase()] = v.value;
      });
    }

    const response = await fetch('/api/cart', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(body)
    });

    return { success: response.ok };
  }
});
```

--------------------------------

### Preload Selektable Widget

Source: https://docs.selektable.com/sdk/methods

Creates the Selektable widget iframe in the background without displaying it. This allows for instant opening when `open()` is called later. If an iframe for the widget already exists, this method does nothing. It does not lock scroll or show any overlay.

```javascript
// On page load
Selektable.preload('widget_abc123');

// Later, on button click. Opens instantly
Selektable.open('widget_abc123', { ... });
```

--------------------------------

### Integrate Selektable SDK via JavaScript

Source: https://docs.selektable.com/integrations/custom-platform

Standard implementation for adding the Selektable widget to any website. Includes script initialization, button triggers, and cart callback handlers for seamless user experience.

```html
<!-- 1. Add the embed script -->
<script src="https://app.selektable.com/widgets/embed.js" data-store-id="store_xxx" async></script>

<!-- 2. Add a button -->
<button onclick="openWidget()">View in your room</button>

<!-- 3. Open the widget with product data -->
<script>
function openWidget() {
  Selektable.open('widget_abc123', {
    productId: 123,
    productTitle: 'Product Name',
    productImage: 'https://example.com/product.jpg',
    productImages: [
      { id: 1, src: 'https://example.com/product.jpg', alt: 'Product' }
    ],
    productUrl: 'https://example.com/product',

    onAddToCart: async function(product, quantity, variation) {
      const response = await yourCartApi.add(product.id, quantity);
      return {
        success: response.ok,
        error: response.ok ? undefined : 'Failed to add to cart'
      };
    },

    onViewCart: function() {
      window.location.href = '/cart';
    },

    onCheckout: function() {
      window.location.href = '/checkout';
    }
  });
}
</script>
```

--------------------------------

### Cart Integration Callbacks

Source: https://docs.selektable.com/guides/cart-integration

This section details the callbacks used for cart integration. When cart integration is enabled, customers can add products to their cart from the visualization. Your implementation handles the actual cart operations through these callbacks.

```APIDOC
## Cart Integration Callbacks

When cart integration is enabled on a widget, customers can add products to their shopping cart directly from the visualization result screen. You implement the actual cart logic through callbacks.

### Enabling Cart Integration

First, enable cart in the widget configuration in the dashboard. Then provide the callbacks when opening the widget:

```javascript
Selektable.open('widget_abc123', {
  productId: 'prod-456',
  productTitle: 'Modern Sofa',
  productImage: 'https://myshop.com/sofa.jpg',

  onAddToCart: async function (product, quantity, variation) {
    // Your cart logic here
    return { success: true };
  },

  onViewCart: function () {
    window.location.href = '/cart';
  },

  onCheckout: function () {
    window.location.href = '/checkout';
  }
});
```

### Callback Reference

#### `onAddToCart(product, quantity, variation)`

Called when the customer clicks "Add to Cart" in the widget.

**Parameters:**

- **product** (object) - Required - The product to add.
  - **id** (number) - Required - Product ID
  - **title** (string) - Required - Product title
  - **price** (string) - Optional - Product price
  - **image** (string) - Optional - Product image URL
- **quantity** (number) - Required - Number of items to add.
- **variation** (array) - Optional - Selected product variations (for variable products).
  - **attribute** (string) - Required - Variation attribute name (e.g., "color")
  - **value** (string) - Required - Selected value (e.g., "blue")

**Return value:**

Return an object (or a `Promise` that resolves to one):

```typescript
{
  success: boolean;   // Whether the add-to-cart succeeded
  error?: string;     // Error message to display (if success is false)
  cartUrl?: string;   // URL to the cart page (shown as link on success)
}
```

If the callback returns `void` or `undefined`, it's treated as `{ success: true }`.

#### `onViewCart()`

Called when the customer clicks "View Cart" after adding to cart. Navigate them to your cart page.

#### `onCheckout()`

Called when the customer clicks "Checkout" after adding to cart. Navigate them to your checkout page.

### Examples

#### Simple REST API cart

```javascript
onAddToCart: async function (product, quantity) {
  const response = await fetch('/api/cart', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      productId: product.id,
      quantity: quantity
    })
  });

  if (!response.ok) {
    return { success: false, error: 'Could not add to cart' };
  }

  return { success: true, cartUrl: '/cart' };
}
```

#### WooCommerce AJAX cart

```javascript
onAddToCart: async function (product, quantity, variation) {
  const formData = new FormData();
  formData.append('product_id', product.id);
  formData.append('quantity', quantity);

  if (variation) {
    variation.forEach(function (v) {
      formData.append('attribute_' + v.attribute, v.value);
    });
  }

  const response = await fetch('/?wc-ajax=add_to_cart', {
    method: 'POST',
    body: formData
  });

  return { success: response.ok };
}
```

#### Shopify AJAX cart

```javascript
onAddToCart: async function (product, quantity) {
  const response = await fetch('/cart/add.js', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      id: product.id,
      quantity: quantity
    })
  });

  return { success: response.ok, cartUrl: '/cart' };
}
```

## Error Handling

If you don't provide `onAddToCart` but cart is enabled on the widget, the customer will see an error when they try to add to cart. If your callback throws an error, the widget catches it and shows an error message to the customer.
```
Tokens:
Raw