🎯 TWC Preferences Widget

A powerful, customizable JavaScript widget that allows users to manage their product preferences including sizes, brands, colors, and categories. Built with automatic error handling, environment switching, and dynamic customer management.

🚀 Quick Start

1. Installation

CDN (Recommended)

<script src="https://unpkg.com/@thewishlistco/preference-center/script.js"></script>

NPM

npm install @thewishlistco/preference-center

2. HTML Structure

<div id="preferences-widget-container"></div>

3. Initialize Widget

document.addEventListener("DOMContentLoaded", async () => {
   await PreferencesWidget.init({
      containerId: "preferences-widget-container",
      tenantId: "your-tenant-id",
      customerEmail: "[email protected]",
      env: "staging", // or "prod"
   });
});

That's it! The widget will automatically handle authentication, load customer data, and display preferences.

⚙️ Configuration

Configuration Object

| Parameter | Type | Required | Default | Description | | --------------- | ------ | -------- | ----------- | ------------------------------------ | | containerId | string | ✅ | - | ID of the HTML container element | | tenantId | string | ✅ | - | Your tenant identifier | | customerEmail | string | ❌ | null | Customer email address | | env | string | ❌ | "staging" | Environment: "staging" or "prod" |

Environment Configuration

| Environment | API Base URL | Use Case | | ----------- | ------------------------------- | --------------------- | | staging | api.au-sandbox.thewishlist.io | Development & Testing | | prod | api.au-aws.thewishlist.io | Production & Live |

📚 Usage Examples

Basic Setup

// Staging environment with customer
await PreferencesWidget.init({
   containerId: "preferences-widget-container",
   tenantId: "your-tenant-id",
   customerEmail: "[email protected]",
   env: "staging",
});

Production Setup

// Production environment
await PreferencesWidget.init({
   containerId: "preferences-widget-container",
   tenantId: "your-prod-tenant-id",
   customerEmail: "[email protected]",
   env: "prod",
});

Initialize Without Customer

// Initialize first, set customer later
await PreferencesWidget.init({
   containerId: "preferences-widget-container",
   tenantId: "your-tenant-id",
   env: "staging",
});

// Set customer email when available
await PreferencesWidget.setCustomerEmail("[email protected]");

Dynamic Customer Switching

// Switch between customers dynamically
await PreferencesWidget.setCustomerEmail("[email protected]");
console.log("Current:", PreferencesWidget.getCurrentCustomerEmail());

// Switch to different customer
await PreferencesWidget.setCustomerEmail("[email protected]");
console.log("New:", PreferencesWidget.getCurrentCustomerEmail());

Widget Status Checking

// Check initialization status
if (PreferencesWidget.isInitialized()) {
   await PreferencesWidget.setCustomerEmail("[email protected]");
} else {
   console.log("Widget not initialized yet");
}

🔧 API Reference

💡 Built-in Error Handling: All methods handle errors internally and display user-friendly messages. No manual error handling required!

Core Methods

init(config)

Initializes the preferences widget with configuration.

await PreferencesWidget.init({
   containerId: "my-container",
   tenantId: "tenant123",
   customerEmail: "[email protected]",
   env: "prod",
});

setCustomerEmail(email)

Changes the customer and reloads their preferences.

await PreferencesWidget.setCustomerEmail("[email protected]");

getCurrentCustomerEmail()

Returns the currently active customer email.

const email = PreferencesWidget.getCurrentCustomerEmail();
console.log("Current customer:", email);

isInitialized()

Checks if the widget has been properly initialized.

const ready = PreferencesWidget.isInitialized();
if (ready) {
   // Widget is ready for use
}

Advanced Methods

getAuthToken(tenantId, env)

Gets authentication token (for advanced integrations).

const authData = await PreferencesWidget.getAuthToken("tenant123", "prod");
console.log("Token:", authData.access_token);

getCustomer(tenantId, accessToken, customerEmail, env)

Retrieves customer data (for advanced integrations).

const customer = await PreferencesWidget.getCustomer("tenant123", "access-token", "[email protected]", "prod");
console.log("Customer:", customer);

📖 Complete Example

<!DOCTYPE html>
<html lang="en">
   <head>
      <meta charset="UTF-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <title>Preferences Widget Demo</title>
      <script src="https://unpkg.com/@thewishlistco/[email protected]/script.js"></script>
   </head>
   <body>
      <div id="preferences-widget-container"></div>

      <script>
         document.addEventListener("DOMContentLoaded", async () => {
            // Initialize widget
            await PreferencesWidget.init({
               containerId: "preferences-widget-container",
               tenantId: "your-tenant-id",
               customerEmail: "[email protected]",
               env: "staging",
            });

            // Example: Switch customer after 5 seconds
            setTimeout(async () => {
               await PreferencesWidget.setCustomerEmail("[email protected]");
            }, 5000);
         });
      </script>
   </body>
</html>

🎛️ Customization

CSS Customization

/* Override widget styles */
.preferences-section {
   background-color: #f5f5f5;
   border-radius: 15px;
}

.preference-btn {
   font-size: 16px;
   padding: 12px 24px;
}

.preference-btn.active {
   background-color: #your-brand-color;
}

Container Styling

#preferences-widget-container {
   max-width: 800px;
   margin: 0 auto;
   padding: 20px;
}

Made with ❤️ by The Wishlist Co