This guide takes you from a new account to a complete Appcues installation, with the user data, events, and elements your first campaigns need. You plan what to send, your developer writes the code, and you verify the results together.

A complete installation takes more planning than adding a snippet, and it's what makes targeting, Key Moments, dashboards, and recommendations accurate from day one. Some choices, like the user ID, can't be changed later without splitting your users' history.

Prerequisites

• An Appcues account. If you don't have one, register here.
• A developer with access to your application's codebase.
• About 20 minutes with that developer to agree on the plan.

Step 1: Plan what Appcues needs

Fill in the installation plan in Brief your developer before install before anyone writes code. It walks you through:

• The first three things you want to launch, and how you'll know each one worked
• The user properties, account properties, and events those launches need
• The elements in your product that your content will point at
• The other tools Appcues connects to, and which ID each one matches on
• The Key Moments you'll measure success by: the two or three milestones that show a user is getting value, such as publishing a first project. Each one needs an event or a user property your developer sends.
• Your hosting region, environments, and who owns your Content Security Policy

Guessing at properties and events is the most common reason an installation gets done twice. Appcues can only target and measure what you send it.

Step 2: Hand the plan to your developer

Send your developer the filled-in plan with Install Appcues without rework. That page explains what each decision costs later and which parts depend on someone outside their team.

The code itself is small. These are what usually set the timeline:

• Content Security Policy. If your application has one, your security or infrastructure team has to allow Appcues domains. See Configure Content Security Policies for Appcues.
• Identity verification. If your security review requires it, it adds backend work. See Identity Verification.
• Stable selectors. Your developer adds stable attributes to the elements your content will point at. See Prepare your frontend for element targeting.
• Mobile releases. Mobile users only get Appcues after your next app store release.

Step 3: Install the snippet or SDK

Web

1. Open Settings > Web. Your account ID is at the top right.
2. Give your developer the account ID and Install the Appcues SDK. They can also install through Segment, Google Tag Manager, or Rudderstack.
3. Add the snippet to every page where you want experiences to appear. Appcues only works on pages where the snippet loads.

Mobile

1. Open Settings > Mobile and register each app. See Register your mobile app.
2. Have your developer add the Appcues SDK to your mobile app. See Installing Appcues in mobile applications.

Confirm it worked

• In Settings > Web, your domains appear under Connected domains with the status Installed.
• Open your app and launch the Appcues web debugger or mobile debugger. SDK Loaded shows a green checkmark.

If the debugger shows a red status or doesn't appear, check that the snippet is on the current page, that your Content Security Policy allows Appcues, and that ad blockers are off. See Installation testing and debugging.

Step 4: Identify users

Identifying users tells Appcues who is using your product. Without it, you can't target experiences, personalize content, or measure results.

Call Appcues.identify() on every page load after a user logs in. Pass the user's ID and the properties from your plan.

Appcues.identify("USER_ID", {
  createdAt: 1672531200000,   // Unix timestamp, milliseconds
  role: "admin",
  plan: "growth",
  email: "name@company.com",
  firstName: "Jo"
});

Pick a user ID you'll never change

userId is the only value Appcues requires. Use a stable, unique identifier such as a database ID or UUID, not an email address. When a user ID changes, Appcues treats that person as a new user and their history splits into two profiles that don't merge.

If you plan to connect other tools, use an ID those tools already store, with identical casing.

Send the properties from your plan

Most teams start with createdAt, role, and plan, which cover lifecycle, permission, and plan-tier targeting. Add email if you'll send emails, and firstName or companyName if you'll personalize content. See User properties overview.

Add account properties with group

If your product has team or company accounts, call Appcues.group() after Appcues.identify().

Appcues.group("ACCOUNT_ID", {
  name: "Acme Corp",
  plan: "enterprise",
  employeeCount: 250
});

Always call Appcues.identify() first. A group call made before identify is held until a user is identified, then applied to that user, so calling them out of order can attach the wrong user to the account. See Group properties overview.

Keep your data clean from day one

• Use one naming convention. createdAt and created_at are two separate properties in Appcues. Pick camelCase or snake_case and stick with it.
• Send properties on every page load. Appcues uses the most recent identify call for targeting. If you only send properties at login, a plan upgrade mid-session won't count until the next login.
• Keep the plan current. When someone adds a property or event, they add it to the installation plan first, so the next person checks there before creating a duplicate.

Confirm it worked

Open the Appcues debugger and check that:

• User Identified shows a green checkmark.
• The correct user ID appears.
• Your properties are listed with the values you expect.

If properties are missing, check that Appcues.identify() runs after login, and that property names match exactly. Names are case-sensitive.

Step 5: Track events

Events record what users do, such as Created Project or Invited Teammate. They power event-based targeting, Key Moments, campaign objectives, and dashboards. Without events, Appcues can't tell you whether your campaigns worked.

Call Appcues.track() when a user completes an action from your plan.

Appcues.track("Invited Teammate");

Appcues.track("Created Project", {
  projectType: "onboarding",
  templateUsed: true
});

On web, your team can also create events without code using Click to Track in the Appcues Builder. Keep track() for events that need validation before they count, like a successful payment, and for mobile.

Keep event names clean

• Use one format. Past tense in Title Case works well: Invited Teammate, Created Project.
• Be specific. Clicked Button tells you nothing. Submitted Support Ticket tells you what happened.
• Check before you add. Invited Teammate, invited_teammate, and teammate-invited are three separate events in Appcues. Look in Settings > Events first.

Confirm it worked

Do the action you're tracking in your app.

Open Settings > Events. The event appears after it fires at least once.

If an event doesn't appear, check that Appcues.track() runs after Appcues.identify() and that the event name matches exactly, including capitalization.

Step 6: Define your Key Moments

Key Moments are the milestones Appcues measures your campaigns against. Every campaign objective is built on one, and dashboards and targeting can use them too. Define your first two or three now, while you're checking that their events arrive.

1. Open Settings > Key Moments and click + Create new.
2. Enter a name your team already uses, such as "First project published." The slug Appcues generates from it can't be changed after you save.
3. Under What action counts?, select the event from your plan. To count a one-time milestone instead, skip the event and add conditions on the user.
4. Click Save.

You can also describe the moment to Appcues AI and it creates the Key Moment for you. See Create a Key Moment.

Step 7: Connect integrations

Open Settings > Connections.

Connect the tools from your plan:

• Data in: Segment, Heap, Amplitude, or Mixpanel can add user properties and events from your analytics stack.
• Data out: send Appcues events, such as Flow completed or NPS submitted, to your analytics, CRM, or marketing tools. See the integrations overview.

Confirm data flows both ways. For example, if you connect Segment, check that Segment properties appear in Settings > Properties and that Appcues events appear in Segment.

Verify your full installation

Run through this checklist with the Appcues debugger open:

• SDK Loaded: green checkmark, and your domains show Installed in Settings > Web.
• User Identified: green checkmark, correct user ID, and every property from your plan with the expected value.
• Events tracked: each event from your plan appears in Settings > Events.
• Pages tracked: the debugger shows the current URL updating as you move between pages.
• Key Moments defined: each milestone from your plan is listed in Settings > Key Moments.
• Elements ready: the elements in your plan have the stable attributes your developer added.

When everything passes, your installation is complete. Next, create a campaign.

If something isn't working

Debugger doesn't appear. The snippet may not be on the current page, or an ad blocker or privacy extension may be blocking it. Try an incognito window with extensions off.

User not identified. Check that Appcues.identify() runs after the user logs in, not on the login page. The user ID must be a non-empty string.

Properties missing or wrong. Compare what your code sends with what the debugger shows, keeping in mind that names are case-sensitive. Confirm Appcues.identify() runs on every page load.

Events not appearing. Call Appcues.track() after Appcues.identify(). Events tracked before identify are held and attributed to the next identified user, so they can land on the wrong profile.

Domain shows Not installed. The snippet isn't loading on that domain yet. Check that your developer deployed it there.

Experiences not showing after setup. This guide covers installation only. See Installation testing and debugging.

Contact support

If your installation still isn't working, collect the following and contact support@appcues.com:

• Your Appcues account ID, from Settings > Web
• A screenshot of the Appcues debugger showing the issue
• The URL of the page where the problem happens
• Your installation method: direct snippet, Segment, Google Tag Manager, or mobile SDK
• Browser and OS version for web, or device and OS version for mobile