Hyper Widget Integration Guide

This guide will help you integrate the Hyper widget into your website. The Hyper onboarding widget is designed to be embedded into any web page using a simple script tag.

Quick Start

Add the following code to your HTML page where you want the Hyper widget to appear:

const HYPER_PLATFORM_ID = "your-platform-id"; // IMPORTANT: Replace "your-platform-id" with the platform ID you can find in the Hyper dashboard

window.hyperSettings = {
  platform_id: HYPER_PLATFORM_ID,
  user_id: user.id, // IMPORTANT: Replace "user.id" with the variable you use to capture the user's ID
  created_at: user.createdAt, // IMPORTANT: Replace "user.createdAt" with the variable you use to capture the user's sign-up date
  email: user.email,
  first_name: user.firstName, // IMPORTANT: Replace "user.firstName" with the variable you use to capture the user's first name
  full_name: user.fullName, // IMPORTANT: Replace "user.fullName" with the variable you use to capture the user's full name
  locale: user.locale, // IMPORTANT: Replace "user.locale" with the variable you use to capture the user's preferred locale code for the user
  company: {
    company_id: user.companyId, // IMPORTANT: Replace "user.companyId" with the variable you use to capture the user's company ID
    name: user.companyName, // IMPORTANT: Replace "user.companyName" with the variable you use to capture the user's company name
    meta: {
      // Arbitrary company-level metadata, these are optional. Just some examples:
      // plan: user.company.plan,
      // industry: user.company.industry,
    }
  },
  meta: {
    // Arbitrary user-level metadata, these are optional. Just some examples:
    // browser: navigator.userAgent,
    // screen_size: `${window.innerWidth}x${window.innerHeight}`,
  }
};

(function() {
  // Create script element
  const script = document.createElement("script");
  script.src = "https://widget.makehyper.com/assets/widget.js";
  script.type = "module";
  script.async = true;

  // Add error handling
  script.onerror = function() {
    console.error("Failed to load Hyper widget");
  };

  // Wait for HyperReady event before initializing
  script.onload = function() {
    window.Hyper.initialize(window.hyperSettings);
  };

  // Append script to document
  document.head.appendChild(script);
})();

This asynchronous loading approach offers several benefits: it prevents blocking page rendering, provides precise control over when the widget initializes, includes robust error handling, and allows you to conditionally load the widget based on user actions or other contextual factors.

Optional: Setting Tab-Specific Parameters

You can optionally set runtime parameters that provide context for AI guidances:

// Set tab-specific context (optional)
window.Hyper.setParams({
  current_page: "dashboard",
  view_mode: "analytics"
});

// Verify parameters were set
console.log(window.Hyper.getParams());
// Output: { current_page: "dashboard", view_mode: "analytics" }

// Clear parameters when context changes
window.Hyper.clearParams();
console.log(window.Hyper.getParams());
// Output: {}

See Tab-Specific Runtime Parameters for detailed information.

Configuration Options

The Hyper widget accepts the following configuration options:

Option	Type	Required	Description
platform_id	string	Yes	Your unique platform identifier, as can be found in the Hyper dashboard
user_id	string	Yes	Unique identifier for the current user
email	string	Yes	User's email address
created_at	datetime	Yes	UTC Date and time of when the user was created
first_name	string	Yes	User's first name
full_name	string	Yes	User's full name
locale	string	Yes	User's preferred language code (e.g., "en", "es", "fr")
company	object	Yes	Company information
company.company_id	string	Yes	Unique identifier for the company
company.name	string	Yes	Company name
company.meta	object	No	Optional company metadata
meta	object	No	Any optional metadata that will be stored in the user record

TypeScript Support

If you're using TypeScript, you can use the following interface for type checking:

interface HyperConfig {
  platform_id: string;
  user_id: string;
  email: string;
  created_at: string;
  first_name: string;
  full_name: string;
  locale: string;
  company: {
    company_id: string;
    name: string;
    meta: Record<string, any>;
  };
  meta: Record<string, any>;
}

Runtime Parameters for Guidances

Hyper supports passing runtime parameters when starting milestones or adhoc guidances. This allows you to customize the AI guidance based on the current context of your application.

Note: Parameter keys are automatically converted to snake_case format. You can use any naming convention (camelCase, PascalCase, kebab-case, etc.) and they will be normalized to snake_case (e.g., customerName → customer_name).

Starting a Milestone with Parameters

You can pass runtime parameters when starting a milestone using the startMilestone method:

// Example: Pass order details when starting an order processing milestone
window.Hyper.startMilestone("process-order-milestone", {
  order_number: "ORD-2024-001",
  customer_name: "ACME Corp",
  order_total: 1299.99,
  item_count: 3
});

Template Rendering

If your milestone prompts use Handlebars templates, the parameters will be used to render the actual prompt sent to the AI. For example, if your milestone prompt is:

Process order {{order_number}} for customer {{customer_name}} with {{item_count}} items

And you call:

window.Hyper.startMilestone("order-fulfillment", {
  order_number: "ORD-2024-001",
  customer_name: "John Smith",
  item_count: 5
});

The AI will receive the rendered prompt: "Process order ORD-2024-001 for customer John Smith with 5 items"

Parameter Processing

Parameters are processed as follows: 1. Automatic conversion: All parameter keys are automatically converted to snake_case format 2. Schema validation: If a schema is defined for the milestone, parameters must match the schema after conversion

Invalid parameters (that don't match the schema) will cause the guidance to fail with an appropriate error message.

Common Use Cases

1. Order Processing: Pass order details to provide context-specific guidance
2. Form Assistance: Include current form values to get relevant help
3. Role-Based Guidance: Pass user role information for customized instructions
4. Dynamic Content: Use current page state to make guidance more relevant

// Example: Dynamic guidance based on user actions
document.querySelector('#create-invoice-btn').addEventListener('click', () => {
  const formData = new FormData(document.querySelector('#invoice-form'));

  window.Hyper.startMilestone("create-invoice", {
    client_name: formData.get('client_name'),
    invoice_type: formData.get('invoice_type'),
    has_discount: formData.get('discount') !== null
  });
});

Automatic Key Conversion Examples

All parameter keys are automatically converted to snake_case: - customerName → customer_name - OrderNumber → order_number - customer-name → customer_name - CUSTOMER_NAME → customer_name - is premium → is_premium - created at → created_at

Tab-Specific Runtime Parameters

In addition to passing parameters when starting individual guidances, you can maintain tab-specific runtime parameters that persist across multiple guidances within the same browser tab. This is useful for storing page context that should be available throughout the user's interaction in that specific tab.

Important: These parameters are stored in sessionStorage, which means: - They are TAB-SPECIFIC (not shared between browser tabs) - They persist across page refreshes within the same tab - They are automatically cleared when the tab is closed - Each tab maintains its own independent set of parameters

This is different from cookie-based sessions that work across tabs. Think of these as "tab context" rather than "user session".

Setting Tab-Specific Parameters

Use window.Hyper.setParams() to set or update tab-specific parameters:

// Set tab context when navigating to a specific page
window.Hyper.setParams({
  current_page: "orders",
  filter_status: "pending",
  sort_by: "date_desc"
});

// Update specific parameters later (shallow merge)
window.Hyper.setParams({
  filter_status: "completed",  // Updates existing
  date_range: "last_7_days"   // Adds new
});
// Result: { current_page: "orders", filter_status: "completed", sort_by: "date_desc", date_range: "last_7_days" }

Key Behaviors

1. Shallow Merge: setParams() performs a shallow merge - only first-level keys are updated
2. Automatic Normalization: All keys are converted to snake_case before storage
3. Tab Isolation: Parameters are isolated per browser tab (stored in sessionStorage)
4. Parameter Priority: Direct parameters override tab-specific parameters when starting guidances

Getting Current Parameters

const currentParams = window.Hyper.getParams();
console.log("Tab-specific params:", currentParams);

Clearing Parameters

// Clear all tab-specific parameters (e.g., when context changes significantly)
window.Hyper.clearParams();

How Parameters Are Merged

When starting a guidance, parameters are resolved in this order: 1. Tab-specific parameters (base layer) 2. Direct parameters passed to startMilestone()/startAdhoc() (override layer)

// Tab-specific params
window.Hyper.setParams({ 
  current_view: "orders", 
  filter_status: "pending" 
});

// Start milestone with additional params
window.Hyper.startMilestone("process-order", {
  order_number: "ORD-123",
  filter_status: "completed"  // Overrides tab-specific param
});

// AI receives: { current_view: "orders", filter_status: "completed", order_number: "ORD-123" }

Common Use Cases

1. Page Context: Store current page/view information for this tab
2. Filter State: Track active filters and sorting options in this tab
3. Form Progress: Sync form data for contextual help specific to this tab
4. Navigation State: Track where the user is in multi-step processes

// Example: Tab-specific page context
function updatePageContext() {
  window.Hyper.setParams({
    current_page: window.location.pathname,
    current_view: "order_details",
    order_id: getOrderIdFromUrl(),
    edit_mode: isEditModeActive()
  });
}

// Now all guidances in this tab have access to this context
window.Hyper.startMilestone("edit-order-help");
// The AI knows which order is being edited in this specific tab

Note: Remember that each browser tab maintains its own parameters. If a user has multiple tabs open, each can have different context parameters.

Browser Compatibility

Safari with Intelligent Tracking Prevention (ITP)

When your application (that includes the Hyper widget) is embedded as an iframe on a different domain, Safari users with ITP enabled will experience session persistence issues. Sessions will not persist across page navigations, creating a new session on each page load.

Recommended solutions: - Use a Single Page Application (SPA) - no page navigations means no session loss - Avoid embedding your application in cross-domain iframes - Host your application on the same domain as the parent frame - See Safari ITP Limitations for detailed information

Troubleshooting

When troubleshooting integration issues, we recommend examining the browser console for any error messages that might provide insight into the problem. It's also important to confirm that your configuration includes all required fields with valid values. Although most values are optional, the platform UUID is the most important one to get right. Additionally, verify that the widget script URL is properly accessible from your domain and that both your platform identifier and user identifier have been correctly configured and are valid within the Hyper system.

Support

For additional support or questions, please contact our support team or refer to our API documentation.