Driver API

The Normandy driver is an object passed to all actions when they are created. It provides methods and attributes for performing operations that require more privileges than JavaScript is normally given. For example, the driver might provide a function for showing a notification bar within the Firefox UI, something normal JavaScript can’t trigger.

Environments in which actions are run (such as the Normandy client) implement the driver and pass it to the actions before executing them.


The driver object contains the following attributes:


Boolean describing whether the action is being executed in “testing” mode. Testing mode is mainly used when previewing recipes within the Normandy admin interface.


String containing the locale code of the user’s preferred language.

log(message, level='debug')

Log a message to an appropriate location. It’s up to the driver where these messages are stored; they could go to the browser console, or to a remote logging service, or somewhere else. If level is 'debug', then messages should only be logged if testing is true.

  • message – Message to log
  • level – Level to log message at, such as debug, info, or error. Defaults to debug.

Displays a Heartbeat survey to the user. Appears as a notification bar with a 5-star rating input for users to vote with. Also contains a “Learn More” button on the side. After voting, users are shown a thanks message and optionally a new tab is opened to a specific URL.

  • message – Primary message to display alongside rating stars.
  • engagementButtonLabel – Message to display on the engagement button. If specified, a button will be shown instead of the rating stars.
  • thanksMessage – Message to show after user submits a rating.
  • flowId – A UUID that should be unique to each call to this function. Used to track metrics related to this user interaction.
  • postAnswerUrl – URL to show users after they submit a rating. If empty, the user won’t be shown anything.
  • learnMoreMessage – Text to show on the “Learn More” button.
  • learnMoreUrl – URL to open when the “Learn More” button is clicked.
  • surveyId – Extra data to be stored in telemetry.
  • surveyVersion – Extra data to be stored in telemetry.
  • testing – Extra data to be stored in telemetry when Normandy is in testing mode.

A Promise that resolves with an event emitter.

The emitter returned by this function can be subscribed to using on method. For example:

let heartbeat = await Normandy.showHeartbeat(options);
heartbeat.on('NotificationOffered', function(data) {
   // Do something!

All events are given a data object with the following attributes:

The flowId passed into showHeartbeat.
Timestamp (number of milliseconds since Unix epoch) of when the event being emitted occurred.

The events emitted by the emitter include:

Emitted after the notification bar is shown to the user.
Emitted after the notification bar closes, either by being closed manually by the user, or automatically after voting.
Emitted when the user clicks the “Learn More” link.
Emitted when the user clicks the star rating bar and submits a rating. An extra score attribute is included on the data object for this event containing the rating the user submitted.
Emitted when the user clicks the engagement button. Only occurs if the engagementButtonLabel parameter was given when showHeartbeat was called.
Emitted after Heartbeat has sent flow data to the Telemetry servers. Only available on Firefox 46 and higher.


Individual events are only emitted once; if on is called after an event has already been emitted, the given callback will be called immediately.


Generates a v4 UUID. The UUID is randomly generated.

Returns:String containing the UUID.

The v4 UUID currently assigned to the user, loaded from the client’s localStorage. If no UUID exists, a new one is generated, and saved to localStorage.


Creates a storage object that can be used to store data on the client.

  • keyPrefix – Prefix to append to keys before storing them, to avoid collision with other actions using the storage.



Retrieves information about the user’s browser.

Returns:Promise that resolves with a client data object.

The client data object includes the following fields:

String containing the Firefox version.

String containing the update channel. Valid values include, but are not limited to:

  • 'release'
  • 'aurora'
  • 'beta'
  • 'nightly'
  • 'default' (self-built or automated testing builds)
Boolean specifying whether Firefox is set as the user’s default browser.
String containing the user’s default search engine identifier.
Boolean containing whether the user has set up Firefox Sync.
Integer specifying the number of desktop clients the user has added to their Firefox Sync account.
Integer specifying the number of mobile clients the user has added to their Firefox Sync account.
Integer specifying the total number of clients the user has added to their Firefox Sync account.
An object mapping of plugin names to Plugin() objects describing the plugins installed on the client.
String containing the distribution ID of Firefox. This value is undefined on Firefox versions older than 48.0.

Retrieves information about an installed add-on.

Returns:Promise that resolves with an add-on object.

The add-on object includes the following fields:

String containing the add-on’s ID.
String containing the add-on’s name.
String containing the version of the add-on.
A Date object of when the add-on was installed.
Boolean specifying whether is the add-on is active (true) or disabled (false).


class Plugin()

A simple object describing a plugin installed on the client. This is not the same object as returned by navigator.plugins, but it is similar.

The name of the plugin.


A human-readable description of the plugin.


The plugin’s version number string.


class Storage()

Storage objects allow actions to store data locally on the client. All methods return Promises, and can store any JSON serializable types. Unlike localStorage, items are not converted to strings.


Retrieves a value from storage.

  • key – Key to look up in storage.

A Promise that resolves with the value found in storage, or null if the key doesn’t exist.

Storage.setItem(key, value)

Inserts a value into storage under the given key.

  • key – Key to insert the value under.
  • value – Value to store.

A Promise that resolves when the value has been stored.


Removes a value from storage.

  • key – Key to remove.

A Promise that resolves when the value has been removed.


Removes all stored values. :returns: A Promise that resolves when the values have been removed.