import { Analytics } from '../../core/analytics' import { Context } from '../../core/context' import { Plugin } from '../../core/plugin' import { hasQueryString } from '../../core/query-string' import { InAppEvents, InboxEvents, JourneysEvents, newEvent, allEvents, ContentType, } from './events' import Gist, { type GistConfig, type ColorScheme, type EmbedPayload, } from 'customerio-gist-web' import type { InboxAPI, InboxMessage, GistInboxMessage, InboxActionConfig, InboxMessageActionParams } from './inbox_messages' import { createInboxAPI } from './inbox_messages' export { InAppEvents, InboxEvents } export type { InboxAPI, InboxMessage, ColorScheme } export type InAppPluginSettings = { siteId?: string events?: EventListenerOrEventListenerObject | null _env?: GistConfig['env'] _logging?: GistConfig['logging'] anonymousInApp?: boolean enabled?: boolean /** * Set by a host that only places embedded messages — a landing-page snippet, * typically. The SDK then renders the embeds declared on the page and starts * none of the delivery machinery: no user queue, SSE, guest session or inbox. * Leave unset for a workspace that also receives in-app messages, so both * work on the same page. */ embedOnly?: boolean /** * Controls the color scheme for in-app messages. * - `'default'` — always use light mode * - `'system'` — follow the user's OS-level color scheme preference * - `'auto'` — detect the color scheme from the page and react to live changes * * Defaults to `'default'` (light) when not specified. */ colorScheme?: GistConfig['colorScheme'] } /** * Mounts the embeds the page declares, and cannot fail the caller: mounting is * best-effort page content, and nothing it does should be able to reject * analytics.load. Both arms are needed — a synchronous throw is evaluated * before Promise.resolve, so .catch alone would not see it. * * Deliberately not awaited: the SDK waits for each container to appear, which * must not hold up analytics.load. */ function mountEmbedsSafely(): void { const failed = (error: unknown) => _error(`Failed to mount embedded messages: ${String(error)}`) try { Promise.resolve(Gist.mountEmbeds()).catch(failed) } catch (error) { failed(error) } } /** * Reporting identity for content that belongs to no campaign — an anonymous * broadcast, or an embed the page supplied. Both report as the same content * event through the same call: the pipeline requires an integer contentId and * templateId (services core/batch/batch.go), so an embed payload has to carry * them exactly as a broadcast does. * * Says so when they are incomplete rather than resolving quietly: such an * event is accepted at the edge and dropped by the consumer, which is silent * from here, so the metric would otherwise simply never appear. */ function resolveContentIds(message: any): { contentId?: number templateId?: number } { const gist = message?.properties?.gist const broadcast = gist?.broadcast const ids = broadcast ? { contentId: broadcast.broadcastIdInt || broadcast.broadcastId, templateId: broadcast.templateId, } : { contentId: gist?.contentId, templateId: gist?.templateId } if (message?.embedId && !(ids.contentId && ids.templateId)) { _error( `Embedded message ${message.embedId} carries no contentId/templateId, so its events cannot be reported.` ) } else if (ids.contentId && !ids.templateId) { _error( `Content event for contentId ${ids.contentId} has no templateId; the pipeline requires both and will drop it.` ) } return ids } if (hasQueryString('cio_debug_session', 'true')) { Gist.setupDebugOverlay?.() } export function InAppPlugin(settings: InAppPluginSettings): Plugin { let _analytics: Analytics let _gistLoaded = false let _pluginLoaded = false const _eventTarget: EventTarget = new EventTarget() async function setAnonymousId() { const anonymousId = _analytics.user().anonymousId() if (anonymousId) { await Gist.setCustomAttribute('cio_anonymous_id', anonymousId) } } function attachListeners() { if (!_gistLoaded || _pluginLoaded) return _analytics.on('reset', reset) if (settings.events) { allEvents.forEach((event) => { _eventTarget.addEventListener( event, settings?.events as EventListenerOrEventListenerObject ) }) Gist.events.on('messageError', (message: any) => { _eventTarget.dispatchEvent( newEvent(InAppEvents.MessageError, { messageId: message.messageId, deliveryId: message.properties?.gist?.campaignId, }) ) }) } Gist.events.on('messageDismissed', (message: any) => { const deliveryId: string = message?.properties?.gist?.campaignId if (settings.events) { _eventTarget.dispatchEvent( newEvent(InAppEvents.MessageDismissed, { messageId: message?.messageId, deliveryId: deliveryId, }) ) } // The SDK fires messageDismissed for every removal and carries the // reason; only the visitor closing the message meters as dismissed. The // reason is required rather than defaulted, so an SDK that predates it // (which fired this for snoozes and displacements too) cannot overcount. if (message?.dismissReason !== 'dismissed') { return } // A campaign-delivered message has no dismissed delivery metric; only // anonymous broadcasts and embeds meter dismissals, as content events. if (typeof deliveryId !== 'undefined' && deliveryId !== '') { return } const { contentId, templateId } = resolveContentIds(message) if (contentId) { void _analytics.track(JourneysEvents.Content, { actionType: JourneysEvents.DismissedContent, contentId: contentId, templateId: templateId, contentType: ContentType, }) } }) Gist.events.on('messageShown', (message: any) => { const deliveryId: string = message?.properties?.gist?.campaignId if (settings.events) { _eventTarget.dispatchEvent( newEvent(InAppEvents.MessageOpened, { messageId: message?.messageId, deliveryId: deliveryId, message: { dismiss: function () { void Gist.dismissMessage(message?.instanceId) }, }, }) ) } if (typeof deliveryId !== 'undefined' && deliveryId !== '') { void _analytics.track(JourneysEvents.Metric, { deliveryId: deliveryId, metric: JourneysEvents.Opened, }) return } const { contentId, templateId } = resolveContentIds(message) if (contentId) { void _analytics.track(JourneysEvents.Content, { actionType: JourneysEvents.ViewedContent, contentId: contentId, templateId: templateId, contentType: ContentType, }) } }) Gist.events.on('inboxMessageAction', (event: unknown) => { const params = event as InboxMessageActionParams if (params?.message && params?.action) { if (settings.events) { const { message, action, actionConfig } = params if (action === 'opened') { _eventTarget.dispatchEvent( newEvent(InboxEvents.MessageOpened, { messageId: message.queueId, deliveryId: message.deliveryId, }) ) } else if (action === 'dismissed') { _eventTarget.dispatchEvent( newEvent(InboxEvents.MessageDismissed, { messageId: message.queueId, deliveryId: message.deliveryId, }) ) } else if (action === 'clicked') { _eventTarget.dispatchEvent( newEvent(InboxEvents.MessageAction, { messageId: message.queueId, deliveryId: message.deliveryId, action: actionConfig?.action, name: actionConfig?.name, actionName: actionConfig?.name, actionValue: actionConfig?.action, }) ) } } _handleInboxMessageAction( _analytics, params.message, params.action, params.actionConfig ) } }) Gist.events.on('messageAction', (params: any) => { const deliveryId: string = params?.message?.properties?.gist?.campaignId if (settings.events) { _eventTarget.dispatchEvent( newEvent(InAppEvents.MessageAction, { messageId: params.message.messageId, deliveryId: deliveryId, action: params.action, name: params.name, actionName: params.name, actionValue: params.action, message: { dismiss: function () { void Gist.dismissMessage(params.message.instanceId) }, }, }) ) } if (params.action === 'gist://close') { return } if (typeof deliveryId !== 'undefined' && deliveryId !== '') { void _analytics.track(JourneysEvents.Metric, { deliveryId: deliveryId, metric: JourneysEvents.Clicked, actionName: params.name, actionValue: params.action, }) return } const { contentId, templateId } = resolveContentIds(params?.message) if (contentId) { void _analytics.track(JourneysEvents.Content, { actionType: JourneysEvents.ClickedContent, contentId: contentId, templateId: templateId, contentType: ContentType, actionName: params.name, actionValue: params.action, }) } }) Gist.events.on('eventDispatched', (gistEvent: any) => { if (gistEvent.name === 'analytics:track') { const trackEventName: string = gistEvent.payload?.event if (typeof trackEventName === 'undefined' || trackEventName === '') { return } void _analytics.track( trackEventName, gistEvent.payload?.properties, gistEvent.payload?.options ) } }) } function page(ctx: Context): Context { if (!_pluginLoaded) return ctx const page: string = ctx.event?.properties?.name ?? ctx.event?.properties?.url if (typeof page === 'string' && page.length > 0) { void Gist.setCurrentRoute(page) } // Payload blocks are scanned once when the plugin loads, so an app that // renders embed markup client-side would never be noticed. page() is the // signal such an app already sends on navigation, and re-scanning is cheap: // one querySelectorAll, and embeds already on screen are skipped. mountEmbedsSafely() return ctx } async function reset(ctx: Context): Promise { await Gist.clearUserToken() await Gist.clearCustomAttributes() await setAnonymousId() return ctx } async function syncUserToken(ctx: Context): Promise { if (!_gistLoaded) return ctx const user = _analytics.user().id() if (typeof user === 'string' && user.length > 0) { await Gist.setUserToken(user) } else { await Gist.clearUserToken() } return ctx } const customerio: Plugin = { name: 'Customer.io In-App Plugin', type: 'before', version: '0.0.1', isLoaded: (): boolean => _pluginLoaded, load: async (ctx: Context, instance: Analytics) => { _analytics = instance // An embed-only host has no queue to authenticate against, so it can run // without a siteId — the workspace supplies one only when in-app // messaging is enabled for it. if ( !settings.embedOnly && (settings.siteId == null || settings.siteId === '') ) { _error("siteId is required. Can't initialize.") return ctx } await setAnonymousId() await Gist.setup({ siteId: settings.siteId ?? '', env: settings._env ? settings._env : 'prod', logging: settings._logging, useAnonymousSession: settings.anonymousInApp, colorScheme: settings.colorScheme, embedOnly: settings.embedOnly, }) _gistLoaded = true await syncUserToken(ctx) attachListeners() ;(instance as any).inbox = (...topics: string[]): InboxAPI => { if (!_pluginLoaded) { throw new Error( 'Customer.io In-App Plugin is not loaded yet. Ensure the plugin is initialized before calling inbox().' ) } return createInboxAPI(instance, Gist, topics) } ;(instance as any).embed = async ( payload: EmbedPayload ): Promise => Gist.embed(payload) _pluginLoaded = true // Listeners are already attached, so the view each embed reports on // render is captured. mountEmbedsSafely() return Promise.resolve() }, identify: syncUserToken, page: page, unload: () => { if (settings.events) { allEvents.forEach((event) => { _eventTarget.removeEventListener( event, settings?.events as EventListenerOrEventListenerObject ) }) } }, } return customerio } function _handleInboxMessageAction( analyticsInstance: Analytics, message: GistInboxMessage, action: InboxMessageActionParams['action'], actionConfig?: InboxActionConfig ) { const deliveryId = message?.deliveryId if (typeof deliveryId === 'undefined' || deliveryId === '') { return } if (action === 'opened') { void analyticsInstance.track(JourneysEvents.Metric, { deliveryId: deliveryId, metric: JourneysEvents.Opened, }) return } if (action === 'clicked') { if (actionConfig?.behavior === 'dismiss' && !actionConfig?.name) { return } void analyticsInstance.track(JourneysEvents.Metric, { deliveryId: deliveryId, metric: JourneysEvents.Clicked, actionName: actionConfig?.name, actionValue: actionConfig?.action, }) } } function _error(msg: string) { console.error(`[Customer.io In-App Plugin] ${msg}`) }