Registry / communication / customerio-gist-web

customerio-gist-web

library3.21.13jsnpmunverified

The Customer.io Gist Web SDK (current stable version 3.21.13) provides a robust solution for embedding rich, interactive in-app messages and multi-step flows directly into web applications. Acquired by Customer.io in July 2022, this SDK allows developers to leverage Customer.io's no-code message builder to design and deliver modals, banners, embedded content, and a persistent message inbox. The package maintains an active release cadence with patch, minor, and major versions, indicating regular updates and enhancements. Key differentiators include seamless integration with Customer.io campaigns, advanced route targeting, comprehensive user identification, event tracking for message lifecycle, and the ability to customize messages using user attributes. It enables use cases like user onboarding, feature announcements, and in-app support, simplifying complex in-app messaging logic.

communication aws

npm install customerio-gist-web

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CUSTOMERIO-GIST-WE

customerio-gist-web

communicationjavascriptv3.21.13

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Gist

✓ import Gist from 'customerio-gist-web';

✗ const Gist = require('customerio-gist-web');

The primary SDK instance is exported as a default. Use ES module import syntax for modern JavaScript and TypeScript environments. CommonJS `require` is not officially supported for this module structure.

GistConfig

✓ import type { GistConfig } from 'customerio-gist-web';

✗ import { GistConfig } from 'customerio-gist-web';

To import only the TypeScript interface for configuration options, use `import type`. Importing it as a regular named export is incorrect as it's a type definition.

GistEventName

✓ import type { GistEventName } from 'customerio-gist-web';

✗ import { GistEventName } from 'customerio-gist-web';

Similar to GistConfig, `GistEventName` is a TypeScript type representing event names for `Gist.events.on`. Use `import type` to import only the type definition.

This quickstart demonstrates how to install, initialize, identify a user, set the current route, and subscribe to message events using the Customer.io Gist Web SDK.

import Gist from 'customerio-gist-web'; interface MyConfig extends GistConfig { siteId: string; dataCenter: 'us' | 'eu'; } async function initializeGist() { const config: MyConfig = { siteId: process.env.GIST_SITE_ID ?? 'YOUR_CUSTOMERIO_SITE_ID', dataCenter: 'us', logging: true, // Enable logging for development useAnonymousSession: true, // Automatically create guest sessions }; try { await Gist.setup(config); console.log('Customer.io Gist SDK initialized successfully.'); // Identify a user (replace with actual user data) Gist.identify('user-123', { email: 'user@example.com', name: 'Test User' }); // Set current route for message targeting (important for SPAs) await Gist.setCurrentRoute(window.location.pathname); // Listen for messages shown Gist.events.on('messageShown', (message) => { console.log('Message shown:', message.messageId); }); } catch (error) { console.error('Failed to initialize Customer.io Gist SDK:', error); } } initializeGist();

Debug

Known issues

breakingMajor versions of `customerio-gist-web` (e.g., v2 to v3) may introduce breaking API changes. Always consult the official release notes and migration guides before upgrading to a new major version to ensure compatibility and avoid unexpected behavior.

fix

Review the official documentation and migration guides for your target major version. Test upgrades in a staging environment.

affects: >=1.0

gotchaThe `Gist.setup()` method is asynchronous and returns a Promise. It is crucial to `await` its completion or use `.then()` before calling any other SDK methods (like `identify`, `setCurrentRoute`, or `showMessage`) to ensure the SDK is fully initialized. Calling methods prematurely can lead to errors or silent failures.

fix

Ensure `await Gist.setup(...)` is completed before subsequent SDK calls. Example: `await Gist.setup(...); Gist.identify(...);`

affects: >=1.0

gotchaThe `siteId` and `dataCenter` properties are required for `Gist.setup()`. Failing to provide these, or providing incorrect values, will prevent the SDK from connecting to Customer.io and delivering messages. These values should typically be retrieved securely (e.g., from environment variables).

fix

Always pass valid `siteId` and `dataCenter` (e.g., 'us' or 'eu') in the `GistConfig` object during initialization. Check your Customer.io workspace settings for the correct `siteId`. Example: `{ siteId: process.env.GIST_SITE_ID, dataCenter: 'us' }`.

affects: >=1.0

Errors

Common errors & fixes

TypeError: Gist.setup is not a function

Attempting to call `setup` on `Gist` when it has not been correctly imported as a default export or when using CommonJS `require`.

fix

Ensure you are using `import Gist from 'customerio-gist-web';` for ESM environments. If in a CommonJS context, consider a bundler that handles ESM or ensure proper transpilation.

Error: Gist SDK not initialized. Call Gist.setup() first.

An SDK method (e.g., `Gist.identify()`, `Gist.showMessage()`) was called before `Gist.setup()` had successfully completed.

fix

Wrap calls to other SDK methods within an `async` function and `await Gist.setup()`, or chain them with `.then()` after `Gist.setup()`.

Property 'siteId' is missing in type 'GistConfig'.

When using TypeScript, the `siteId` property was omitted from the configuration object passed to `Gist.setup()`, which is a required field.

fix

Provide the `siteId` string in the configuration object. Example: `Gist.setup({ siteId: 'your-site-id', dataCenter: 'us' });`

Upgrade

Version history

3.21.13latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

29 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/customerio/gist-web ↗

packagehttps://www.npmjs.com/package/customerio-gist-web ↗

homepagehttps://customer.io ↗