Userflow.js Reference
Userflow.js should be installed in your web app or website. It's responsible for identifying your users with Userflow and showing flows, checklists and more when appropriate.
Follow us on Twitter for Userflow.js announcements.
Quick links
Quick access to methods that you'll probably need:
Method | Purpose |
---|---|
userflow.init() | Initialize Userflow.js with your Token |
userflow.identify() | Identify a user |
userflow.group() | Associate current user with a group/company |
userflow.track() | Track an event |
Installation
Install userflow.js via npm
Install Userflow.js via npm:
npm install userflow.js
Or, install via Yarn
yarn add userflow.js
We recommend using the userflow.js npm package as it offers the best developer experience:
See also Userflow.js installation for an alternative installation method via a plain <script>
tag.
Quick start
import userflow from 'userflow.js'
userflow.init('<USERFLOW_TOKEN>')
userflow.identify('<USER_ID>', {
name: '<NAME>',
email: '<EMAIL>',
signed_up_at: '2019-06-14T16:25:49Z'
})
Put this code in your app where it has access to the current user's information.
Replace all placeholders (e.g. <USERFLOW_TOKEN>
and <USER_ID>
) with real values.
Grab your Userflow.js Token under Settings -> Environments. Note that if you have multiple environments (e.g. Production and Staging) that each environment has a unique token.
The userflow object
Import the
userflow
object:
import userflow from 'userflow.js'
The userflow.js
npm package is a thin wrapper around the real Userflow.js, which is loaded from our CDN. This way, you can interact with the imported userflow
object immediately. On the first method call, the real Userflow.js will automatically be loaded (asynchronously) and injected into the current page. Method calls are automatically queued by the userflow
object.
The real Userflow.js script is a small script (currently <16 KB gzipped) that contains the bare minimum to identify users and check if they have any active flows. Additional UI code and styles will only load if the user has any active flows. This is to have as small an impact on your page's load time as possible. For legacy browsers (that don't support ES2020 features), a legacy script is loaded instead.
If you've installed Userflow.js via a <script>
tag, you can access the object via window.userflow
. Just be careful that it may not be loaded yet (which is why the userflow.js npm package is recommended!).
Attributes
Example of using all the possible data types (these will all be inferred as expected):
userflow.identify('123456', {
string: 'Just a string',
always_true: true,
always_false: false,
integer_number: 42,
decimal_number: 1234.56,
used_datetime_at: '2019-12-03T12:34:56.123Z'
})
Remove an attribute:
userflow.updateUser({
phone_number: null
})
Explicitly setting
data_type
:
userflow.identify('123456', {
// This will be consumed as a string, even though its value
// is a number here
phone: {set: 12345678, data_type: 'string'}
})
Using
set_once
:
userflow.identify('123456', {
coupon_code: {set_once: generate_onetime_coupon_code()}
})
Using
add
andsubtract
:
userflow.updateUser({
widget_count: {add: 1},
total_revenue: {add: 1234.56},
days_left: {subtract: 1}
})
List operations:
userflow.updateUser({
foods: {append: 'apple'}, // Append single value
tags: {append: ['cool', 'smart']}, // Append multiple values
roles: {prepend: ['admin']},
flags: {remove: ['invoicing']}
})
Several methods accept an attributes
dictionary, which represents arbitrary information about objects such as users and events. You can use this to, for example, store a user's name or their date of sign-up, or to decorate events with e.g. which billing plan was selected. These attributes can then be used within Userflow to segment users or personalize their flows.
When updating objects with attributes, the values in the attributes
dictionary can be literal values (string, boolean, number, or list of strings), which just sets the attributes to the given values.
If an attribute value is null
, the attribute will be removed from the object.
You can also specify an operation object instead of a literal value. This operation object can contain the following keys (note that exactly one of set
, set_once
, add
, subtract
, append
, prepend
or remove
must be set):
Key | Description |
---|---|
set |
String/number/boolean - Sets the attribute to this value. This is the same as using literal values, except this way you can explicitly set the data_type , too. |
set_once |
String/number/boolean - Sets the attribute to this value, but only if the user doesn't already have a value for this attribute. |
add |
Number - Adds this value to the attribute's current value. If the user does not have the attribute yet, the given number will be added to 0 . Only works on number attributes. |
subtract |
Number - Same as add , but subtracts the given number instead. To subtract, you either supply a negative number to add , or a positive number to subtract . |
append |
String/list of strings - Adds one or more values to the end of a list type attribute. If the user's attribute value was not set before, it will be initialized to an empty list before the values are appended. Any values already present in the user's attribute value will be ignored (no duplicates are inserted). |
prepend |
String/list of strings - Like append , but inserts the values at the beginning of the list. |
remove |
String/list of strings - Removes one or more values from a list type attribute. If the user's attribute value was not set before, it will be set to an empty list. |
data_type |
String - Explicitly tells Userflow what data type to use. See Attribute data types for possible values. You usually don't have to set this, as Userflow will infer the right data type depending on the values you supply. |
Attribute names (they keys of attributes
objects) must consist only of a-z, A-Z, 0-9, underscores, dashes and spaces. We recommend using snake_case
everywhere though. Attributes' human-friendly display names (e.g. "Signed Up" for signed_up_at
) can also be configured in the Userflow UI.
Attribute data types
We support the following attribute data types:
Name | Description |
---|---|
string |
Represents a string. |
number |
Represents a number (supports both integers and floating point numbers). |
boolean |
Represents either true or false . |
datetime |
Represents a point in time, always stored as ISO 8601 in UTC. |
list |
Represents a list of strings. |
Setup
init()
userflow.init('bmztslyu5zgujmcvna34mggj44')
Initializes Userflow.js to target your company. Must be called once (per page load) before you make any other call.
Parameters
Parameter | Description |
---|---|
token |
String, required - Your Userflow.js Token, which you can find under Settings -> Environments. Note that if you have multiple environments (e.g. Production and Staging) that each environment has a unique token. |
Users
Users are the people using your application. Userflow keeps track of your users, so we can determine which flows to show them, and remember which flows they've already seen.
identify()
Example of sending the recommended attributes:
userflow.identify('123456', {
name: 'Jane Smith',
email: 'jane@example.com',
signed_up_at: '2019-06-14T16:25:49Z'
})
Minimal example of sending only userId:
userflow.identify('123456')
Example of using identify verification
userflow.identify(
'123456',
{
name: 'Jane Smith',
email: 'jane@example.com',
signed_up_at: '2019-06-14T16:25:49Z'
},
{
// This value should be computed by your backend.
// Do NOT expose the identity verification in your front-end.
signature: '...'
}
)
Identifies the current user with Userflow. You should call this once on any page load where a user is signed in.
If attributes
is set, they will be merged into the user's existing attributes in Userflow. Any attributes you leave out will be left as-is in Userflow.
It's up to you which attributes you want to send to Userflow. The only required argument is userId
. Make sure not to send any sensitive data such as passwords. We recommend sending the name
and email
attributes so you can easily tell users apart in Userflow without relying on IDs only, and signed_up_at
, which is often used in flow start conditions.
If the user has any active flows, they will be displayed. If the user matches any flows' start conditions, they may be started.
Parameters
Parameter | Description |
---|---|
userId |
String, required - The user's ID in your database. |
attributes |
Object, optional - Attributes to update for the user. See Attributes. These attributes can be used in flow content and conditions to personalize the user experience. |
options |
Object, optional |
options.signature |
String, optional - When identity verification is enforced in your environment, you must calculate a signature based on the user ID and include it here. |
Returns
A Promise
that resolves once the identify call succeeds.
identifyAnonymous()
Example of identifying an anonymous user and tagging them with a custom
website_lead
attribute, so they can be targeted by flows:
userflow.identifyAnonymous({
website_lead: true
})
Same as userflow.identify(), except Userflow.js will automatically assign the current user a unique ID. This ID will be stored in the user's localStorage
, and will be reused on reloads.
You should only use this for anonymous users, who are not signed into your app (unauthenticated users). If they are signed in, please use userflow.identify() with their real user ID.
Parameters
Parameter | Description |
---|---|
attributes |
Object, optional - Attributes to update for the user. See Attributes. These attributes can be used in flow content and conditions to personalize the user experience. |
Returns
A Promise
that resolves once the identify call succeeds.
isIdentified()
userflow.isIdentified() // true or false
Check if a user has been identified.
Returns
true
if userflow.identify
or userflow.identifyAnonymous
has been called. false
otherwise.
updateUser()
Example of updating a user's favorite color:
userflow.updateUser({
favorite_color: 'red'
})
Updates attributes for a user that has already been identified with userflow.identify
since the last page load.
Parameters
Parameter | Description |
---|---|
attributes |
Object, optional - Attributes to update for the user. See Attributes. |
Returns
A Promise
that resolves once the update call succeeds.
reset()
userflow.reset()
Makes Userflow forget about the current user and immediately hides any active flows.
Call this when users sign out of your app.
Groups/companies
Groups are used to group multiple users together. In your business, groups may correspond to e.g. companies, teams or departments.
Like users, groups can have attributes. Events can also be associated with groups.
With groups, you can orchestrate the flows a user sees:
- ...based on behavior of other users in a group. Example: Show a flow if no one in a group has created a "widget" yet.
- ...based on multiple groups that the user is a member of. Example: Show a flow if the group the user is currently working on matches some condition.
Note that the Groups feature is only available in certain plans. Check your Billing page or reach out to us to ask.
group()
Example setting the current group/company for a user:
userflow.group('987654', {
name: 'Acme Inc.',
plan: 'Premium',
// Use this to indicate when the group/company was first created in your app
signed_up_at: '2019-06-14T16:25:49Z'
})
Minimal example of sending only
groupId
:
userflow.group('987654')
Example including membership attributes:
userflow.group(
'987654',
// These are the group's attributes
{
name: 'Acme Inc.',
plan: 'Premium'
},
{
// These are the membership's attributes
membership: {
role: 'owner'
}
}
)
Example of using identify verification:
userflow.group(
'987654',
{
name: 'Acme Inc.',
plan: 'Premium'
},
{
membership: {
role: 'owner'
},
// This value should be computed by your backend.
// Do NOT expose the identity verification in your front-end.
signature: '...'
}
)
Associates the currently identified user with a group/company, and optionally updates the group's attributes. You should call this once on any page where the user is working on a specific group. If the user navigates to a different group, simply call userflow.group(newGroupId)
again, and Userflow will switch to using that group instead.
If attributes
is set, they will be merged into the group's existing attributes in Userflow. Any attributes you leave out will be left as-is in Userflow.
Parameters
Parameter | Description |
---|---|
groupId |
String, required - The group/company's ID in your database. |
attributes |
Object, optional - Attributes to update for the group. These attributes can be used in flow content and conditions to personalize the user experience. |
options |
Object, optional |
options.membership |
Object, optional - Attributes to update for the user's membership of the group. Some attributes neither belong on users, nor on groups. One example is a user's "role". A user can have different roles in different groups. A group's members can have different roles. Attributes like "role" are membership attributes. They can be used in the Userflow UI just like group attributes. |
options.signature |
String, optional - When identity verification is enforced in your environment, you must calculate a signature based on the group ID and include it here. |
Returns
A Promise
that resolves once the group call succeeds.
updateGroup()
Example of updating a group's plan:
userflow.updateGroup({
plan: 'Pro'
})
Updates attributes for a group that has already been registered with userflow.group
since the last page load.
Parameters
Parameter | Description |
---|---|
attributes |
Object, optional - Attributes to update for the group. See Attributes. |
Returns
A Promise
that resolves once the update call succeeds.
Events
You can track events for users and groups for analytics purposes or to segment and personalize your flows.
Events tracked via Userflow.js is always associated with the current user. They can optionally be associated with groups, too.
track()
Minimal example of tracking an event when a user activates their subscription:
userflow.track('subscription_activated')
Example with attributes:
userflow.track('subscription_activated', {
plan_name: 'plus',
plan_price: 1234.56
})
Track an even without associating it with the current group:
userflow.track(
'email_changed',
// No attributes
{},
// Options
{
userOnly: true
}
)
Tracks an event related to the currently identified user.
userflow.identify
must have been called before calling track
.
Both event names and attribute names must consist only of a-z, A-Z, 0-9, underscores, dashes and spaces. We recommend using snake_case
everywhere though. Events and attributes' human-friendly display names (e.g. "Subscription Activated" for subscription_activated
) can also be configured in the Userflow UI.
We recommend using event names consisting of a noun and a past-tense verb. Check out this great event naming guide by Segment.
Parameters
Parameter | Description |
---|---|
eventName |
String, required - Name of the event. Examples: subscription_activated , project_created , coworker_invited . See note about event naming below. |
attributes |
Object, optional - Attributes for the event. See Attributes. |
options |
Object, optional - Adjust how the event should be tracked. |
options.userOnly |
Boolean, optional - By default, when userflow.group() has been called, events are associated with both the user and the group. Set userOnly to true to not associate the event with the group. This is useful when the user performs an event that's not group-related, such as changing their own email address. |
Returns
A Promise
that resolves once the track call succeeds.
Flows and content
Content refers to the stuff you build in Userflow, such as flows and checklists. You can manipulate what the current user sees programmatically via Userflow.js.
start()
Start a flow and show it immediately:
userflow.start('89eff72a-d0ae-4be6-b241-1ab04e3da7cc')
Start flow, but only if the user hasn't seen it before:
userflow.start('89eff72a-d0ae-4be6-b241-1ab04e3da7cc', {once: true})
Starts a Userflow content item (flow, checklist etc.) for the currently signed-in user. The content will display immediately.
Use this to programmatically start content when something happens in your app. You could, for example, implement a button called "Show onboarding tutorial again", which users can click after signing up to go through your tutorial again.
Parameters
Parameter | Description |
---|---|
contentId |
String, required - ID of the content to start. You can find the content ID in Userflow on the "Link/Embed" tab. It's also the ID you see in the URL: /app/{company}/content/{contentId} |
options |
Object, optional |
options.once |
Boolean, optional - If set to true , the content will only start if the user has not seen it before. If the user has already seen it before, nothing happens. Defaults to false . |
Returns
A Promise
that resolves once the content has been started.
endAll()
End all flows:
userflow.endAll()
Ends all currently active Userflow content (flows, checklists etc.), if any, for the user. The content will be hidden immediately.
If the user does not have any active content, nothing happens.
Resource center
You can programmatically open and close the resource center via Userflow.js. It's also possible to access its current state.
These APIs are most commonly used to render your own custom resource center launcher, instead of the default launcher.
Recipe for rendering custom resource center launcher
React example of rendering your own custom resource center launcher:
import userflow from 'userflow.js'
// Turn off the default resource center launcher same place you call userflow.init()
// userflow.init('...')
userflow.setResourceCenterLauncherHidden(true)
// Your app should put the custom launcher component
// (can be put in a menu or wherever)
const App = () => (
<div>
{/* Rest of app */}
<CustomResourceCenterLauncher />
</div>
)
// Component to render custom launcher
const CustomResourceCenterLauncher = () => {
// Monitor resource center state so we can display number of uncompleted tasks
const [resourceCenterState, setResourceCenterState] = useState(() =>
userflow.getResourceCenterState()
)
useEffect(() => {
const onChange = () => {
setResourceCenterState(userflow.getResourceCenterState())
}
userflow.on('resourceCenterChanged', onChange)
return () => userflow.off('resourceCenterChanged', onChange)
}, [])
return (
<button onClick={() => userflow.openResourceCenter()}>
HELP
{resourceCenterState &&
resourceCenterState.uncompletedChecklistTaskCount > 0 &&
` (${resourceCenterState.uncompletedChecklistTaskCount})`}
</button>
)
}
- Call
userflow.setResourceCenterLauncherHidden(true)
after youruserflow.init()
call. - Render a button or menu item with an onclick handler that calls
userflow.openResourceCenter()
. Alternatively, it can calluserflow.toggleResourceCenter()
if you want the button to close the resource center if it's already open. - Optionally: Monitor the resource center state via
userflow.on('resourceCenterChanged', listener)
anduserflow.getResourceCenterState()
to display the number of uncompleted tasks in the resource center's checklist (if any) or the number of unread announcements.
openResourceCenter()
Programmatically open the resource center:
userflow.openResourceCenter()
Opens the resource center, meaning the fully expanded resource center with all its customizable blocks will be shown.
For this method to work, you must have published a resource center that matches the current user first.
closeResourceCenter()
Programmatically close the resource center:
userflow.closeResourceCenter()
Closes the resource center. By default, this will collapse the resource center into the resource center launcher (the little help icon circle in the corner of the page). If you've called userflow.setResourceCenterLauncherHidden(true)
, then the resource center will be completely hidden.
toggleResourceCenter()
Flip between open and closed:
userflow.toggleResourceCenter()
Opens the resource center if it's currently closed, and closes it if it's currently open.
For this method to work, you must have published a resource center that matches the current user first.
setResourceCenterLauncherHidden()
Turn off the default resource center launcher:
userflow.setResourceCenterLauncherHidden(true)
Configures whether Userflow.js should render the default resource center launcher (the round help icon in the corner of the page) when the resource center is closed.
By default, the default launcher is rendered.
If you want to render your own custom resource center launcher, then set this to true
. Your custom launcher should call userflow.openResourceCenter()
or userflow.toggleResourceCenter()
when clicked.
Parameters
Parameter | Description |
---|---|
hidden |
Boolean, required - false means Userflow.js should render the default launcher, true means it should not and you'll render your own custom launcher. |
getResourceCenterState()
Get the resource center's current state, or null
if there's no active resource center.
Use it to check whether the resource is open, has a checklist, or to get the number of uncompleted checklist tasks or number of unread announcements e.g. for a custom resource center launcher.
Returns
A ResourceCenterState object
Advanced usage
on()
const listener = e => {
console.log(`Flow ${e.flow.id} ended`)
}
userflow.on('flowEnded', listener)
// ...later, when no longer needed:
userflow.off('flowEnded', listener)
Registers an event listener to be called when the given eventName
is triggered.
Parameters
Parameter | Description |
---|---|
eventName |
String, required - Name of event to listen for. See list of supported events. |
listener |
Function, required - Function to call when the event is triggered. Depending on the eventName , listener may receive a single argument providing more details about the event. |
off()
userflow.off('flowEnded', listener)
Removes an event listener previously registered with userflow.on
.
Parameters
Parameter | Description |
---|---|
eventName |
String, required - Name of event. See list of supported events. |
listener |
Function, required - Function to that was added with userflow.on . |
registerCustomInput()
Example HTML markup (in your app):
<label>Fruit</label>
<div class="combo-box">
<div class="combo-box-value">Banana</div>
<div class="combo-box-trigger">..icon..</div>
</div>
Example Userflow.js configuration:
userflow.registerCustomInput('.combo-box-value')
It's now possible to make conditions in the Flow Builder using the value of inputs labeled with
Fruit
. It works just as if the markup had used an<input>
like this:
<label>Fruit</label>
<div class="combo-box">
<input type="text" value="Banana" />
<div class="combo-box-trigger">..icon..</div>
</div>
Example of using the
getValue
function:
userflow.registerCustomInput('.combo-box', el => {
const valueEl = el.querySelector('.combo-box-value')
return (valueEl && valueEl.textContent) || ''
})
In this case, Userflow will return
Banana
as the value, and leave out the..icon..
part.
Teaches Userflow.js to treat HTML elements in your app as custom text inputs.
This is useful if, for example, you use combo boxes and want Userflow to treat them like regular <input>
elements. Instead of reading a value
property (as we do with input
elements), the text content of the custom input element is used instead. Or, you can supply a custom getValue
function to customize how to read a string value from an element.
Note that you can call this function multiple times to support multiple kinds of custom inputs.
Parameters
Parameter | Description |
---|---|
cssSelector |
String, required - Valid CSS selector that matches your custom input element. |
getValue |
Function, optional - If set, should be a function that takes an element and returns a string representing the custom input's current value. If not set, Userflow will default to using the text content of the whole element. |
setCustomNavigate()
Example, where
myRouter
is a fictive router object:
userflow.setCustomNavigate(url => myRouter.push(url))
Example with React Router app:
// File: history.js
import {createBrowserHistory} from 'history'
export default createBrowserHistory()
// File: index.js
import {Router} from 'react-router-dom'
import history from './history'
import App from './App'
ReactDOM.render(
<Router history={history}>
<App />
</Router>,
document.body
)
// File: wherever-you-load-userflow.js
import history from './history'
// ...
userflow.setCustomNavigate(url => history.push(url))
// ...
By default, when performing Go to page actions, Userflow will cause full page loads using window.location.href = url
.
Call this function to override this behavior.
This is useful for single page applications using in-app navigation through the window.history
API.
Parameters
Parameter | Description |
---|---|
customNavigate |
Function or null , required - A function taking a single string url parameter. Or null to turn off and use default behavior. |
setCustomScrollIntoView()
Example making Userflow always scroll tooltip targets to the vertical center of the viewport:
userflow.setCustomScrollIntoView(el => {
el.scrollIntoView({
behavior: 'smooth',
block: 'center'
})
})
For reference, this is how the default works:
userflow.setCustomScrollIntoView(el => {
el.scrollIntoView({
behavior: 'smooth',
block: 'nearest'
})
})
Override how Userflow.js scrolls elements into view, for example when showing a tooltip pointing to an element outside the viewport.
By default, scrolling will be animated and only happen if the element is outside the viewport.
Parameters
Parameter | Description |
---|---|
customScrollIntoView |
Function or null , required - A function taking a DOM Element . Or null to turn off and use default behavior. |
setUrlFilter()
Example removing all query parameters:
userflow.setUrlFilter(url => {
const parsed = new URL(url)
parsed.search = ''
return parsed.toString()
})
// Full URL:
// https://example.com/dashboard?q=secret&sort_by=name
// Filtered URL:
// https://example.com/dashboard
Example removing just a specific
?q
query parameter:
userflow.setUrlFilter(url => {
const parsed = new URL(url)
parsed.searchParams.delete('q')
return parsed.toString()
})
// Full URL:
// https://example.com/dashboard?q=secret&sort_by=name
// Filtered URL:
// https://example.com/dashboard?sort_by=name
Userflow passes the user's current URL to Userflow's servers. We use this for conditions matching the current URL and to automatically track page views. By default, we use the full URL including domain, path (/...
), query parameters (?...
) and fragment (#...
).
If your app's URLs contain sensitive information that should never leave the browser, you can customize URLs before they leaves the browser, e.g. to filter out sensitive parts.
Tip: If you want to verify that your URL filter works properly, try visiting a page with a filtered URL in your app. Then go to Userflow's Users tab and find your own user. Under Activity feed, click the most recent Page Viewed event to expand its attributes. Look for the Page URL attribute.
Parameters
Parameter | Description |
---|---|
urlFilter |
Function or null , required - A function taking a single string url parameter that returns a filtered URL (as a string). Or null to turn off and use default behavior of passing the full URL. |
setLinkUrlDecorator()
Example of adding an authentication token to knowledge base URLs:
// TODO: Add logic to get this auth token from your knowledge base provider
const authToken = '...'
userflow.setLinkUrlDecorator(url => {
// XXX It's important to only add the auth token to links to the desired domain
if (url.startsWith('https://my.kb.com/')) {
const parsed = new URL(url)
parsed.searchParams.set('authToken', authToken)
return parsed.toString()
}
return url
})
// Original URL:
// https://my.kb.com/articles/123
// Decorated URL:
// https://my.kb.com/articles/123?authToken=...
Userflow can link to external pages, such as to articles from your knowledge base.
If, for example, your knowledge base needs the user to log in and it supports a way to pass some sort of authentication token to automatically authorize access to the article, then you can use this function.
Every time Userflow.js needs to render a link, Userflow.js will call the decorator function with the URL as its only argument. The decorator function has to return the updated url.
Parameters
Parameter | Description |
---|---|
linkUrlDecorator |
Function or null , required - A function taking a single string url parameter that returns a decorated URL (as a string). Call this function with null to not decorate URLs again. |
setBaseZIndex()
Example of increasing the base z-index:
userflow.setBaseZIndex(9000000)
Userflow by default places all its floating elements at a z-index
at (or slightly above) 1234500
. Note that due to stacking of multiple Userflow layers, some actual z-index
values may be several thousands higher.
If your own app has elements that placed at higher z-index
values than this, then Userflow's elements may be shown below your own app's content. In this case, you may want to raise Userflow's base z-index
value.
Note that you do not always need to change the base z-index. E.g. for the launchers, checklists and the resource center you can change their individual z-index. For launchers you can do it via the advanced settings and for the checklists and resource center you can do it via the theme settings.
Parameters
Parameter | Description |
---|---|
baseZIndex |
Number, required - The minimum z-index that Userflow will place floating elements at. |
setInferenceAttributeFilter()
Example of ignoring all ids starting with
auto-
:
userflow.setInferenceAttributeFilter(
'id',
// Returns true if the id does not start with `auto-`
id => !id.startsWith('auto-')
)
Example of using an array containing both a function and a regular expression:
userflow.setInferenceAttributeFilter('id', [
// Ignore ids starting with `auto-`
id => !id.startsWith('auto-'),
// Only consider ids consisting of a-z and dashes
/^[a-z-]+$/
])
Restricts HTML element attribute values from being used for element inference.
By default, Userflow.js may use all values of attributes configured with userflow.setInferenceAttributeNames. The only exception is that, by default, id
s ending in numbers will be ignored. This is to support some dynamic IDs out-of-the-box. The same logic is applied to data-id
attributes.
Parameters
Parameter | Description |
---|---|
attributeName |
String, required - The attribute name the filter should apply to. Example values: id , data-testid . |
filters |
Function, RegExp instance, or an array of functions or RegExp instances, required - When Userflow considers an attribute value, it'll be passed through all the given filters before we decide to use it. Filter functions are called with the attribute value and must return a truthy value to allow Userflow.js to use it. Regular expressions must match the attribute value to allow Userflow.js to use it. You can pass a single function, a single regular expression, or an array with a mix. |
setInferenceAttributeNames()
Example of overriding the list of attribute names to use:
userflow.setInferenceAttributeNames(['name', 'placeholder', 'data-testid'])
Tells Userflow.js which HTML element attributes may be used for element inference.
By default, Userflow.js may use the values of the following element attributes for inference:
data-for
data-id
data-testid
data-test-id
for
id
name
placeholder
role
Parameters
Parameter | Description |
---|---|
attributeNames |
Array of strings, required - Names of HTML attributes that Userflow may use for element inference. |
setInferenceClassNameFilter()
Example of ignoring dynamic class names starting with
css-
:
userflow.setInferenceClassNameFilter(
// Returns true if the class name does not start with `css-`
cls => !cls.startsWith('css-')
)
Restricts CSS class names from being used for element inference.
By default, Userflow.js comes with a set of filters that attempt to exclude dynamic class names, such as ones starting with css-
, which may change from version to version of your own app, and therefore aren't reliable.
Parameters
Parameter | Description |
---|---|
filters |
Function, RegExp instance, or an array of functions or RegExp instances, required - When Userflow considers a class name, it'll be passed through all the given filters before we decide to use it. Filter functions are called with the class name and must return a truthy value to allow Userflow.js to use it. Regular expressions must match the class name to allow Userflow.js to use it. You can pass a single function, a single regular expression, or an array with a mix. |
setPageTrackingDisabled()
Turn off automatic tracking of
page_viewed
events:
userflow.setPageTrackingDisabled(true)
By default, Userflow.js automatically tracks page_viewed
events on initial page load and when the URL changes.
If you're not interested in storing these page_viewed
events, you can turn them off using this method.
Parameters
Parameter | Description |
---|---|
pageTrackingDisabled |
Boolean - Set to true to turn off page view tracking. Set to false to turn on again. |
disableEvalJs()
Example of blocking all "Evaluate JavaScript" actions from running:
userflow.disableEvalJs()
Userflow supports adding "Evaluate JavaScript" actions to things like buttons and triggers in the flow builder. This can be used to invoke custom code in your app, e.g. when a user clicks a button.
If you for security purposes want to turn this feature off, then call this function before your userflow.identify()
call. Note that it has to be called on every page load to have an effect.
load()
userflow.load(
() => {
console.log('Userflow initialized successfully!');
userflow.init('<your-userflow-token>');
userflow.identify('user123', { name: 'Jane Doe' });
},
(error) => {
console.warn('Error initializing Userflow:', error);
// Track failures without spamming monitoring tools
// Optional: Add custom alerting logic if necessary
}
);
Userflow.js typically handles initialization automatically, but errors may occasionally occur due to issues like Content Security Policy (CSP) restrictions or network problems. Instead of cluttering your monitoring tools with repeated load failure alerts, you can set up a system to gracefully handle and track these errors while ensuring they don’t go unnoticed. For handling content-security-policy (CSP) restrictions, see CSP policy for csp configurations.
Client-side events
These are events that you can subscribe to via userflow.on().
Note that these events are not related to the events you track with userflow.track
.
checklistEnded
Store in own database when a specific checklist is dismissed:
userflow.on('checklistEnded', event => {
if (event.checklist.id === '52e7e20d-f351-4528-9400-95de7b4ff6be') {
myDb.update({getStartedChecklistDismissed: true})
}
})
Emitted when a checklist is permanently dismissed. This typically happens when the user clicks "Dismiss checklist".
Event properties
When the event is emitted, listeners receive a single object argument with the following keys:
Key | Description |
---|---|
endReason |
String - Indicates why the checklist ended. Possible values: ACTION (a "Dismiss checklist" action on e.g. a task),USER_CLOSED (user clicked the Dismiss button), USERFLOWJS (programmatically dismissed via Userflow.js). |
checklist |
Content object - Checklist that ended. |
flowEnded
Emitted when the flow is permanently dismissed. This typically happens due to a user action, such as by clicking the X or clicking a button with a "Dismiss flow" action.
Event properties
When the event is emitted, listeners receive a single object argument with the following keys:
Key | Description |
---|---|
endReason |
String - Indicates why the flow ended. Possible values: ACTION (a "Start flow" or "Dismiss flow" action on e.g. a button or a trigger),USER_CLOSED (user clicked the X icon), USERFLOWJS (programmatically dismissed via Userflow.js). |
flow |
Content object - Flow that ended. |
resourceCenterChanged
Emitted when the resource center changes, either because its content changes, it opens or closes, its number of uncompleted tasks change, etc.
You can query the updated resource center state via userflow.getResourceCenterState().
Object interfaces
This section contains definitions of objects used in various methods and events.
Content object
Represents a content item (flow/checklist).
Properties
Key | Description |
---|---|
id |
String |
type |
String - Indicates the type of content. One of: checklist , flow |
ResourceCenterState object
Represents the current state of the resource center.
Properties
Key | Description |
---|---|
isOpen |
Boolean - true if the resource center is current open, false if it's closed. |
hasChecklist |
Boolean - true if the resource center has an active checklist, false otherwise. |
uncompletedChecklistTaskCount |
Number - Number of uncompleted checklist tasks. |
unreadAnnouncementCount |
Number - Number of unread announcements. |