Userflow.js API Reference

Note to non-developers: You do not need to know any of this to use Userflow. This is an advanced guide for deep custom integrations.

The userflow global object

Once you've installed Userflow.js in your web app, a userflow object will be available globally on window in users' browsers.

userflow.init(token)

Initializes Userflow.js to target your company. Must be called once (per page load) before you make any other call.

Parameter Type Description
token String, required Your Userflow Token, which you can find under Settings.

Example:

userflow.init('bmztslyu5zgujmcvna34mggj44')

userflow.identify(userId, properties)

Informs Userflow of a user that's signed into your app. You should call this once on any page load where a user is authenticated.

If properties is set, the given properties will be merged into the user's existing data in Userflow. Any properties you leave out will be left as-is in Userflow.

It's up to you which properties you want to send to Userflow. The only required field is userId. Make sure not to send any sensitive data such as passwords. We recommend sending name and/or email so you can easily tell users apart in Userflow without relying on IDs only.

If the user has any active flows, they will be displayed.

Parameter Type Description
userId String, required The user's ID in your database.
properties Object, optional An object with attributes you know about the user.
properties.name String, optional User's name
properties.email String, optional User's email
properties.signedUpAt String, optional Date and time (in ISO 8601 format) the user signed up for your service.
properties.traits Object, optional An object with any other custom traits that you want to store with the user. These traits can be used in flow content and conditions to personalize the user experience. Each trait is a key-value pair. The key must be snake_cased (i.e. all lower case with _ as word separator). Values can be either strings, integers, decimals, booleans or datetimes (in ISO 8601 format).

Returns a Promise that resolves once the identify call succeeds.

Minimal example of only sending userId:

userflow.identify('123456')

Example of sending all standard properties and a few custom traits:

userflow.identify('123456', {
  name: 'Jane Smith',
  email: 'jane@example.com',
  createdAt: '2019-06-14T16:25:49Z',
  traits: {
    user_role: 'admin',
    items_created_total: 42
  }
})

userflow.isIdentified()

Returns true if userflow.identify has been called. false otherwise.

userflow.updateUser(properties)

Updates properties for a user that has already been identified with userflow.identify since the last page load.

Use this if you need to update a property after some event happens.

The properties argument takes the exact same format as in userflow.identify.

Example of updating a user's favorite color after they pick it in your UI:

userflow.updateUser({
  traits: {
    favorite_color: 'red'
  }
})

Returns a Promise that resolves once the update succeeds.

userflow.startFlow(flowId)

Starts a flow for the currently signed-in user. The flow will display immediately.

Use this to programmatically start a flow 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.

Parameter Type Description
flowId String, required ID of the flow to start. You can find a flow's ID in Userflow on the flow's "Link/Embed" tab. It's also the ID you see in the URL: /app/{company}/flows/{flowId}

Returns a Promise that resolves once the flow has been started.

Example:

userflow.startFlow('89eff72a-d0ae-4be6-b241-1ab04e3da7cc')

userflow.endAllFlows()

Ends all currently active flows, if any, for the user. The flows will be hidden immediately.

If the user does not have any active flows, nothing happens.

userflow.reset()

Makes Userflow forget about the currently active user and immediately hides any active flows.

Call this when users sign out of your app.

userflow.on(eventName, listener)

Registers an event listener to be called when the given event is triggered.

Parameter Type Description
eventName String, required Name of event to listen for. See list of supported events below.
listener Function, required Function to call when the event is triggered. Depending on the event, the function may receive arguments.

Supported events:

Event Arguments Description
flowvisibilitychange visible (boolean) Called with visible = true when a flow is shown (started) or with visible = fale when a flow is hidden (ended).

Example:

const listener = visible => {
  console.log(visible ? 'Flow is visible' : 'Flow was hidden')
}
userflow.on('flowvisibilitychange', listener)

// ...later, when no longer needed:
userflow.off('flowvisibilitychange', listener)

userflow.off(eventName, listener)

Removes an event listener previously registered with userflow.on.

Parameter Type Description
flowId String, required Name of event.
listener Function, required Function to that was added with userflow.on.

userflow.setCustomInputSelector(customInputSelector)

Teaches Userflow.js to treat specific elements 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.

Parameter Type Description
customInputSelector String or null, required Valid CSS selector or null to turn off. Note that you can include multiple types of custom inputs by separating each selector with a comma.

Example HTML markup:

<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.setCustomInputSelector('.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 been like this:

<label>Fruit</label>
<div class="combo-box">
  <input type="text" value="Banana" />
  <div class="combo-box-trigger">..icon..</div>
</div>

Got questions? We're here for you!

The best way to get help is to
We usually reply within 5 minutes
You can also send an email to support@getuserflow.com
We usually reply within a few hours