@tulipnpm/appointments-widget
v1.0.0
Published
Loader for the Tulip appointments booking widget.
Readme
@tulipnpm/appointments-widget
Loads the Tulip appointments booking widget on your site. The loader exchanges your publishable key for a short session, keeps it fresh and frames the widget. The widget itself is served from your Tulip host, so booking screens, styling and copy update without a new loader release.
Before you start
Your Tulip contact gives you two values and sets one thing up for you.
- The host, for example
https://tenant.example.com. - A publishable key,
wdg_pk_followed by 32 hex characters. It is safe in page source, because it only starts a session from an allowed origin. - The allowed origins. Tulip lists every origin that loads the widget, for example
https://www.example.comandhttps://staging.example.com. A page on any other origin gets asetuperror.
If your site sends a Content Security Policy, allow these sources.
| Directive | Source |
| ------------- | --------------------------------------------------- |
| script-src | https://cdn.jsdelivr.net, for the script tag only |
| connect-src | your Tulip host, for the session exchange |
| frame-src | your Tulip host, for the widget iframe |
| img-src | the logo URL, when your launcher shows a logo |
Modes
The widget runs in one of two modes.
pagedraws the widget inline in an element you provide. The frame grows and shrinks with its content.sidePaneladds a launcher button to a bottom corner of the page. The button opens the widget in a 560 px panel, full screen on viewports narrower than 744 px. The launcher appears once the widget has loaded.
Tulip stores a default mode for your site. The mode option overrides it. Set mode in page mode, so the frame can show the setup error when the session exchange fails. Without it, the loader does not know the mode and draws nothing.
Install
Script tag, page mode
<div id="book-appointment"></div>
<script src="https://cdn.jsdelivr.net/npm/@tulipnpm/appointments-widget@1/dist/loader.min.js"></script>
<script>
const widget = TulipAppointments.init({
host: 'https://tenant.example.com',
publishableKey: 'wdg_pk_0123456789abcdef0123456789abcdef',
mode: 'page',
container: '#book-appointment',
locale: document.documentElement.lang,
});
widget.on('booked', (booking) => {
window.dataLayer?.push({ event: 'appointment_booked', bookingUuid: booking.bookingUuid });
});
</script>The script sets the global window.TulipAppointments, with init as its only member.
@1 follows every 1.x release after jsDelivr refreshes its cache, which takes up to a day. To use Subresource Integrity, load an exact version such as @1.0.0 with an integrity attribute. You then get fixes only when you change the version.
Bundler, side panel mode
npm install @tulipnpm/appointments-widgetimport { init } from '@tulipnpm/appointments-widget';
init({
host: 'https://tenant.example.com',
publishableKey: 'wdg_pk_0123456789abcdef0123456789abcdef',
mode: 'sidePanel',
});The package is ESM only and ships its own TypeScript types.
React, side panel mode with the store preselected
import { AppointmentsWidget } from '@tulipnpm/appointments-widget/react';
export function StorePage({ storeUuid }: { storeUuid: string }) {
return (
<AppointmentsWidget
host="https://tenant.example.com"
publishableKey="wdg_pk_0123456789abcdef0123456789abcdef"
mode="sidePanel"
context={{ storeUuid }}
onBooked={(booking) => console.info('booked', booking.bookingUuid)}
/>
);
}The component needs React 18 or later. The script tag and the init import need no React.
The component takes the options below except container. In page mode it renders a div, styled through className. In side panel mode it renders nothing and attaches the launcher to document.body. A change to host, publishableKey, mode, locale or colorScheme restarts the widget. A change to context only calls setContext. The onReady, onOpen, onClose, onStepChanged, onBooked and onError props receive the events below. A ref gets the handle.
import { useRef } from 'react';
import type { AppointmentsWidgetHandle } from '@tulipnpm/appointments-widget';
import { AppointmentsWidget } from '@tulipnpm/appointments-widget/react';
export function BookButton() {
const widgetRef = useRef<AppointmentsWidgetHandle>(null);
return (
<>
<AppointmentsWidget
ref={widgetRef}
host="https://tenant.example.com"
publishableKey="wdg_pk_0123456789abcdef0123456789abcdef"
mode="sidePanel"
/>
<button onClick={() => widgetRef.current?.open()}>Book an appointment</button>
</>
);
}Preview releases
Prereleases such as 1.1.0-rc.0 ship under the next dist-tag. A range like @1 does not match a prerelease. Load @next or an exact prerelease instead.
<script src="https://cdn.jsdelivr.net/npm/@tulipnpm/appointments-widget@next/dist/loader.min.js"></script>npm install @tulipnpm/appointments-widget@nextOptions
| Option | Required | Description |
| ---------------- | ------------ | --------------------------------------------------------------------------------- |
| host | yes | Your Tulip host. Must use https. |
| publishableKey | yes | The wdg_pk_ key from Tulip. |
| mode | no | page or sidePanel. Overrides the mode stored in Tulip. |
| container | in page mode | The element, or a CSS selector for it, that holds the widget. |
| locale | no | A BCP 47 tag such as fr-CA. Defaults to the browser language. |
| colorScheme | no | light or dark. Defaults to light. dark uses your brand's dark colors. |
| context | no | { storeUuid, appointmentTypeUuid, associateUuid }. See Preselect. |
The widget shows the first supported language from locale, then your site's default language, then English.
Preselect
context and setContext preselect parts of the booking. Each field is optional.
storeUuidskips the store step when the store takes widget bookings.appointmentTypeUuidskips the type step when the type is offered at the chosen store.associateUuidpreselects the associate on the associate step.
When a value matches nothing bookable, the shopper picks as usual. setContext replaces the whole context, so pass every field you want to keep. You can call it before or after ready.
Handle
init returns a handle at once. Events fire later, so handlers you attach right after init see every event.
| Member | Description |
| --------------------- | ----------------------------------------------------------------------- |
| mode | page, sidePanel, or null until the mode is known. |
| open(), close() | Open or close the side panel. No effect in page mode or before ready. |
| setContext(context) | Replace the preselected store, type and associate. |
| on(event, handler) | Subscribe to an event. Returns a function that unsubscribes. |
| destroy() | Remove the widget, the launcher, the session timer and every listener. |
One widget runs per page. A second init destroys the first widget.
Events
| Event | Payload |
| --------------- | ------------------------------------------------------------------------------------------------ |
| ready | { protocol }, once the widget has loaded. |
| open, close | {}, when the side panel opens or closes. |
| stepChanged | { step, index, total }. index is zero-based over the steps the shopper sees. |
| booked | { bookingUuid, start, end, timeZone, storeUuid, appointmentTypeUuid }. Holds no customer data. |
| error | { code, message, fatal }. See below. |
step is one of selectAppointmentMethod, selectStore, selectAppointmentType, selectAssociate, selectDateTime, bookingForm, reviewBooking or bookingConfirmation. start and end are ISO 8601 with an offset, and timeZone is the store's IANA zone.
Errors
| code | fatal | Meaning |
| -------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| setup | yes | The widget cannot start. The page origin is not allowed, the key is wrong, the host is not https or page mode has no container. |
| session | yes | The session expired and the loader could not renew it. The widget shows an error. Reload the page. |
| configurationUnavailable | no | The widget could not load your site's configuration and runs with the default look. |
| translationsUnavailable | no | The widget could not load your copy overrides and runs with the built-in copy. |
On a setup error from the session exchange, the browser console names the page origin and the key prefix. Side panel mode then shows no launcher, and page mode shows a translated error in the frame.
Migrate from @tulipnpm/timekit_project_selector
The two packages can run on the same page and the same tenant, so you can move one site at a time.
- Tulip support writes your brand, widget configuration and copy overrides.
- Tulip support creates your publishable key and allows your site origins.
- Replace the legacy script tags, the booking.js tags and the
TimekitProjectSelectorinit call with one snippet above. The Timekitapp_keyleaves your page. - Tulip support sets which appointment types the widget offers.
| Legacy | This package |
| ------------------------------------------------- | -------------------------------------------------------------------- |
| app_key in the page source | publishableKey, which only starts a session from an allowed origin |
| addFilter | setContext({ storeUuid, appointmentTypeUuid, associateUuid }) |
| popup and embed modes | mode: 'sidePanel' and mode: 'page' |
| host CSS that targets widget classes | brand and widget configuration in Tulip, no CSS |
| custom UI mode (getStrategy, getStepsFactory) | not offered |
