Install the Appcues SDK
Add the Appcues SDK to your web application so you can show experiences to your users.
Table of Contents
Web installation steps
You're on step 1 of 3.
| Step | Article |
|---|---|
| 1. Install the SDK | You are here |
| 2. Identify users and groups | Identify users and groups |
| 3. Track events | Track events in your web app |
Before you start, decide which properties and events to send: Choose which events and properties to send.
Prerequisites
- Access to your team's Appcues account (you'll need your Appcues Account ID)
- Access to your application's codebase
- A completed installation plan (recommended)
This guide covers direct installation on web. For other methods, see: Segment | Google Tag Manager | Rudderstack | Freshpaint | Mobile SDK
Choose your installation method
You can install the SDK via a script snippet or an NPM package. The script snippet is recommended for most teams.
| Method | Best for | Updates | TypeScript |
|---|---|---|---|
| Script snippet | Most teams | Automatic — always runs the latest SDK | Manual declaration required |
| NPM package | Teams that need version control | Manual — you update the package version | Full built-in support |
Install via script snippet (recommended)
Add the following code inside the <head> tag of your page(s). Replace YOUR_APPCUES_ID with the Account ID from your Studio Settings page.
<script type="text/javascript">
window.AppcuesSettings = { enableURLDetection: true };
</script>
<script src="//fast.appcues.com/YOUR_APPCUES_ID.js"></script>A copyable version of this snippet is also available in the in-Studio installation guide.
Add the script on every page where you want Appcues to run. You can do this by placing it in your index.html or another root file. If you want more control, add it only to specific pages.
The enableURLDetection setting automatically detects page changes across your application. Appcues uses this to determine the current URL for page targeting and cross-page experiences.
TypeScript
If you're using TypeScript and see a 'does not exist' error related to Appcues, declare it as a global variable:
declare global {
interface Window { Appcues: any; }
}
declare global {
interface Window { AppcuesSettings: any; }
}Single-page applications
If you're using React, Next.js, Vue, Angular, or another SPA framework, enableURLDetection handles page changes automatically. If you see Flows restarting or disappearing during navigation, see the SPA guide for troubleshooting and manual page tracking options.
Load the script asynchronously
By default, the Appcues script loads synchronously — it blocks other scripts until it finishes. If page load performance is a concern, you can load it asynchronously so it downloads in parallel with the rest of your page.
Add this setup code before the Appcues script. It creates a queue that buffers any Appcues method calls until the SDK finishes loading:
<script>
(function() {
if (!window.AppcuesReady) {
window.AppcuesReady = function(callback) {
callback && window.AppcuesReady.q.push(callback);
if (window.Appcues) {
while (window.AppcuesReady.q.length) {
cb = window.AppcuesReady.q.shift();
if (typeof cb === 'function') cb();
}
}
};
window.AppcuesReady.q = [];
}
})();
</script>
Then load the Appcues script with async and call AppcuesReady() on load:
<script src="//fast.appcues.com/YOUR_APPCUES_ID.js" async onload="AppcuesReady()"></script>
To call Appcues methods safely before the SDK has loaded, wrap them in AppcuesReady():
AppcuesReady(function() {
Appcues.identify("USER_ID", { email: "user@example.com" });
});
This ensures identify() runs as soon as the SDK is ready, regardless of load order. You can call AppcuesReady() multiple times — all callbacks are queued and executed in order.
If you use the NPM package instead, async loading is handled automatically by
await Appcues.setup()and you don't need this pattern.
Install via NPM
Install the package:
npm install @appcues/web-sdk --saveThe Appcues SDK is also available as a public NPM package at https://www.npmjs.com/package/@appcues/web-sdk
Initialize the SDK when your application launches. Replace APPCUES_ACCOUNT_ID with the Account ID from Studio Settings:
import Appcues from '@appcues/web-sdk'
await Appcues.setup('APPCUES_ACCOUNT_ID')Optional settings
Appcues.setup accepts an optional settings object as the second argument:
| Setting | Type | When to use |
|---|---|---|
apiHostName |
string | When proxying the Appcues API through a custom domain. See self-hosting the bootstrap script. |
bundleDomain |
string | Set to https://fast.eu.appcues.com for EU accounts that are not using a custom proxy domain. |
Example:
import Appcues from '@appcues/web-sdk'
await Appcues.setup('APPCUES_ACCOUNT_ID', {
apiHostName: 'you.customdomain.com'
})After setup completes, you can import the SDK into any module and use its public methods immediately.
How setup handles early method calls
Appcues.setup runs asynchronously. If you call any Appcues method before setup finishes, the SDK buffers those calls in memory and replays them in order once setup completes. No data is lost.
TypeScript support (NPM)
The NPM package includes full type definitions for all SDK methods and properties. You get autocompletion, type checking, and error detection in your editor without any additional setup.
Confirm it worked
Open the Appcues Debugger in your application and check these indicators:
- Installed and Connected to Appcues are green. The Debugger will not open at all if the SDK is not detected.
- Tracking Pages is green. Navigate between pages with the Debugger open — the indicator may flash red briefly during page loads, but it should return to green without a manual refresh.
If both checks pass, the SDK is installed. Next step: identify users and groups.
If the SDK isn't loading
- The Debugger won't open: Confirm the script tag is in the page source (View Source or Elements tab in DevTools). Check that the Account ID matches your Studio Settings.
- Console shows a Content Security Policy error: Your application's CSP is blocking Appcues. Add the required Appcues domains to your allow list. See Configure Content Security Policies.
- SDK loads but experiences don't appear: This is usually an identify issue, not an SDK issue. Make sure you've completed the next step: identify users and groups.
- Ad blocker interference: Some ad blockers can prevent the Appcues script from loading. See Ad blockers & Appcues.
Still stuck?
Collect the following and email support@appcues.com:
- Your Appcues Account ID
- The URL where the issue occurs
- A screenshot of your browser's console (right-click > Inspect > Console tab)
- A screenshot of the Appcues Debugger (if it opens)
Related
- Identify users and groups — Next step after installing the SDK
- Track events in your web app — Final installation step
- Host the SDK under your own domain
- Supported technologies and frameworks