Set up Appcues
Actionable guide to help you get started with Appcues
Table of Contents
This guide walks you through every step from new account to a fully working Appcues installation with clean data flowing. Work through it with your developer — you handle the planning, they handle the code, and you both verify the results together.
For a full installation guide for developers see Installing in Web and Installing in Mobile.
Prerequisites
- An Appcues account. If you don't have one, register here.
- Access to your application's codebase (or a developer who does).
- A list of the user properties and events you want to track. If you haven't planned these yet, the installation plan template helps you organize them before writing any code.
Install the Appcues snippet or SDK
Appcues connects to your product through a lightweight JavaScript snippet (web) or a native SDK (mobile). Choose the path that matches your platform.
Web
- Open Settings > Installation in Appcues Studio. Copy your account-specific snippet.
- Add the snippet to every page of your web app, ideally in the
<head>tag so it loads early. Your developer can also install via Segment, Google Tag Manager, or Rudderstack. See Installation guide for developers for full details. - Confirm the snippet is present on every page where you want experiences to appear — Appcues only works on pages where the snippet is loaded.
Mobile
- Register your mobile app in Settings > Installation in Appcues Studio. See Register your mobile app.
- Add the Appcues SDK to your iOS or Android project. Follow the setup steps in Install the mobile SDK.
Confirm it worked
Open your app in a browser (web) or on a test device (mobile) and launch the Appcues web debugger or mobile debugger. If the snippet or SDK is loaded correctly, the debugger shows a green checkmark next to SDK Loaded.
If the debugger shows a red status or doesn't appear, check that the snippet is on the current page, that there are no Content Security Policy (CSP) blocks, and that ad blockers are disabled. See Installation testing and debugging.
Identify users
User identification tells Appcues who is using your product. Without it, you can't target experiences, personalize content, or measure results accurately.
Call Appcues.identify() on every page load after a user logs in. Pass the user's unique ID and any properties you want to use for targeting or personalization.
Appcues.identify("USER_ID", {
createdAt: 1672531200000, // Unix timestamp, milliseconds
role: "admin",
plan: "growth",
email: "name@company.com",
firstName: "Jo"
});
Choose the right properties
Start with properties that directly support targeting. You can always add more later, but getting these right from the start prevents messy data that's hard to clean up.
Required:
-
userId— the only property Appcues absolutely needs. Use a stable, unique identifier (a database ID, not an email address). If this changes or is inconsistent, you create duplicate user profiles.
Recommended:
-
createdAt— when the user signed up. Enables lifecycle-based targeting like "show this to users in their first 7 days." -
email— needed if you plan to send emails through Workflows. -
role— how your product differentiates permissions (admin, member, viewer). Lets you target experiences by role. -
plan— trial, free, paid, enterprise. Lets you target by plan tier.
Useful additions:
-
firstName— for personalizing experience copy with dynamic fields. -
companyName— for account-level personalization. -
language— for multi-language applications.
For the full recommended list and reasoning, see User properties overview.
Add account-level properties with group
If your app has team or company accounts, call Appcues.group() after Appcues.identify() to associate users with their account.
Appcues.group("ACCOUNT_ID", {
name: "Acme Corp",
plan: "enterprise",
employeeCount: 250
});
Always call
Appcues.identify()beforeAppcues.group(). Group calls without a prior identify call are ignored.
Account properties let you target by company attributes — for example, showing an enterprise onboarding Flow only to accounts on the enterprise plan. See Group properties overview.
Keep your data clean from day one
Inconsistent property data is the most common source of targeting problems and stale segments. These habits prevent issues before they start:
-
Use consistent naming. Pick a convention (camelCase or snake_case) and stick with it.
createdAtandcreated_atare treated as two separate properties in Appcues — if your team sends both, you end up with duplicate data and unreliable targeting. - Use stable user IDs. Pass a database ID or UUID, not an email. If a user changes their email, a new profile is created and their history splits in two.
- Send properties on every page load. Appcues uses the most recent identify call to evaluate targeting. If you only send properties on login, updates made during a session (like a plan upgrade) won't take effect until the next login.
- Document what you send. Use the installation plan template as a living reference. When a new teammate joins or a developer instruments a new property, everyone should check this document first.
- Audit periodically. Review the properties listed on the Events and Properties page in Studio. Hide any that are stale or unused by toggling Show in Menus off. This keeps your targeting menus clean and prevents teammates from building on outdated data.
Confirm it worked
Open the Appcues debugger and check:
- User Identified shows a green checkmark.
- The correct
userIdappears. - Your properties (role, plan, createdAt, etc.) are listed with the expected values.
If properties are missing, check that Appcues.identify() is called after the user logs in (not before), and that property names match what your code sends. Property names are case-sensitive.
Track events
Events capture the actions your users take — clicking a button, completing a task, reaching a milestone. They power three things in Appcues: event-based targeting (show a Flow when a user has not completed onboarding), Goals (measure whether an experience drives the right behavior), and analytics (understand what users do after seeing your content).
Your Appcues implementation is incomplete without events. Without them, you can't measure impact or target based on user behavior.
Send events with track
Call Appcues.track() when a user completes a meaningful action.
Appcues.track("Invited Teammate");
Appcues.track("Created Project", {
projectType: "onboarding",
templateUsed: true
});
You can also track events without code using Click-to-Track, which lets you define events by clicking or hovering on elements in the Appcues Builder.
Choose the right events
Focus on events tied to outcomes you want to drive or measure. Don't track everything — track what matters.
Start with these categories:
-
Activation milestones — the actions that correlate with long-term retention. Examples:
Created Project,Invited Teammate,Published First Flow,Connected Integration. -
Feature usage — actions tied to features you plan to promote or measure. Examples:
Used Search,Exported Report,Enabled Notifications. -
Lifecycle moments — transitions between stages. Examples:
Completed Onboarding,Upgraded Plan,Renewed Subscription.
Keep event names clean
The same naming discipline applies to events:
-
Use a consistent format. Past tense, Title Case works well:
Invited Teammate,Created Project,Completed Onboarding. Pick one style and document it. -
Be specific.
Clicked Buttontells you nothing.Submitted Support Tickettells you everything. -
Avoid duplicates. Before instrumenting a new event, check the Events and Properties page to see if a similar event already exists.
Invited Teammate,invited_teammate, andteammate-invitedare three separate events in Appcues. - Document every event. Add each event to your installation plan with a description of what triggers it and who owns it. This prevents a teammate from creating a near-duplicate six months later.
Confirm it worked
- Trigger the event in your app (perform the action you're tracking).
- Check the Events page in Studio. New events appear here after they've been fired at least once.
If an event doesn't appear, verify that Appcues.track() is called after Appcues.identify(), and that the event name string matches exactly (including capitalization).
Connect integrations
Integrations let you bring data into Appcues from other tools and send Appcues engagement data back out for unified reporting.
- Open Settings > Integrations in Appcues Studio.
- Connect tools based on your needs:
- Data in: Segment, Heap, Amplitude, or Mixpanel can enrich Appcues with additional user properties and events from your analytics stack.
- Data out: Send Appcues events (Flow started, Flow completed, NPS submitted, etc.) to your analytics, CRM, or marketing tools for reporting. See the full integrations overview.
- Verify the connection by checking that data flows in both directions. For example, if you connect Segment, confirm that user properties from Segment appear in Appcues and that Appcues events appear in your Segment instance.
Verify your full installation
Before you start building experiences, run through this final checklist with the Appcues debugger open:
- SDK Loaded — green checkmark.
- User Identified — green checkmark, correct user ID, properties listed with expected values.
- Events tracked — trigger a test event and confirm it appears.
- Pages tracked — navigate between pages and confirm the debugger shows the current URL updating.
When all four checks pass, your installation is complete and you're ready to build and publish your first experience.
If something isn't working
Debugger doesn't appear: The Appcues snippet may not be on the current page, or a browser extension (ad blocker, privacy tool) may be blocking it. Try an incognito window with extensions disabled.
User not identified: Check that Appcues.identify() runs after the user logs in, not on the login page itself. The user ID must be a non-empty string.
Properties missing or wrong: Property names are case-sensitive. Compare what your code sends against what the debugger shows. Also confirm you're calling Appcues.identify() on every page load, not just on login.
Events not appearing: Appcues.track() must be called after Appcues.identify(). If you call track before identify, the event is dropped.
Experiences not showing after setup: This article covers installation only. Targeting, audience, and display issues are covered in Test and troubleshoot Flows and Installation testing and debugging.
Contact support
If your installation still isn't working after checking the above, collect the following and contact support@appcues.com:
- Your Appcues account ID (found in Settings > Installation)
- A screenshot of the Appcues debugger showing the issue
- The URL of the page where the problem occurs
- Your installation method (direct snippet, Segment, GTM, mobile SDK)
- Browser and OS version (for web) or device and OS version (for mobile)