diff --git a/docs/content/scripts/tawk-to.md b/docs/content/scripts/tawk-to.md new file mode 100644 index 000000000..3cfc266cb --- /dev/null +++ b/docs/content/scripts/tawk-to.md @@ -0,0 +1,135 @@ +--- +title: Tawk.to +description: Load the Tawk.to live chat widget and drive it through a typed proxy, reactive state, and event listeners. +links: + - label: Source + icon: i-simple-icons-github + to: https://github.com/nuxt/scripts/blob/main/packages/script/src/runtime/registry/tawk-to.ts + size: xs +--- + +[Tawk.to](https://www.tawk.to/) is a free live chat widget. + +[`useScriptTawkTo()`{lang="ts"}](/scripts/tawk-to) loads the widget, types the `window.Tawk_API` command surface, and bridges the `window` events the embed script dispatches into reactive state and typed listeners. + +::script-stats +:: + +::script-docs +:: + +Bundling and proxying are both off. Nobody has verified how the embed script resolves its own API origin, or what live-chat polling connections a proxy would end up in front of, so neither capability is declared rather than guessed at. + +Find `propertyId` and `widgetId` under **Administration Settings → Channels → Chat Widget** in your Tawk.to dashboard. + +::code-group + +```ts [Proxy] +const { proxy } = useScriptTawkTo({ + propertyId: 'YOUR_PROPERTY_ID', + widgetId: 'YOUR_WIDGET_ID', +}) + +function openChat() { + proxy.maximize() +} +``` + +```ts [onLoaded] +const { onLoaded } = useScriptTawkTo({ + propertyId: 'YOUR_PROPERTY_ID', + widgetId: 'YOUR_WIDGET_ID', +}) + +onLoaded((Tawk_API) => { + Tawk_API.maximize() +}) +``` + +:: + +## Reactive state and events + +Tawk's embed script dispatches `window` `CustomEvent`s (`tawkLoad`, `tawkStatusChange`, `tawkChatMaximized`, …) alongside its documented `Tawk_API.onXxx = fn` callback-property API. `useScriptTawkTo()`{lang="ts"} bridges those events into five readonly refs and twenty typed listeners, so you don't have to wire `window.addEventListener` yourself: + +```vue + + + +``` + +`chatStatus` is Tawk's own online/away/offline operator status (`getStatus()`{lang="ts"}). It's distinct from `status`, the generic script-load state every registry entry exposes. + +Every `onXxx` listener returns a teardown function for use with `onScopeDispose`, mirroring the rest of the registry's event-listener helpers. + +The state refs are a single instance shared by every `useScriptTawkTo()`{lang="ts"} call on the page (there's only ever one Tawk widget), not one instance per call. + +## Getters + +`proxy` is fire-and-forget: calls queue until the script loads and replay once it does, but their return value is always discarded, even after loading. That's fine for actions like `proxy.maximize()`{lang="ts"}, which don't return anything meaningful anyway, but it can't carry a real synchronous getter. `getWindowType`, `getStatus`, `isChatMaximized`, `isChatMinimized`, `isChatHidden`, `isChatOngoing`, `isVisitorEngaged`, and `widgetPosition` are exposed directly on `useScriptTawkTo()`{lang="ts"}'s return value instead, calling straight through to `window.Tawk_API`: + +```ts +const { getStatus, isChatHidden } = useScriptTawkTo({ + propertyId: 'YOUR_PROPERTY_ID', + widgetId: 'YOUR_WIDGET_ID', +}) + +getStatus() // 'online' | 'away' | 'offline' | undefined +isChatHidden() // boolean, false before the widget has loaded +``` + +## Identifying visitors + +`proxy.visitor = {...}` doesn't work for the same reason: unhead's script proxy has no `set` trap, so a property assignment through it never reaches the real `Tawk_API`. Use `setVisitor()`{lang="ts"} instead. + +It is pre-load only. Tawk honors `Tawk_API.visitor` before the embed script loads and ignores it afterwards, so once the embed has been requested the call warns and does nothing. Change identity after load with `window.Tawk_API.setAttributes({ name, email, phone, hash })`{lang="ts"}. + +```ts +const { proxy, setVisitor } = useScriptTawkTo({ + propertyId: 'YOUR_PROPERTY_ID', + widgetId: 'YOUR_WIDGET_ID', +}) + +setVisitor({ + name: 'Jane Doe', + email: 'jane@example.com', + // HMAC-SHA256 signature for Secure Mode, generated server-side + hash: visitorHash, +}) +proxy.setAttributes({ plan: 'pro' }) +proxy.addTags(['vip']) +``` + +## Switching properties at runtime + +```ts +const { proxy } = useScriptTawkTo({ + propertyId: 'YOUR_PROPERTY_ID', + widgetId: 'YOUR_WIDGET_ID', +}) + +proxy.switchWidget({ propertyId: 'OTHER_PROPERTY_ID', widgetId: 'OTHER_WIDGET_ID' }) +``` + +::script-types +:: + +## Partytown + +Do not run Tawk.to under Partytown. The widget renders DOM overlays (the chat bubble, prechat and full chat panels) directly, and the `window` `CustomEvent`s the reactive state and listeners depend on aren't configured for worker forwarding. diff --git a/packages/script/src/registry-logos.ts b/packages/script/src/registry-logos.ts index 77a698ce7..a3459e90f 100644 --- a/packages/script/src/registry-logos.ts +++ b/packages/script/src/registry-logos.ts @@ -56,6 +56,7 @@ export const LOGOS = { light: ``, dark: ``, }, + tawkTo: `https://www.tawk.to/icon.png`, crisp: { light: ``, dark: ``, diff --git a/packages/script/src/registry-types.json b/packages/script/src/registry-types.json index e6abb5da4..59246ab3a 100644 --- a/packages/script/src/registry-types.json +++ b/packages/script/src/registry-types.json @@ -1233,6 +1233,48 @@ "code": "interface ScriptStripePricingTableSlots {\n default?: () => any\n loading?: () => any\n awaitingLoad?: () => any\n error?: () => any\n}" } ], + "tawk-to": [ + { + "name": "TawkToOptions", + "kind": "const", + "code": "export const TawkToOptions = object({\n /**\n * Your Tawk.to property ID: the first path segment of the widget embed URL\n * `https://embed.tawk.to//`.\n * @see https://dashboard.tawk.to/\n */\n propertyId: pipe(string(), minLength(1)),\n /**\n * Your Tawk.to widget ID: the second path segment of the widget embed URL\n * `https://embed.tawk.to//`.\n * @see https://dashboard.tawk.to/\n */\n widgetId: pipe(string(), minLength(1)),\n})" + }, + { + "name": "TawkToStatus", + "kind": "type", + "code": "export type TawkToStatus = 'online' | 'away' | 'offline'" + }, + { + "name": "TawkToWindowType", + "kind": "type", + "code": "export type TawkToWindowType = 'inline' | 'embed'" + }, + { + "name": "TawkToWidgetPosition", + "kind": "type", + "code": "export type TawkToWidgetPosition = 'br' | 'bl' | 'cr' | 'cl' | 'tr' | 'tl'" + }, + { + "name": "TawkToVisitor", + "kind": "interface", + "code": "export interface TawkToVisitor {\n name?: string\n email?: string\n /** Visitor phone number in E.164 format (e.g. `+15551234567`). */\n phone?: string\n /** HMAC-SHA256 signature for Tawk's Secure Mode, generated server-side by the consumer. */\n hash?: string\n}" + }, + { + "name": "TawkToApi", + "kind": "interface", + "code": "export interface TawkToApi {\n /** Starts the chat. Pass `{ showWidget: true }` to also show the widget. */\n start: (options?: { showWidget?: boolean }) => void\n shutdown: () => void\n maximize: () => void\n minimize: () => void\n toggle: () => void\n popup: () => void\n showWidget: () => void\n hideWidget: () => void\n toggleVisibility: () => void\n endChat: () => void\n\n getWindowType: () => TawkToWindowType\n getStatus: () => TawkToStatus\n isChatMaximized: () => boolean\n isChatMinimized: () => boolean\n isChatHidden: () => boolean\n isChatOngoing: () => boolean\n isVisitorEngaged: () => boolean\n /** Set by Tawk once the widget has finished loading. The embed writes a boolean (`!0`), not a number. */\n onLoaded?: boolean\n /** Set by Tawk before the widget begins loading. */\n onBeforeLoaded?: boolean\n widgetPosition: () => TawkToWidgetPosition\n\n visitor?: TawkToVisitor\n setAttributes: (attributes: Record, callback?: (error: Error | null) => void) => void\n addEvent: (event: string, metadata?: Record, callback?: (error: Error | null) => void) => void\n addTags: (tags: string[], callback?: (error: Error | null) => void) => void\n removeTags: (tags: string[], callback?: (error: Error | null) => void) => void\n switchWidget: (data: { propertyId: string, widgetId: string }, callback?: (error: Error | null) => void) => void\n}" + }, + { + "name": "TawkToProxyApi", + "kind": "type", + "code": "export type TawkToProxyApi = Omit" + }, + { + "name": "TawkToEvents", + "kind": "interface", + "code": "export interface TawkToEvents {\n isHidden: Readonly>\n isMinimized: Readonly>\n isMaximized: Readonly>\n /** The operator status Tawk reports (`getStatus()`) — not to be confused with `status`, the script's own load state. */\n chatStatus: Readonly>\n unreadCount: Readonly>\n\n // Getters, called directly against `window.Tawk_API` (see `TawkToProxyApi`'s\n // doc comment for why `proxy` can't carry these). `undefined` before the\n // widget has loaded; the four `isXxx` booleans default to `false` instead\n // since a definite \"no\" is a safe, honest answer before load.\n getWindowType: () => TawkToWindowType | undefined\n getStatus: () => TawkToStatus | undefined\n isChatMaximized: () => boolean\n isChatMinimized: () => boolean\n isChatHidden: () => boolean\n isChatOngoing: () => boolean\n isVisitorEngaged: () => boolean\n widgetPosition: () => TawkToWidgetPosition | undefined\n\n /**\n * Sets `Tawk_API.visitor` directly - assigning through `proxy.visitor` is a no-op\n * (no `set` trap). Pre-insertion only: Tawk honors `Tawk_API.visitor` until the\n * embed script is requested, so a call after that warns and does nothing - use\n * `window.Tawk_API.setAttributes()` for post-load identity changes.\n */\n setVisitor: (data: TawkToVisitor) => void\n\n onLoad: (cb: () => void) => () => void\n onBeforeLoad: (cb: () => void) => () => void\n onStatusChange: (cb: (status: TawkToStatus) => void) => () => void\n onChatMaximized: (cb: () => void) => () => void\n onChatMinimized: (cb: () => void) => () => void\n onChatHidden: (cb: () => void) => () => void\n onChatStarted: (cb: () => void) => () => void\n onChatEnded: (cb: () => void) => () => void\n onPrechatSubmit: (cb: (data: Record) => void) => () => void\n onOfflineSubmit: (cb: (data: Record) => void) => () => void\n onChatMessageVisitor: (cb: (message: string) => void) => () => void\n onChatMessageAgent: (cb: (message: string) => void) => () => void\n onChatMessageSystem: (cb: (message: string) => void) => () => void\n onAgentJoinChat: (cb: (data: Record) => void) => () => void\n onAgentLeaveChat: (cb: (data: Record) => void) => () => void\n onChatSatisfaction: (cb: (satisfaction: number) => void) => () => void\n onVisitorNameChanged: (cb: (visitorName: string) => void) => () => void\n onFileUpload: (cb: (link: string) => void) => () => void\n onTagsUpdated: (cb: (data: Record) => void) => () => void\n onUnreadCountChanged: (cb: (count: number) => void) => () => void\n}" + } + ], "tiktok-pixel": [ { "name": "StandardEvents", @@ -2826,6 +2868,20 @@ "defaultValue": "'basil'" } ], + "TawkToOptions": [ + { + "name": "propertyId", + "type": "string", + "required": true, + "description": "Your Tawk.to property ID: the first path segment of the widget embed URL `https://embed.tawk.to//`." + }, + { + "name": "widgetId", + "type": "string", + "required": true, + "description": "Your Tawk.to widget ID: the second path segment of the widget embed URL `https://embed.tawk.to//`." + } + ], "TikTokPixelOptions": [ { "name": "id", diff --git a/packages/script/src/registry.ts b/packages/script/src/registry.ts index 95a8d539b..eb6978466 100644 --- a/packages/script/src/registry.ts +++ b/packages/script/src/registry.ts @@ -48,6 +48,7 @@ import { SnapTrPixelOptions, SpeedCurveOptions, StripeOptions, + TawkToOptions, TikTokPixelOptions, UmamiAnalyticsOptions, UsercentricsOptions, @@ -174,6 +175,7 @@ export const registryMeta: RegistryScriptMeta[] = [ m('intercom', 'Intercom', 'support', 'useScriptIntercom', { bundle: true, proxy: true }, PRIVACY_IP_ONLY), m('crisp', 'Crisp', 'support', 'useScriptCrisp', { bundle: true }, null), m('deskcrew', 'DeskCrew', 'support', 'useScriptDeskCrew', {}, null), + m('tawkTo', 'Tawk.to', 'support', 'useScriptTawkTo', {}, null), // cdn m('npm', 'NPM', 'cdn', 'useScriptNpm', { bundle: true }, null), // utility @@ -778,6 +780,13 @@ export async function registry(resolve?: (path: string) => Promise): Pro composableName: 'useScriptDeskCrew', envDefaults: { widgetKey: '', board: '' }, }), + // Bundle/proxy: unverified for Tawk, left off rather than guessed at. + def('tawkTo', { + schema: TawkToOptions, + label: 'Tawk.to', + category: 'support', + envDefaults: { propertyId: '', widgetId: '' }, + }), // cdn def('npm', { schema: NpmOptions, diff --git a/packages/script/src/runtime/registry/schemas.ts b/packages/script/src/runtime/registry/schemas.ts index 4683052e1..05ce35732 100644 --- a/packages/script/src/runtime/registry/schemas.ts +++ b/packages/script/src/runtime/registry/schemas.ts @@ -1203,6 +1203,21 @@ export const StripeOptions = object({ version: optional(union([literal('v3'), literal('acacia'), literal('basil'), literal('clover'), literal('dahlia'), string()])), }) +export const TawkToOptions = object({ + /** + * Your Tawk.to property ID: the first path segment of the widget embed URL + * `https://embed.tawk.to//`. + * @see https://dashboard.tawk.to/ + */ + propertyId: pipe(string(), minLength(1)), + /** + * Your Tawk.to widget ID: the second path segment of the widget embed URL + * `https://embed.tawk.to//`. + * @see https://dashboard.tawk.to/ + */ + widgetId: pipe(string(), minLength(1)), +}) + export const TikTokPixelOptions = object({ /** * Your TikTok Pixel ID. diff --git a/packages/script/src/runtime/registry/tawk-to.ts b/packages/script/src/runtime/registry/tawk-to.ts new file mode 100644 index 000000000..f28e35708 --- /dev/null +++ b/packages/script/src/runtime/registry/tawk-to.ts @@ -0,0 +1,332 @@ +import type { Ref } from 'vue' +import type { RegistryScriptInput, UseScriptContext } from '#nuxt-scripts/types' +import { joinURL } from 'ufo' +import { ref } from 'vue' +import { useRegistryScript } from '../utils' +import { TawkToOptions } from './schemas' + +export { TawkToOptions } + +export type TawkToInput = RegistryScriptInput + +export type TawkToStatus = 'online' | 'away' | 'offline' +export type TawkToWindowType = 'inline' | 'embed' +export type TawkToWidgetPosition = 'br' | 'bl' | 'cr' | 'cl' | 'tr' | 'tl' + +export interface TawkToVisitor { + name?: string + email?: string + /** Visitor phone number in E.164 format (e.g. `+15551234567`). */ + phone?: string + /** HMAC-SHA256 signature for Tawk's Secure Mode, generated server-side by the consumer. */ + hash?: string +} + +/** + * The `window.Tawk_API` surface, as exposed through `proxy`. `proxy` is + * fire-and-forget: unhead's script proxy queues/replays calls but always + * discards their return value, even once the script is fully loaded (and it + * has no `set` trap, so plain property assignment through it goes nowhere). + * That means only void-returning actions belong here - real getters and the + * `visitor` setter live on `useScriptTawkTo()`'s own return value instead + * (see `TawkToEvents`), backed directly by `window.Tawk_API`. + * @see https://developer.tawk.to/jsapi/ + */ +export interface TawkToApi { + /** Starts the chat. Pass `{ showWidget: true }` to also show the widget. */ + start: (options?: { showWidget?: boolean }) => void + shutdown: () => void + maximize: () => void + minimize: () => void + toggle: () => void + popup: () => void + showWidget: () => void + hideWidget: () => void + toggleVisibility: () => void + endChat: () => void + + getWindowType: () => TawkToWindowType + getStatus: () => TawkToStatus + isChatMaximized: () => boolean + isChatMinimized: () => boolean + isChatHidden: () => boolean + isChatOngoing: () => boolean + isVisitorEngaged: () => boolean + /** Set by Tawk once the widget has finished loading. The embed writes a boolean (`!0`), not a number. */ + onLoaded?: boolean + /** Set by Tawk before the widget begins loading. */ + onBeforeLoaded?: boolean + widgetPosition: () => TawkToWidgetPosition + + visitor?: TawkToVisitor + setAttributes: (attributes: Record, callback?: (error: Error | null) => void) => void + addEvent: (event: string, metadata?: Record, callback?: (error: Error | null) => void) => void + addTags: (tags: string[], callback?: (error: Error | null) => void) => void + removeTags: (tags: string[], callback?: (error: Error | null) => void) => void + switchWidget: (data: { propertyId: string, widgetId: string }, callback?: (error: Error | null) => void) => void +} + +declare global { + interface Window { + Tawk_API?: TawkToApi + Tawk_LoadStart?: Date + } +} + +/** + * The subset of `TawkToApi` that `proxy` actually exposes: the getters, the + * `visitor` setter and the `onLoaded`/`onBeforeLoaded` flags are omitted since + * none of them work through the fire-and-forget proxy (see `TawkToApi`'s doc + * comment). They're still real members of the underlying `window.Tawk_API` + * object, just not reachable via `proxy`. + */ +export type TawkToProxyApi = Omit + +/** + * Reactive state and typed event listeners bridged from the `window` + * `CustomEvent`s Tawk's embed script dispatches (`tawkLoad`, `tawkStatusChange`, etc). + * These aren't part of the documented `Tawk_API.onXxx = fn` callback-property API - + * they're a separate, verified-in-the-browser signal the embed script also fires. + */ +export interface TawkToEvents { + isHidden: Readonly> + isMinimized: Readonly> + isMaximized: Readonly> + /** The operator status Tawk reports (`getStatus()`) — not to be confused with `status`, the script's own load state. */ + chatStatus: Readonly> + unreadCount: Readonly> + + // Getters, called directly against `window.Tawk_API` (see `TawkToProxyApi`'s + // doc comment for why `proxy` can't carry these). `undefined` before the + // widget has loaded; the four `isXxx` booleans default to `false` instead + // since a definite "no" is a safe, honest answer before load. + getWindowType: () => TawkToWindowType | undefined + getStatus: () => TawkToStatus | undefined + isChatMaximized: () => boolean + isChatMinimized: () => boolean + isChatHidden: () => boolean + isChatOngoing: () => boolean + isVisitorEngaged: () => boolean + widgetPosition: () => TawkToWidgetPosition | undefined + + /** + * Sets `Tawk_API.visitor` directly - assigning through `proxy.visitor` is a no-op + * (no `set` trap). Pre-insertion only: Tawk honors `Tawk_API.visitor` until the + * embed script is requested, so a call after that warns and does nothing - use + * `window.Tawk_API.setAttributes()` for post-load identity changes. + */ + setVisitor: (data: TawkToVisitor) => void + + onLoad: (cb: () => void) => () => void + onBeforeLoad: (cb: () => void) => () => void + onStatusChange: (cb: (status: TawkToStatus) => void) => () => void + onChatMaximized: (cb: () => void) => () => void + onChatMinimized: (cb: () => void) => () => void + onChatHidden: (cb: () => void) => () => void + onChatStarted: (cb: () => void) => () => void + onChatEnded: (cb: () => void) => () => void + onPrechatSubmit: (cb: (data: Record) => void) => () => void + onOfflineSubmit: (cb: (data: Record) => void) => () => void + onChatMessageVisitor: (cb: (message: string) => void) => () => void + onChatMessageAgent: (cb: (message: string) => void) => () => void + onChatMessageSystem: (cb: (message: string) => void) => () => void + onAgentJoinChat: (cb: (data: Record) => void) => () => void + onAgentLeaveChat: (cb: (data: Record) => void) => () => void + onChatSatisfaction: (cb: (satisfaction: number) => void) => () => void + onVisitorNameChanged: (cb: (visitorName: string) => void) => () => void + onFileUpload: (cb: (link: string) => void) => () => void + onTagsUpdated: (cb: (data: Record) => void) => () => void + onUnreadCountChanged: (cb: (count: number) => void) => () => void +} + +// One Tawk widget exists per page, so its derived state is a module-level +// singleton shared by every useScriptTawkTo() call - not one ref tree per +// call, and not Nuxt's useState() (nothing here is ever known during SSR). +const isHidden = ref(false) +const isMinimized = ref(false) +const isMaximized = ref(false) +const chatStatus = ref('offline') +const unreadCount = ref(0) + +function listen(event: string, cb: (detail: D) => void): () => void { + if (import.meta.server) + return () => {} + const handler = (e: Event) => cb((e as CustomEvent).detail) + window.addEventListener(event, handler) + return () => window.removeEventListener(event, handler) +} + +// Bridges the window CustomEvents into the refs above. Guarded so it only +// wires up once no matter how many times useScriptTawkTo() is called. +let stateBridged = false +function ensureStateBridge() { + if (stateBridged) + return + stateBridged = true + listen('tawkLoad', () => { + isHidden.value = !!window.Tawk_API?.isChatHidden?.() + isMinimized.value = !!window.Tawk_API?.isChatMinimized?.() + isMaximized.value = !!window.Tawk_API?.isChatMaximized?.() + chatStatus.value = window.Tawk_API?.getStatus?.() ?? 'offline' + }) + listen('tawkStatusChange', (detail) => { + chatStatus.value = detail + }) + listen('tawkChatHidden', () => { + isHidden.value = true + }) + listen('tawkChatMinimized', () => { + isMinimized.value = true + isMaximized.value = false + }) + listen('tawkChatMaximized', () => { + isMaximized.value = true + isMinimized.value = false + }) + listen('tawkUnreadCountChanged', (detail) => { + unreadCount.value = detail + }) +} + +// Tawk fires `tawkChatHidden` when the widget hides but no matching event when +// it is shown again, so the ref would stick true forever after hideWidget() -> +// showWidget(). Resynchronise it from the API whenever a visibility command runs. +function resyncHiddenState() { + if (import.meta.server) + return + isHidden.value = !!window.Tawk_API?.isChatHidden?.() +} + +// Proxy commands that change widget visibility; reading through the wrapped +// proxy stays transparent. +const visibilityCommands = new Set(['hideWidget', 'showWidget', 'toggleVisibility']) +const TAWK_PROXY_DECORATED = Symbol('nuxt-scripts.tawk-proxy-decorated') + +export function useScriptTawkTo(_options?: TawkToInput): UseScriptContext & TawkToEvents { + const instance = useRegistryScript('tawkTo', options => ({ + scriptInput: { + src: joinURL('https://embed.tawk.to', options.propertyId, options.widgetId), + async: true, + crossorigin: 'anonymous', + }, + schema: import.meta.dev ? TawkToOptions : undefined, + scriptOptions: { + resolve({ waitFor }) { + if (window.Tawk_API?.onLoaded) + return window.Tawk_API as TawkToProxyApi as T + + return waitFor((resolve, reject) => { + const stop = listen('tawkLoad', () => { + stop() + if (window.Tawk_API) + resolve(window.Tawk_API as TawkToProxyApi as T) + else + reject(new Error('[nuxt-scripts] Tawk.to reported ready without exposing window.Tawk_API')) + }) + return stop + }) + }, + }, + clientInit: import.meta.server + ? undefined + : () => { + // Installs the `Tawk_API` stub and `Tawk_LoadStart` the same way + // Tawk's own embed snippet does before its script tag. unhead runs + // this via beforeInit during the composable call - before the embed + // script is requested - so it must not close setVisitor's + // pre-insertion window (that is derived from the script's `status`, + // see setVisitor below). + window.Tawk_API = window.Tawk_API || {} as TawkToApi + window.Tawk_LoadStart = new Date() + }, + }), _options) as UseScriptContext & TawkToEvents + + if (!import.meta.server) { + ensureStateBridge() + + // `proxy` lives on the shared script, and every caller gets its own consumer + // scope over it. Decorate the shared object so later callers inherit the + // wrapper instead of reading the bare proxy off the prototype. + const shared = ((instance as any).script || instance) as { + proxy: typeof instance.proxy + [TAWK_PROXY_DECORATED]?: boolean + } + if (shared.proxy && !shared[TAWK_PROXY_DECORATED]) { + shared.proxy = new Proxy(shared.proxy, { + get(target, prop, receiver) { + const value = Reflect.get(target, prop, receiver) + if (!(typeof prop === 'string' && visibilityCommands.has(prop)) || typeof value !== 'function') + return value + return (...args: unknown[]) => { + ;(value as (...a: unknown[]) => void)(...args) + resyncHiddenState() + } + }, + }) as typeof instance.proxy + Object.defineProperty(shared, TAWK_PROXY_DECORATED, { value: true }) + } + } + + // The refs are module-level singletons (see above); consumers only get the + // Readonly> view so mutation stays confined to the state bridge. + instance.isHidden = isHidden + instance.isMinimized = isMinimized + instance.isMaximized = isMaximized + instance.chatStatus = chatStatus + instance.unreadCount = unreadCount + instance.onLoad = cb => listen('tawkLoad', cb) + instance.onBeforeLoad = cb => listen('tawkBeforeLoad', cb) + instance.onStatusChange = cb => listen('tawkStatusChange', cb) + instance.onChatMaximized = cb => listen('tawkChatMaximized', cb) + instance.onChatMinimized = cb => listen('tawkChatMinimized', cb) + instance.onChatHidden = cb => listen('tawkChatHidden', cb) + instance.onChatStarted = cb => listen('tawkChatStarted', cb) + instance.onChatEnded = cb => listen('tawkChatEnded', cb) + instance.onPrechatSubmit = cb => listen('tawkPrechatSubmit', cb) + instance.onOfflineSubmit = cb => listen('tawkOfflineSubmit', cb) + instance.onChatMessageVisitor = cb => listen('tawkChatMessageVisitor', cb) + instance.onChatMessageAgent = cb => listen('tawkChatMessageAgent', cb) + instance.onChatMessageSystem = cb => listen('tawkChatMessageSystem', cb) + instance.onAgentJoinChat = cb => listen('tawkAgentJoinChat', cb) + instance.onAgentLeaveChat = cb => listen('tawkAgentLeaveChat', cb) + instance.onChatSatisfaction = cb => listen('tawkChatSatisfaction', cb) + instance.onVisitorNameChanged = cb => listen('tawkVisitorNameChanged', cb) + instance.onFileUpload = cb => listen('tawkFileUpload', cb) + instance.onTagsUpdated = cb => listen('tawkTagsUpdated', cb) + instance.onUnreadCountChanged = cb => listen('tawkUnreadCountChanged', cb) + + // Called directly against window.Tawk_API rather than through `proxy`, + // which discards every return value (see TawkToProxyApi's doc comment). + // The method access is optional (`?.()`) because clientInit only installs a + // bare `{}` stub until the embed script adds the real methods - the contract + // is undefined/false before load, never a TypeError. + instance.getWindowType = () => import.meta.server ? undefined : window.Tawk_API?.getWindowType?.() + instance.getStatus = () => import.meta.server ? undefined : window.Tawk_API?.getStatus?.() + instance.isChatMaximized = () => !import.meta.server && !!window.Tawk_API?.isChatMaximized?.() + instance.isChatMinimized = () => !import.meta.server && !!window.Tawk_API?.isChatMinimized?.() + instance.isChatHidden = () => !import.meta.server && !!window.Tawk_API?.isChatHidden?.() + instance.isChatOngoing = () => !import.meta.server && !!window.Tawk_API?.isChatOngoing?.() + instance.isVisitorEngaged = () => !import.meta.server && !!window.Tawk_API?.isVisitorEngaged?.() + instance.widgetPosition = () => import.meta.server ? undefined : window.Tawk_API?.widgetPosition?.() + instance.setVisitor = (data) => { + if (import.meta.server) + return + // Before clientInit creates the stub, create or reuse it so the visitor is + // not silently dropped - Tawk honors `Tawk_API.visitor` set pre-load. + window.Tawk_API = window.Tawk_API || {} as TawkToApi + // Tawk only honors `Tawk_API.visitor` before the embed script is requested. + // unhead runs clientInit during the composable call, so the cutoff cannot + // be derived from it - it reads the script's own lifecycle instead: once + // `status` leaves `awaitingLoad` the embed has been requested and + // insertion is in flight (and `onLoaded` means the widget finished + // loading). Past that point the write would be dropped - warn and do + // nothing; use `setAttributes()` for post-load identity changes. + if (instance.status.value !== 'awaitingLoad' || window.Tawk_API.onLoaded) { + console.warn('[nuxt-scripts] Tawk.to: setVisitor() only works before the widget script is inserted. Tawk drops visitor data written after that - set it before the widget loads, or use window.Tawk_API.setAttributes({ name, email, phone, hash }) afterwards.') + return + } + window.Tawk_API.visitor = data + } + + return instance +} diff --git a/packages/script/src/runtime/types.ts b/packages/script/src/runtime/types.ts index 5db5700bf..06f6fc345 100644 --- a/packages/script/src/runtime/types.ts +++ b/packages/script/src/runtime/types.ts @@ -43,6 +43,7 @@ import type { SegmentInput } from './registry/segment' import type { SnapTrPixelInput } from './registry/snapchat-pixel' import type { SpeedCurveInput } from './registry/speedcurve' import type { StripeInput } from './registry/stripe' +import type { TawkToInput } from './registry/tawk-to' import type { TikTokPixelInput } from './registry/tiktok-pixel' import type { UmamiAnalyticsInput } from './registry/umami-analytics' import type { UsercentricsInput } from './registry/usercentrics' @@ -286,6 +287,7 @@ export interface ScriptRegistry { segment?: SegmentInput speedcurve?: SpeedCurveInput stripe?: StripeInput + tawkTo?: TawkToInput tiktokPixel?: TikTokPixelInput xEmbed?: XEmbedInput xPixel?: XPixelInput @@ -310,7 +312,7 @@ export type BuiltInRegistryScriptKey | 'plausibleAnalytics' | 'googleAdsense' | 'googleAnalytics' | 'googleMaps' | 'leaflet' | 'maplibre' | 'googleRecaptcha' | 'googleSignIn' | 'lemonSqueezy' | 'googleTagManager' | 'hotjar' | 'intercom' | 'linkedinInsight' | 'paypal' | 'posthog' | 'pulseAnalytics' | 'matomoAnalytics' - | 'mixpanelAnalytics' | 'rybbitAnalytics' | 'redditPixel' | 'segment' | 'stripe' | 'tiktokPixel' + | 'mixpanelAnalytics' | 'rybbitAnalytics' | 'redditPixel' | 'segment' | 'stripe' | 'tawkTo' | 'tiktokPixel' | 'xEmbed' | 'xPixel' | 'snapchatPixel' | 'speedcurve' | 'youtubePlayer' | 'vercelAnalytics' | 'vimeoPlayer' | 'umamiAnalytics' | 'usercentrics' | 'gravatar' | 'npm' diff --git a/packages/script/src/script-meta.ts b/packages/script/src/script-meta.ts index e5046d8c9..bc9ecf78e 100644 --- a/packages/script/src/script-meta.ts +++ b/packages/script/src/script-meta.ts @@ -151,6 +151,11 @@ export const scriptMeta = { trackedData: ['user-identity', 'events', 'errors'], testId: 'pub_deskcrewdemo', }, + tawkTo: { + urls: ['https://embed.tawk.to/68496650ddf9cd19094b4530/1itfbfagd'], + trackedData: ['user-identity', 'events'], + testId: '68496650ddf9cd19094b4530', + }, crisp: { urls: ['https://client.crisp.chat/l.js'], diff --git a/playground/nuxt.config.ts b/playground/nuxt.config.ts index 4274a04c4..3d576e743 100644 --- a/playground/nuxt.config.ts +++ b/playground/nuxt.config.ts @@ -41,6 +41,7 @@ export default defineNuxtConfig({ intercom: { app_id: 'akg5rmxb' }, crisp: { id: 'b1021910-7ace-425a-9ef5-07f49e5ce417' }, deskcrew: { widgetKey: 'pub_deskcrewdemo', board: 'demo' }, + tawkTo: { propertyId: '68496650ddf9cd19094b4530', widgetId: '1itfbfagd' }, }, }, }, @@ -111,6 +112,7 @@ export default defineNuxtConfig({ intercom: { app_id: 'akg5rmxb', trigger: 'manual' }, crisp: { id: 'b1021910-7ace-425a-9ef5-07f49e5ce417', trigger: 'manual' }, deskcrew: { widgetKey: 'pub_deskcrewdemo', board: 'demo', trigger: 'manual' }, + tawkTo: { propertyId: '68496650ddf9cd19094b4530', widgetId: '1itfbfagd', trigger: 'manual' }, // Media youtubePlayer: { trigger: 'manual' }, diff --git a/playground/pages/index.vue b/playground/pages/index.vue index 7194f5b64..47a2d822c 100644 --- a/playground/pages/index.vue +++ b/playground/pages/index.vue @@ -41,6 +41,7 @@ function getPlaygroundPath(script: any): string | null { 'intercom': '/third-parties/intercom/facade', 'crisp': '/third-parties/crisp/facade', 'deskcrew': '/third-parties/deskcrew/facade', + 'tawk.to': '/third-parties/tawk-to/use-script', 'stripe': '/third-parties/stripe/nuxt-scripts', 'paypal': '/third-parties/paypal/nuxt-scripts', 'lemon-squeezy': '/third-parties/lemon-squeezy/component', diff --git a/playground/pages/third-parties/tawk-to/use-script.vue b/playground/pages/third-parties/tawk-to/use-script.vue new file mode 100644 index 000000000..da3b2b9da --- /dev/null +++ b/playground/pages/third-parties/tawk-to/use-script.vue @@ -0,0 +1,333 @@ + + + diff --git a/test/types/types.test-d.ts b/test/types/types.test-d.ts index 02b8aca8c..6d1e8b8f7 100644 --- a/test/types/types.test-d.ts +++ b/test/types/types.test-d.ts @@ -2,6 +2,7 @@ import type { ModuleOptions } from '../../packages/script/src/module' import type { CrispApi } from '../../packages/script/src/runtime/registry/crisp' import type { DeskCrewApi, DeskCrewEmbedOptions } from '../../packages/script/src/runtime/registry/deskcrew' import type { DefaultEventName } from '../../packages/script/src/runtime/registry/google-analytics' +import type { TawkToApi, TawkToProxyApi, TawkToVisitor, TawkToWindowType } from '../../packages/script/src/runtime/registry/tawk-to' import type { TikTokPixelApi, useScriptTikTokPixel } from '../../packages/script/src/runtime/registry/tiktok-pixel' import type { NuxtConfigScriptRegistry, NuxtConfigScriptRegistryEntry, NuxtUseScriptOptions, RegistryScriptInput, ScriptRegistry, UseFunctionType, UseScriptContext } from '../../packages/script/src/runtime/types' import { describe, expectTypeOf, it } from 'vitest' @@ -48,6 +49,7 @@ describe('module options registry', () => { expectTypeOf().not.toBeAny() expectTypeOf().not.toBeAny() expectTypeOf().not.toBeAny() + expectTypeOf().not.toBeAny() expectTypeOf().not.toBeAny() expectTypeOf().not.toBeAny() expectTypeOf().not.toBeAny() @@ -215,3 +217,39 @@ describe('tiktok pixel ttq methods', () => { expectTypeOf().toBeCallableWith('StartTrial') }) }) + +describe('tawk-to proxy api', () => { + it('visitor accepts the documented optional phone field', () => { + expectTypeOf().toHaveProperty('phone') + expectTypeOf().toEqualTypeOf() + expectTypeOf().toExtend<{ name?: string, email?: string, phone?: string, hash?: string }>() + }) + + it('omits the load flags the fire-and-forget proxy cannot carry', () => { + // `onLoaded`/`onBeforeLoaded` are plain data properties Tawk writes itself; + // the proxy has no set trap and discards values, so a typed read of them + // through `proxy` would always be wrong. + type Flags = Extract + expectTypeOf().toBeNever() + }) + + it('window type uses the documented inline/embed literals', () => { + expectTypeOf().toEqualTypeOf<'inline' | 'embed'>() + }) + + it('onLoaded is a boolean, matching the embed that writes `!0`', () => { + expectTypeOf().toEqualTypeOf() + }) + + it('start accepts its documented optional configuration object', () => { + expectTypeOf().toBeCallableWith() + expectTypeOf().toBeCallableWith({ showWidget: true }) + }) + + it('switchWidget callback receives the error argument Tawk passes', () => { + expectTypeOf().toBeCallableWith( + { propertyId: 'property-id', widgetId: 'widget-id' }, + (_error: Error | null) => {}, + ) + }) +}) diff --git a/test/unit/proxy-configs.test.ts b/test/unit/proxy-configs.test.ts index 3bdc5c8bf..6cdd805d0 100644 --- a/test/unit/proxy-configs.test.ts +++ b/test/unit/proxy-configs.test.ts @@ -409,6 +409,11 @@ describe('proxy configs', () => { expect(config).toBeUndefined() }) + it('does not return proxy config for tawkTo (runtime network behavior unverified)', async () => { + const config = (await getProxyConfigs()).tawkTo + expect(config).toBeUndefined() + }) + it('returns proxy config for calendly', async () => { const config = (await getProxyConfigs()).calendly expect(config).toBeDefined() @@ -464,6 +469,7 @@ describe('proxy configs', () => { expect(configs).toHaveProperty('intercom') expect(configs).not.toHaveProperty('crisp') expect(configs).not.toHaveProperty('deskcrew') + expect(configs).not.toHaveProperty('tawkTo') expect(configs).toHaveProperty('vercelAnalytics') expect(configs).toHaveProperty('gravatar') expect(configs).toHaveProperty('calendly') diff --git a/test/unit/registry-readiness.test.ts b/test/unit/registry-readiness.test.ts index a14c210a2..6c04feee5 100644 --- a/test/unit/registry-readiness.test.ts +++ b/test/unit/registry-readiness.test.ts @@ -5,19 +5,40 @@ import { beforeEach, describe, expect, it, vi } from 'vitest' import { ref } from 'vue' import { useScriptCrisp } from '../../packages/script/src/runtime/registry/crisp' import { useScriptGoogleMaps } from '../../packages/script/src/runtime/registry/google-maps' +import { useScriptTawkTo } from '../../packages/script/src/runtime/registry/tawk-to' import { useScriptUsercentrics } from '../../packages/script/src/runtime/registry/usercentrics' const mocks = vi.hoisted(() => ({ definitions: new Map(), useRegistryScript: vi.fn(), + useScript: vi.fn(), + resolveScriptKey: (input: any) => input.key || input.src || (typeof input.innerHTML === 'string' ? input.innerHTML : ''), + createError: vi.fn(), + useRuntimeConfig: vi.fn(() => ({ + public: { + 'scripts': {}, + 'nuxt-scripts': { defaultScriptOptions: {} }, + 'nuxt-scripts-devtools': {}, + }, + })), })) vi.mock('@unhead/vue', () => ({ useHead: vi.fn() })) +vi.mock('nuxt/app', () => ({ + createError: mocks.createError, + useRuntimeConfig: mocks.useRuntimeConfig, +})) + vi.mock('../../packages/script/src/runtime/utils', () => ({ useRegistryScript: mocks.useRegistryScript, })) +vi.mock('../../packages/script/src/runtime/composables/useScript', () => ({ + useScript: mocks.useScript, + resolveScriptKey: mocks.resolveScriptKey, +})) + function createResolverWait() { let cleanup: void | (() => void) const waitFor = (setup: (resolve: (value: T) => void, reject: (reason?: unknown) => void) => void | (() => void)) => new Promise((outerResolve, outerReject) => { @@ -45,18 +66,21 @@ describe('registry script readiness resolvers', () => { delete (window as any).$crisp delete window.CRISP_READY_TRIGGER delete window.__ucCmp + delete window.Tawk_API mocks.useRegistryScript.mockImplementation((key, factory) => { const options = { crisp: { id: 'website-id' }, googleMaps: { apiKey: 'maps-key' }, usercentrics: { rulesetId: 'ruleset-id' }, - }[key as 'crisp' | 'googleMaps' | 'usercentrics'] + tawkTo: { propertyId: 'test-property', widgetId: 'test-widget' }, + }[key as 'crisp' | 'googleMaps' | 'usercentrics' | 'tawkTo'] const definition = factory(options || {}) mocks.definitions.set(key, definition) return { status: ref('awaitingLoad'), signal: new AbortController().signal, load: vi.fn(), + proxy: new Proxy({}, { get: () => () => {} }), } }) }) @@ -108,4 +132,181 @@ describe('registry script readiness resolvers', () => { await expect(apiPromise).resolves.toEqual({ ucCmp: api }) expect(removeEventListener).toHaveBeenCalledWith('UC_CMP_API_READY', expect.any(Function)) }) + + it('resolves Tawk.to from the tawkLoad window event', async () => { + const api = { + onLoaded: undefined, + isChatHidden: vi.fn(() => false), + isChatMinimized: vi.fn(() => false), + isChatMaximized: vi.fn(() => false), + getStatus: vi.fn(() => 'online'), + } as any + window.Tawk_API = api + useScriptTawkTo({ propertyId: 'test-property', widgetId: 'test-widget' }) + const resolver = createResolverWait() + const apiPromise = mocks.definitions.get('tawkTo').scriptOptions.resolve(resolver) + + window.dispatchEvent(new CustomEvent('tawkLoad')) + + await expect(apiPromise).resolves.toBe(api) + }) + + // The shipped embed script writes `window.Tawk_API.onLoaded = !0` (boolean + // true), not the number 1 - the fast path must honor the real value. + it('resolves Tawk.to immediately when already loaded (onLoaded === true)', () => { + const api = { onLoaded: true } as any + window.Tawk_API = api + useScriptTawkTo({ propertyId: 'test-property', widgetId: 'test-widget' }) + const result = mocks.definitions.get('tawkTo').scriptOptions.resolve(createResolverWait()) + + expect(result).toBe(api) + }) + + it('warns when setVisitor is called after the widget has loaded (onLoaded === true)', () => { + const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}) + const api = { onLoaded: true } as any + window.Tawk_API = api + const instance = useScriptTawkTo({ propertyId: 'test-property', widgetId: 'test-widget' }) + + instance.setVisitor({ name: 'Jane Doe' }) + + expect(warn).toHaveBeenCalledWith(expect.stringContaining('setVisitor')) + expect(warn).toHaveBeenCalledWith(expect.stringContaining('before the widget script is inserted')) + // The warning must recommend the full TawkToVisitor surface, including phone. + expect(warn).toHaveBeenCalledWith(expect.stringContaining('phone')) + expect(api.visitor).toBeUndefined() + warn.mockRestore() + }) + + it('creates the Tawk_API stub and assigns visitor when setVisitor is called before clientInit', () => { + const instance = useScriptTawkTo({ propertyId: 'test-property', widgetId: 'test-widget' }) + + instance.setVisitor({ name: 'Jane' }) + + expect(window.Tawk_API).toBeDefined() + expect(window.Tawk_API!.visitor).toEqual({ name: 'Jane' }) + }) + + // Regression: unhead invokes the wrapped beforeInit (which runs clientInit) + // synchronously during the composable call. The setVisitor pre-insertion + // window must not be derived from that moment, or the documented pre-load + // path becomes unreachable (every call warns and silently drops the data). + // It stays open until the embed script is actually requested (status leaves + // `awaitingLoad`), which happens at the trigger (default: onMounted), not at + // composable-call time. This exercises the real useRegistryScript wiring by + // only mocking the `useScript` composable. + it('keeps setVisitor working after the composable call until the embed script is actually requested', async () => { + vi.resetModules() + vi.doUnmock('../../packages/script/src/runtime/utils') + const { useScriptTawkTo: useScriptTawkToRealRegistry } = await import('../../packages/script/src/runtime/registry/tawk-to') + const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}) + const scriptStatus = ref('awaitingLoad') + // Mimic unhead's _useScript: beforeInit (and therefore clientInit) runs + // synchronously inside the composable call, before any script request. + mocks.useScript.mockImplementation((_input: any, options: any) => { + options?.beforeInit?.() + return { + id: 'tawkTo', + status: scriptStatus, + signal: new AbortController().signal, + load: vi.fn(), + proxy: new Proxy({}, { get: () => () => {} }), + } + }) + + try { + const instance = useScriptTawkToRealRegistry({ propertyId: 'test-property', widgetId: 'test-widget' }) + + instance.setVisitor({ name: 'Jane Doe' }) + + expect(warn).not.toHaveBeenCalled() + expect(window.Tawk_API!.visitor).toEqual({ name: 'Jane Doe' }) + + // unhead flips the status when it actually requests the embed script; + // from that point Tawk drops the write. + scriptStatus.value = 'loading' + warn.mockClear() + + instance.setVisitor({ name: 'Other' }) + + expect(warn).toHaveBeenCalledWith(expect.stringContaining('setVisitor')) + expect(window.Tawk_API!.visitor).toEqual({ name: 'Jane Doe' }) + } + finally { + warn.mockRestore() + mocks.useScript.mockReset() + } + }) + + // clientInit installs a bare `{}` Tawk_API stub; the getters must degrade to + // undefined/false instead of throwing TypeError on the missing methods. + it('returns undefined/false from every getter while only the Tawk_API stub exists', () => { + window.Tawk_API = {} as any + const instance = useScriptTawkTo({ propertyId: 'test-property', widgetId: 'test-widget' }) + + expect(instance.getWindowType()).toBeUndefined() + expect(instance.getStatus()).toBeUndefined() + expect(instance.isChatMaximized()).toBe(false) + expect(instance.isChatMinimized()).toBe(false) + expect(instance.isChatHidden()).toBe(false) + expect(instance.isChatOngoing()).toBe(false) + expect(instance.isVisitorEngaged()).toBe(false) + expect(instance.widgetPosition()).toBeUndefined() + }) + + // Tawk fires `tawkChatHidden` on hide but no matching event on show, so the + // ref must resynchronize when a visibility command runs. + it('resets isHidden when a visibility command runs after the widget was hidden', () => { + window.Tawk_API = { isChatHidden: vi.fn(() => false) } as any + const instance = useScriptTawkTo({ propertyId: 'test-property', widgetId: 'test-widget' }) + + window.dispatchEvent(new CustomEvent('tawkChatHidden')) + expect(instance.isHidden.value).toBe(true) + + instance.proxy.showWidget() + expect(instance.isHidden.value).toBe(false) + }) + + // useScript hands every caller its own consumer scope over one shared script + // object, and `proxy` lives on that shared object. Decorating the scope means + // the second caller reads the undecorated proxy straight off the prototype. + it('resyncs isHidden for every caller, not only the first', () => { + window.Tawk_API = { isChatHidden: vi.fn(() => false) } as any + const sharedScript: any = { proxy: new Proxy({}, { get: () => () => {} }) } + mocks.useRegistryScript.mockImplementation((key: string, factory: (o: any) => any) => { + mocks.definitions.set(key, factory({ propertyId: 'test-property', widgetId: 'test-widget' })) + const scope = Object.create(sharedScript) + scope.status = ref('awaitingLoad') + scope.signal = new AbortController().signal + scope.load = vi.fn() + scope.script = sharedScript + return scope + }) + + useScriptTawkTo({ propertyId: 'test-property', widgetId: 'test-widget' }) + const second = useScriptTawkTo({ propertyId: 'test-property', widgetId: 'test-widget' }) + + window.dispatchEvent(new CustomEvent('tawkChatHidden')) + expect(second.isHidden.value).toBe(true) + + second.proxy.showWidget() + expect(second.isHidden.value).toBe(false) + }) + + // Runs last: once unhead actually requests the embed script (status leaves + // `awaitingLoad`), Tawk no longer honors `Tawk_API.visitor` writes - even + // before `onLoaded` is set. + it('warns and drops setVisitor once the embed script has been requested, even before onLoaded', () => { + const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}) + const instance = useScriptTawkTo({ propertyId: 'test-property', widgetId: 'test-widget' }) + // unhead flips the status when the trigger fires and the embed is requested. + instance.status.value = 'loading' + expect(window.Tawk_API?.onLoaded).toBeUndefined() + + instance.setVisitor({ name: 'Jane Doe' }) + + expect(warn).toHaveBeenCalledWith(expect.stringContaining('setVisitor')) + expect(window.Tawk_API!.visitor).toBeUndefined() + warn.mockRestore() + }) })