Best practices for onboarding, upboarding, and offboarding users

Onboarding

A good onboarding experience is essential for every browser extension and is not hard to do. You can onboard people through a new tab or popup window.

Detecting installation

You can listen for your extension’s installation using runtime.onInstalled as follows:

browser.runtime.onInstalled.addListener(async ({ reason, temporary }) => {
  if (temporary) return; // skip during development
  switch (reason) {
    case "install":
      {
        const url = browser.runtime.getURL("views/installed.html");
        await browser.tabs.create({ url });
        // or: await browser.windows.create({ url, type: "popup", height: 600, width: 600, });
      }
      break;
    // see below
  }
});

Onboarding page content

Your onboarding page or popup should provide the essential information people need to get started. The content should, therefore, be brief and to the point. If your extension has many features, provide a separate help guide. The page should also complement the details provided on addons.mozilla.org, not repeat them in detail: the focus of the startup page should be how to use your extension, rather than what it does.

Consider adding the following information to the onboarding page, in roughly the order it’s listed below:

• Your extension’s name, as it appears on addons.mozilla.org, along with its icon or logo.
• A brief overview of your extension’s features and functions, enough information to reassure the new user they’ve installed the right extension.
• Practical information on how to use the extension, including details on how to access its features from a toolbar button, address bar button, sidebar, or context menu. Include at least one simple activity that the user can do immediately. If your extension has many features, focus on providing instructions for the things users do first.
  Tip: Provide an introductory video: showing someone how to use your extension can be a lot more effective than telling them. If you do create a video, provide closed captioning or a transcript to make sure it’s accessible.
• If your extension features can be customized, explain the options available and provide a link to the settings page. If settings are a significant feature of the extension or the range of settings is large, don’t expect your new user to be happy working through several pages of settings now: consider providing quick links to specific configurations.
  Tip: Use runtime.openOptionsPage() to open the settings page.
• If the user needs an account for your web service to make use of the extension, provide them with a link to sign in or register.
• If your extension has paid features, let the user know what those features are and how much they cost. If you have tiered payments, provide a comparison chart or link to one on the extension’s website.
  Tip: If you fund the extension’s development from donations, now is a good time to tell people and provide a link to the donate page.
• Provide links to additional information such as the extension support page, help guide, tutorials, and alike.
  Tip: If you have other extensions, give them a mention.

Having read your onboarding page, your new user should be confident about starting to use the extension immediately and know where to go if they need more information or support. If possible, they should have had some hands-on experience with key features.

Page design

Pay attention to the design and style of the page. Keep it consistent with your extension’s web page and AMO listing. For example, use consistent icons and colors. This helps reassure your user that they’ve installed and are using the right product. Follow the Photon Design System, where this doesn’t conflict with your product’s design.

Don’t include advertising on your post-install page. Ads can degrade people’s trust in an extension, draw people away before they engage with your extension, and create confusion about what extension has been installed among other drawbacks.

Onboarding page examples

Here's an example of a good onboarding page:

Upboarding

When you update to your extension, take the opportunity to tell your users about the new features and any fixed issues. In addition to being an opportunity to engage with active users, you can also re-engage with people who may have stopped or never started using your extension.

Detecting an upgrade

You can listen for your extension’s updates using runtime.onInstalled as follows:

browser.runtime.onInstalled.addListener(async ({ reason, temporary }) => {
  if (temporary) return; // skip during development
  switch (reason) {
    // see above
    case "update":
      {
        const url = browser.runtime.getURL("views/updated.html");
        await browser.tabs.create({ url });
        // or: await browser.windows.create({ url, type: "popup", height: 600, width: 600, });
      }
      break;
  }
});

Tip: If your upgrade involves requesting additional permissions, see Test permission requests for details on how to test those changes.

Upboarding page content

Consider adding the following information to the update page:

• A brief description of your extension. This should be enough so your regular users can identify which extension has updated and enough to entice lapsed users back to using the extension.
• A list of the new or improved features or issues corrected in this update. Include information on how to find and use the new or improved features.
• If any of the new features require payment to use, let the user know what those features are and how much they cost. If you have tiered payments, provide a comparison chart or link to one on the extension’s website. This is also a good time to request donations, remembering to add a link to the donate page.
• Provide links to key information such as the extension support page, help guide, tutorials, and alike.

Upboarding page examples

Here are some examples of good upboarding pages:

Offboarding

When a user decides to remove your extension, don’t miss the opportunity to gather feedback on why the extension hasn’t worked for them: you may not be able to get this user back but, by addressing their concerns you can hopefully reduce the number of users who might remove your extension in the future.

Setting up an offboarding page link

To gather information from leaving users, you need to set up an external webpage and then specify this in runtime.setUninstallURL(). This page then opens when a user removes the extension.

Page content

Consider adding the following information to the offboarding page:

• A “help us improve” message.
• A survey about why the user is removing the extension. Offer them a list of the most likely reasons and an optional free text area to provide more details.

Remember to keep everything brief. A departing user is unlikely to respond to a multiple question quiz about why they are going.

Offboarding page examples

Here are some examples of good offboarding pages: