Oyster Widget Developer Docs (v0.2.0)

This is the legacy documentation for integrations pinned to v0.2.0. New integrations should use v1 docs.

What you ship

One script tag plus a small init call. The widget opens as an embedded overlay and can be opened, minimized, or closed.

Two display modes

Float shows a floating launcher automatically. Inline lets you control when to call open().

Events

Your callback receives checkout, minimized, and closed events.

Overview

What it is, how it behaves

The Oyster widget is embedded by loading a UMD bundle that exposes a global OysterskinWidget. You create a widget instance using one of the factory methods:

  • OysterskinWidget.createScanWidget(options)
  • OysterskinWidget.createChatWidget(options)
  • OysterskinWidget.createUnifiedWidget(options)
  • OysterskinWidget.createConsultationWidget(options)

Each factory returns an instance with open(), minimize(), and close().

Permissions: the widget is embedded using an iframe with allow="camera *; geolocation *". If camera access is needed, your site must be served over HTTPS.

Quickstart

Copy/paste baseline integration

Replace placeholders like YOUR_VENDOR_KEY and YOUR_END_USER_ID. Your callback is required and receives widget events.

Minimal standalone examples: float mode and inline mode.

Use the playground below to validate your key + event plumbing quickly (no code changes required).

Playground

Load, create, open, minimize, close
Important Your vendor key is never stored by this page (other non-secret fields may be remembered locally).
Prefer pinned URLs in production.
Chat and Unified can accept conversation starters.
Float shows a launcher immediately. Inline requires calling open().
This doc does not store your key
Used for launcher/spinner styling and applied inside the widget UI.
Stable identifier you control (not an email address).
Used by the launcher hover popup text.
If starters are provided, chat/unified auto-open on create.
Event log (callback payloads)

This snippet reflects your current playground settings. Your vendor key is never inlined; replace YOUR_VENDOR_KEY.

Loading the bundle

UMD + global API

The widget is distributed as a UMD script that exposes a global OysterskinWidget. Load exactly one: 

<script src="https://sandbox.widget-lib.oysterskin.com/v0.2.0/oysterskin-vendor-widget-web.umd.js"></script>
<script src="https://widget-lib.oysterskin.com/v0.2.0/oysterskin-vendor-widget-web.umd.js"></script>

Modes (float vs inline)

Decide how the widget appears

Float mode

Create the widget with mode: "float". A floating launcher appears immediately; users open the widget by clicking it.

Inline mode

Create the widget with mode: "inline". No launcher is shown automatically. You decide when to call instance.open().

Both modes support minimize() which hides the widget and shows the floating launcher again.

Widget types

Which factory method to call
  • Scan: createScanWidget
  • Chat: createChatWidget
  • Unified: createUnifiedWidget
  • Consultation: createConsultationWidget

All widget types share the same instance contract and most options.

Options reference

What you can configure
  • key (string, required): vendor key.
  • user (object, required): { id, name?, email? }.
  • callback (function, required): called with widget events.
  • mode ("float" | "inline", optional): defaults to "float".
  • primaryColor (string, optional): affects launcher styling and widget theme.
  • displayLogo (boolean, optional): defaults to true.
  • introMessage / messageBody (string, optional): launcher hover popup.
  • minBudget/maxBudget (number, optional).
  • conversationStarters (string[], chat/unified only).

Events and callback

How to listen and react
  • closed: widget requested close.
  • minimized: widget requested minimize.
  • checkout: user completed checkout; payload in data.
function onWidgetMessage(message) {
  switch (message.event) {
    case "checkout":
      break;
    case "minimized":
      break;
    case "closed":
      break;
    default:
      break;
  }
}

Framework patterns

React/Next.js, SPAs, tag managers

See v1 docs for updated inline embedding patterns.

Advanced patterns

Lazy load, singleton, CTA-driven open

See v1 docs for updated inline embedding patterns.

Versioning

Pin versions and promote safely
// Sandbox base
https://sandbox.widget-lib.oysterskin.com/<VERSION_OR_ALIAS>/oysterskin-vendor-widget-web.umd.js

// Production base
https://widget-lib.oysterskin.com/<VERSION_OR_ALIAS>/oysterskin-vendor-widget-web.umd.js

If you’re on v0, prefer pinning exact versions (or patch-only channels like /v0.2/), since 0.x can introduce breaking changes in minor releases.

CSP / security headers

Common integration blocker

Allow the widget script + iframe origins for the environment you use.

Performance

Load timing + UX

Prefer lazy-loading in inline mode for best page performance.

Troubleshooting

Fast fixes

If OysterskinWidget is undefined, verify your script URL and CSP.

Launch checklist

Before you ship
  • Keys: no keys committed; loaded at runtime from your config/secret system.
  • Callback: events are handled and logged in staging.
  • CSP: script-src and frame-src updated for the widget domains.