Self-hosted Userflow.js

IMPORTANT: This is a WIP! Unless you've been explicitly told by Userflow to use this package, you should use our CDN-hosted version instead. See https://userflow.com/install

Userflow.js is hosted on Userflow's CDN (running on Cloudflare). We always recommend using the official Userflow.js CDN, unless you have very specific requirements as detailed in this document. See Userflow.js installation via CDN

This package allows you to self-host Userflow.js. This may be required in cases such as:

• Chrome Extensions using manifest v3, which does not allow for loading remote JavaScript code.
• When Userflow.js is deployed on customers' machines running behind a firewall. In this case, you're also responsible for proxying requests to Userflow's backend, which is not detailed in this document.

Backwards compatibility

Userflow.js connects to Userflow's backend and communicates about flows and user activity. When you use our official CDN, you're always guaranteed to run on the latest Userflow.js version. We occasionally, but rarely, introduce backwards incompatible changes between old Userflow.js versions and the currently deployed Userflow backend. We strive to keep old Userflow.js clients (browsers that have not refreshed in days, for example) working for at least 2 weeks. But this is not a strict guarantee - there could be very rare cases, where outdated and unsupported clients are rejected sooner.

If you choose to self-host, your Userflow.js version may run behind what the Userflow backend is designed to work with. It is therefore your responsibility to periodically upgrade to the latest userflow.js-self-hosted package version.

The consequence of an outdated and unsupported Userflow.js client version connecting to the Userflow backend, would simply be that no Userflow content will show, and calls to userflow.identify(), userflow.start() etc. will fail.

Contact Userflow if you require a more tightly controlled service agreement with explicit backwards compatibility guarantees.

Versioning

userflow.js-self-hosted uses Semantic Versioning, where versions are on the format 1.0.<USERFLOW_BUILD>, where <USERFLOW_BUILD> is a Userflow-internal build number (always incrementing). Example: 1.0.1002407. As long as the major version is 1, you can expect no changes in how to consume the package. If we one day change the structure of the package, requiring you to do some work, it'll be under a new major version, e.g. 2.0.<USERFLOW_BUILD>. This means it should always be safe and maintenance-free for you to upgrade to the latest patch version.

Usage

Install from npm:

npm install userflow.js-self-hosted

The package contains ES modules and a few CSS files. The entrypoint is ./userflow.js, whose default export is the userflow object - the one you call userflow.init() etc. on.

From your own code, you can import ./userflow.js via a dynamic import() call. Then grab the default export from that. Example:

const {default: userflow} = await import(
  'path/to/userflow.js-self-hosted/userflow.js'
)
userflow.init('<TOKEN>')
// userflow.identify(...) etc.

It'll automatically and lazily figure out how to import further modules from the same location as ./userflow.js was loaded from. For example, it won't load the resource center code if you're not using it. It'll also load CSS files from the same location. It never touches the official CDN at js.userflow.com (except if you use our default avatar SVGs).

You may also be able to use a bundler, such as Webpack, to transform the code into whatever format you want.

Usage in Chrome Extensions

Here's a super simple Chrome Extension which installs Userflow.js on myapp.com. It assumes that you've already installed userflow.js-self-hosted as an npm package.

manifest.json:

{
  "manifest_version": 3,
  "name": "Demo",
  "description": "Just a demo of using Userflow.js in manifest v3",
  "version": "0.1.0",
  "content_scripts": [
    {
      "matches": ["https://myapp.com/*"],
      "js": ["content-script.js"]
    }
  ],
  "web_accessible_resources": [
    {
      "matches": ["<all_urls>"],
      "resources": ["node_modules/userflow.js-self-hosted/*"]
    }
  ]
}

content-script.js:

;(async () => {
  const {default: userflow} = await import(
    chrome.runtime.getURL('node_modules/userflow.js-self-hosted/userflow.js')
  )
  userflow.init('<TOKEN>')
  // userflow.identify(...) etc.
})()

Since ./userflow.js is an ES module (so are all other .js files in the package), and Chrome extensions don't use ES modules themselves directly, you have to include it in your content script via this dynamic import() call. It's important to add the userflow.js-self-hosted package's path under web_accessible_resources in your manifest.json.

Userflow.js documentation

• Userflow.js Reference