{"id":13033,"library":"customerio-gist-web","title":"Customer.io Gist Web SDK","description":"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.","status":"active","version":"3.21.13","language":"javascript","source_language":"en","source_url":"git://github.com/customerio/gist-web","tags":["javascript","gist","in-app","messages","product","messaging","in-product","gist.build","customerio","typescript"],"install":[{"cmd":"npm install customerio-gist-web","lang":"bash","label":"npm"},{"cmd":"yarn add customerio-gist-web","lang":"bash","label":"yarn"},{"cmd":"pnpm add customerio-gist-web","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const Gist = require('customerio-gist-web');","symbol":"Gist","correct":"import Gist from 'customerio-gist-web';"},{"note":"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.","wrong":"import { GistConfig } from 'customerio-gist-web';","symbol":"GistConfig","correct":"import type { GistConfig } from 'customerio-gist-web';"},{"note":"Similar to GistConfig, `GistEventName` is a TypeScript type representing event names for `Gist.events.on`. Use `import type` to import only the type definition.","wrong":"import { GistEventName } from 'customerio-gist-web';","symbol":"GistEventName","correct":"import type { GistEventName } from 'customerio-gist-web';"}],"quickstart":{"code":"import Gist from 'customerio-gist-web';\n\ninterface MyConfig extends GistConfig {\n  siteId: string;\n  dataCenter: 'us' | 'eu';\n}\n\nasync function initializeGist() {\n  const config: MyConfig = {\n    siteId: process.env.GIST_SITE_ID ?? 'YOUR_CUSTOMERIO_SITE_ID',\n    dataCenter: 'us',\n    logging: true, // Enable logging for development\n    useAnonymousSession: true, // Automatically create guest sessions\n  };\n\n  try {\n    await Gist.setup(config);\n    console.log('Customer.io Gist SDK initialized successfully.');\n\n    // Identify a user (replace with actual user data)\n    Gist.identify('user-123', { email: 'user@example.com', name: 'Test User' });\n\n    // Set current route for message targeting (important for SPAs)\n    await Gist.setCurrentRoute(window.location.pathname);\n\n    // Listen for messages shown\n    Gist.events.on('messageShown', (message) => {\n      console.log('Message shown:', message.messageId);\n    });\n  } catch (error) {\n    console.error('Failed to initialize Customer.io Gist SDK:', error);\n  }\n}\n\ninitializeGist();","lang":"typescript","description":"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."},"warnings":[{"fix":"Review the official documentation and migration guides for your target major version. Test upgrades in a staging environment.","message":"Major 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.","severity":"breaking","affected_versions":">=1.0"},{"fix":"Ensure `await Gist.setup(...)` is completed before subsequent SDK calls. Example: `await Gist.setup(...); Gist.identify(...);`","message":"The `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.","severity":"gotcha","affected_versions":">=1.0"},{"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' }`.","message":"The `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).","severity":"gotcha","affected_versions":">=1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Attempting to call `setup` on `Gist` when it has not been correctly imported as a default export or when using CommonJS `require`.","error":"TypeError: Gist.setup is not a function"},{"fix":"Wrap calls to other SDK methods within an `async` function and `await Gist.setup()`, or chain them with `.then()` after `Gist.setup()`.","cause":"An SDK method (e.g., `Gist.identify()`, `Gist.showMessage()`) was called before `Gist.setup()` had successfully completed.","error":"Error: Gist SDK not initialized. Call Gist.setup() first."},{"fix":"Provide the `siteId` string in the configuration object. Example: `Gist.setup({ siteId: 'your-site-id', dataCenter: 'us' });`","cause":"When using TypeScript, the `siteId` property was omitted from the configuration object passed to `Gist.setup()`, which is a required field.","error":"Property 'siteId' is missing in type 'GistConfig'."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}