tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

targeting-attributes.md (30107B)

Targeting attributes

When you create ASRouter messages such as contextual feature recommendations or onboarding cards, you may choose to include targeting information with those messages.

Targeting information must be captured in an expression that has access to the following attributes. You may combine and compare any of these attributes as needed.

Please note that some targeting attributes require stricter controls on the telemetry than can be collected, so when in doubt, ask for review.

Available attributes

Detailed usage

`addonsInfo`

Provides information about the add-ons the user has installed.

Note that the name, userDisabled, and installDate is only available if isFullData is true (this is usually not the case right at start-up).

Due to an existing bug, `userDisabled` is not currently available

Examples

addonsInfo.addons["unicornaddon@mozilla.org"]

addonsInfo.isFullData && addonsInfo.addons["unicornaddon@mozilla.org"].userDisabled

Definition

declare const addonsInfo: Promise<AddonsInfoResponse>;
interface AddonsInfoResponse {
  // Does this include extra information requiring I/O?
  isFullData: boolean;
  // addonId should be something like activity-stream@mozilla.org
  [addonId: string]: {
    // Version of the add-on
    version: string;
    // (string) e.g. "extension"
    type: AddonType;
    // Version of the add-on
    isSystem: boolean;
    // Is the add-on a webextension?
    isWebExtension: boolean;
    // The name of the add-on
    name: string;
    // Is the add-on disabled?
    // CURRENTLY UNAVAILABLE due to an outstanding bug
    userDisabled: boolean;
    // When was it installed? e.g. "2018-03-10T03:41:06.000Z"
    installDate: string;
  };
  // Has the user installed addons beyond the built in and system addons?
  hasInstalledAddons: boolean;
}

`attributionData`

An object containing information on exactly how Firefox was downloaded

Examples

attributionData && attributionData.campaign == "back_to_school"

Definition

declare const attributionData: AttributionCode;
interface AttributionCode {
  // Descriptor for where the download started from
  campaign: string,
  // A source, like addons.mozilla.org, or google.com
  source: string,
  // The medium for the download, like if this was referral
  medium: string,
  // Additional content, like an addonID for instance
  content: string
}

`browserSettings`

Examples

browserSettings.update.enabled

browserSettings.update.channel == 'beta'

Definition

declare const browserSettings: {
  attribution: undefined | {
    // Referring partner domain, when install happens via a known partner
    // e.g. google.com
    source: string;
    // category of the source, such as "organic" for a search engine
    // e.g. organic
    medium: string;
    // identifier of the particular campaign that led to the download of the product
    // e.g. back_to_school
    campaign: string;
    // identifier to indicate the particular link within a campaign
    // e.g. https://mozilla.org/some-page
    content: string;
  },
  update: {
    // Is auto-downloading enabled?
    autoDownload: boolean;
    // What release channel, e.g. "nightly"
    channel: string;
    // Is updating enabled?
    enabled: boolean;
  }
}

`buildId`

The build ID (MOZ_BUILDID) parsed as a number to allow for comparisons.

Examples

buildId >= 202501010000

Definition

declare const buildId: number;

`currentDate`

The current date at the moment message targeting is checked.

Examples

currentDate > "Wed Oct 03 2018 00:00:00"|date

Definition

declare const currentDate; ECMA262DateString;
// ECMA262DateString = Date.toString()
type ECMA262DateString = string;

`devToolsOpenedCount`

Number of usages of the web console.

Examples

devToolsOpenedCount > 10

Definition

declare const devToolsOpenedCount: number;

`isDefaultBrowser`

Is Firefox the user's default browser?

Definition

declare const isDefaultBrowser: boolean;

`isDefaultBrowserUncached`

Behaves the same as isDefaultBrowser, but retrieves the current value directly from shell service instead of using the cached value. This may not be as performant.

`isDefaultHandler`

Is Firefox the user's default handler for various file extensions?

Windows-only.

Definition

declare const isDefaultHandler: {
  pdf: boolean;
  html: boolean;
};

Examples

isDefaultHandler.pdf

`defaultPDFHandler`

Information about the user's default PDF handler

Windows-only.

Definition

declare const defaultPDFHandler: {
  // Does the user have a default PDF handler registered?
  registered: boolean;

  // Is the default PDF handler a known browser?
  knownBrowser: boolean;
};

`firefoxVersion`

The major Firefox version of the browser

Examples

firefoxVersion > 63

Definition

declare const firefoxVersion: number;

`launchOnLoginEnabled`

Is the launch on login option enabled?

declare const launchOnLoginEnabled: boolean;

`locale`

The current locale of the browser including country code, e.g. en-US.

Examples

locale in ["en-US", "de-DE"]

Definition

declare const locale: string;

`localeLanguageCode`

The current locale of the browser NOT including country code, e.g. en. This is useful for matching all countries of a particular language.

Examples

localeLanguageCode == "en"

Definition

declare const localeLanguageCode: string;

`needsUpdate`

Does the client have the latest available version installed

declare const needsUpdate: boolean;

`packageFamilyName`

Provides the package family name as given by the MSIX that Firefox was installed from, or the empty string if not installed from MSIX.

Examples

"MozillaNightly" in packageFamilyName

Definition

declare const packageFamilyName: string;

`pinnedSites`

The sites (including search shortcuts) that are pinned on a user's new tab page.

Examples

"foo.com" in pinnedSites|mapToProperty("host")

"duckduckgo.com" in pinnedSites[.searchTopSite == true]|mapToProperty("host")

Definition

interface PinnedSite {
  // e.g. https://foo.mozilla.com/foo/bar
  url: string;
  // e.g. foo.mozilla.com
  host: string;
  // is the pin a search shortcut?
  searchTopSite: boolean;
}
declare const pinnedSites: Array<PinnedSite>

`previousSessionEnd`

Timestamp of the previously closed session.

Definition

declare const previousSessionEnd: UnixEpochNumber;
// UnixEpochNumber is UNIX Epoch timestamp, e.g. 1522843725924
type UnixEpochNumber = number;

`primaryResolution`

An object containing the available width and available height of the primary monitor in pixel values. The values take into account the existence of docks and task bars.

Definition

interface primaryResolution {
  width: number;
  height: number;
}

`profileAgeCreated`

The date the profile was created as a UNIX Epoch timestamp.

Definition

declare const profileAgeCreated: UnixEpochNumber;
// UnixEpochNumber is UNIX Epoch timestamp, e.g. 1522843725924
type UnixEpochNumber = number;

`profileAgeReset`

The date the profile was reset as a UNIX Epoch timestamp (if it was reset).

Examples

!profileAgeReset

Definition

// profileAgeReset can be undefined if the profile was never reset
// UnixEpochNumber is number, e.g. 1522843725924
declare const profileAgeReset: undefined | UnixEpochNumber;
// UnixEpochNumber is UNIX Epoch timestamp, e.g. 1522843725924
type UnixEpochNumber = number;

`providerCohorts`

Information about cohort settings (from prefs, including shield studies) for each provider.

Examples

providerCohorts.cfr == "foo_test"

Definition

declare const providerCohorts: {
  [providerId: string]: string;
}

`region`

Country code retrieved from location.services.mozilla.com. Can be "" if request did not finish or encountered an error.

Examples

region == "CA"

Definition

declare const region: string;

`searchEngines`

Information about the current and available search engines. If the user's engine is a third party engine, then the value will be null.

Examples

searchEngines.current == "google"

Definition

declare const searchEngines: Promise<SearchEnginesResponse>;
interface SearchEnginesResponse: {
  current: SearchEngineId;
  installed: Array<SearchEngineId>;
}
// This is an identifier for a search engine such as "google" or "ddg"
type SearchEngineId = string;

`sync`

Information about synced devices.

Examples

sync.mobileDevices > 0

Definition

declare const sync: {
  desktopDevices: number;
  mobileDevices: number;
  totalDevices: number;
}

`topFrecentSites`

Information about the browser's top 25 frecent sites.

Please note this is a restricted targeting property that influences what telemetry is allowed to be collected may not be used without review

Examples

"mozilla.com" in topFrecentSites[.lastVisitDate > 1522843725924]|mapToProperty("host")

Definition

declare const topFrecentSites: Promise<Array<TopSite>>
interface TopSite {
  // e.g. https://foo.mozilla.com/foo/bar
  url: string;
  // e.g. foo.mozilla.com
  host: string;
  // Deprecated property unsupported in Firefox 145+, refer to bug 1987415 for guidance on future options.
  frecency: number;
  lastVisitDate: UnixEpochNumber;
}
// UnixEpochNumber is UNIX Epoch timestamp, e.g. 1522843725924
type UnixEpochNumber = number;

`totalBookmarksCount`

Total number of bookmarks.

Definition

declare const totalBookmarksCount: number;

`usesFirefoxSync`

Does the user use Firefox sync?

Definition

declare const usesFirefoxSync: boolean;

`isFxAEnabled`

Does the user have Firefox sync enabled? The service could potentially be turned off for enterprise builds.

Definition

declare const isFxAEnabled: boolean;

`isFxASignedIn`

Is the user signed in to a Firefox Account?

Definition

declare const isFxASignedIn: Promise<boolean>

`creditCardsSaved`

The number of credit cards the user has saved for Forms and Autofill.

Examples

creditCardsSaved > 1

Definition

declare const creditCardsSaved: Promise<number>

`addressesSaved`

The number of addresses the user has saved for Forms and Autofill.

Examples

addressesSaved > 1

Definition

declare const addressesSaved: Promise<number>

`archBits`

The number of bits used to represent a pointer in this build.

Definition

declare const archBits: number;

`xpinstallEnabled`

Pref used by system administrators to disallow add-ons from installed altogether.

Definition

declare const xpinstallEnabled: boolean;

`currentTabInstalledAsWebApp`

Returns whether the current tab has a matching Web App (Taskbar Tab) installed.

Definition

declare const currentTabInstalledAsWebApp: Promise<boolean>;

`currentTabGroups`

Returns the number of currently open tab groups.

`savedTabGroups`

Returns the number of tab groups the user has saved.

`hasPinnedTabs`

Does the user have any pinned tabs in any windows.

Definition

declare const hasPinnedTabs: boolean;

`hasAccessedFxAPanel`

Boolean pref that gets set the first time the user opens the FxA toolbar panel

Definition

declare const hasAccessedFxAPanel: boolean;

`totalBlockedCount`

Total number of events from the content blocking database

Definition

declare const totalBlockedCount: number;

`recentBookmarks`

An array of GUIDs of recent bookmarks as provided by `NewTabUtils.getRecentBookmarks`

Definition

interface Bookmark {
  bookmarkGuid: string;
  url: string;
  title: string;
  ...
}
declare const recentBookmarks: Array<Bookmark>

`userPrefs`

Information about user facing prefs configurable from about:preferences.

Examples

userPrefs.cfrFeatures == false

Definition

declare const userPrefs: {
  cfrFeatures: boolean;
  cfrAddons: boolean;
}

`attachedFxAOAuthClients`

Information about connected services associated with the FxA Account. Return an empty array if no account is found or an error occurs.

Definition

interface OAuthClient {
  // OAuth client_id of the service
  // https://docs.telemetry.mozilla.org/datasets/fxa_metrics/attribution.html#service-attribution
  id: string;
  lastAccessedDaysAgo: number;
}

declare const attachedFxAOAuthClients: Promise<OAuthClient[]>

Examples

{
  id: "7377719276ad44ee",
  name: "Pocket",
  lastAccessTime: 1513599164000
}

`platformName`

Platform information.

Definition

declare const platformName = "linux" | "win" | "macosx" | "android" | "other";

`memoryMB`

The amount of RAM available to Firefox, in megabytes.

Definition

declare const memoryMB = number;

`messageImpressions`

Dictionary that maps message ids to impression timestamps. Timestamps are stored in consecutive order. Can be used to detect first impression of a message, number of impressions. Can be used in targeting to show a message if another message has been seen. Impressions are used for frequency capping so we only store them if the message has frequency configured. Impressions for badges might not work as expected: we add a badge for every opened window so the number of impressions stored might be higher than expected. Additionally not all badges have frequency cap so messageImpressions might not be defined. Badge impressions should not be used for targeting.

Definition

declare const messageImpressions: { [key: string]: Array<UnixEpochNumber> };

`blockedCountByType`

Returns a breakdown by category of all blocked resources in the past 42 days.

Definition

declare const blockedCountByType: { [key: string]: number };

Examples

Object {
  trackerCount: 0,
  cookieCount: 34,
  cryptominerCount: 0,
  fingerprinterCount: 3,
  socialCount: 2
}

`browserIsSelected`

A context property included for all triggers, indicating whether the tab the trigger came from is the currently selected tab. For some triggers that don't actually emit from tabs, this is always true. For other triggers, like openURL, this can be false if the trigger happened in a background tab.

Definition

declare const browserIsSelected: boolean;

`isAIWindow`

A context property included for all triggers that evaluates to true when the message comes from an AI Window, and false otherwise.

Definition

declare const isAIWindow: boolean;

Examples

isAIWindow

!isAIWindow

isAIWindow == isAIWindow
or equivalently
(isAIWindow || !isAIWindow)

`isChinaRepack`

Does the user use the partner repack distributed by Mozilla Online, a wholly owned subsidiary of the Mozilla Corporation that operates in China.

Definition

declare const isChinaRepack: boolean;

`userId`

A unique user id generated by Normandy (note that this is not clientId).

Definition

declare const userId: string;

`profileRestartCount`

A session counter that shows how many times the browser was started. More info about the details in the telemetry docs.

Definition

declare const profileRestartCount: number;

`homePageSettings`

An object reflecting the current settings of the browser home page (about:home)

Definition

declare const homePageSettings: {
  isDefault: boolean;
  isLocked: boolean;
  isWebExt: boolean;
  isCustomUrl: boolean;
  urls: Array<URL>;
}

interface URL {
  url: string;
  host: string;
}

Examples

Object {
  isDefault: true,
  isLocked: false,
  isCustomUrl: false,
  isWebExt: false,
  urls: [
    { url: "about:home", host: "" }
  ],
}

Object {
  isDefault: true,
  isLocked: true,
  isCustomUrl: false,
  isWebExt: false,
  urls: [
    { url: "about:home", host: "" }
  ],
}

Object {
  isDefault: false,
  isLocked: false,
  isCustomUrl: true,
  isWebExt: false,
  urls: [
    { url: "https://www.google.com", host: "google.com" }
  ],
}

Object {
  isDefault: false,
  isLocked: false,
  isCustomUrl: true,
  isWebExt: false,
  urls: [
    { url: "https://www.google.com", host: "google.com" },
    { url: "https://www.youtube.com", host: "youtube.com" }
  ],
}

Object {
  isDefault: false,
  isLocked: false,
  isCustomUrl: false,
  isWebExt: true,
  urls: [
    { url: "moz-extension://123dsa43213acklncd/home.html", host: "" }
  ],
}

`newtabAddonVersion`

The full version string of the built-in New Tab add-on that is actively in use. Comparisons should be done with the versionCompare filter expression.

Definition

declare const newtabAddonVersion: string;

`newtabSettings`

An object reflecting the current settings of the browser newtab page (about:newtab)

Definition

declare const newtabSettings: {
  isDefault: boolean;
  isWebExt: boolean;
  isCustomUrl: boolean;
  url: string;
  host: string;
}

Examples

Object {
  isDefault: true,
  isCustomUrl: false,
  isWebExt: false,
  url: "about:newtab",
  host: "",
}

Object {
  isDefault: false,
  isCustomUrl: true,
  isWebExt: false,
  url: "https://www.google.com",
  host: "google.com",
}

Object {
  isDefault: false,
  isCustomUrl: false,
  isWebExt: true,
  url: "moz-extension://123dsa43213acklncd/home.html",
  host: "",
}

`activeNotifications`

True when an infobar style message is displayed or when the awesomebar is expanded to show a message (for example onboarding tips).

`isMajorUpgrade`

A boolean. true if the browser just updated to a new major version.

`hasActiveEnterprisePolicies`

A boolean. true if any Enterprise Policies are active.

`userMonthlyActivity`

Returns an array of entries in the form [int, unixTimestamp] for each day of user activity where the first entry is the total urls visited for that day.

`doesAppNeedPin`

Checks if Firefox app can be and isn't pinned to OS taskbar/dock or Windows start menu in MSIX builds.

`doesAppNeedPinUncached`

Does the same as doesAppNeedPin, but retrieves the current value directly from shell service instead of using the cached value. This may not be as performant.

`doesAppNeedPrivatePin`

Checks if Firefox Private Browsing Mode can be and isn't pinned to OS taskbar/dock. Currently this only works on certain Windows versions.

`isBackgroundTaskMode`

Checks if this invocation is running in background task mode.

`backgroundTaskName`

A non-empty string task name if this invocation is running in background task mode, or null if this invocation is not running in background task mode.

`userPrefersReducedMotion`

Checks if user prefers reduced motion as indicated by the value of a media query for prefers-reduced-motion.

`distributionId`

A string containing the id of the distribution, or the empty string if there is no distribution associated with the build.

`fxViewButtonAreaType`

A string of the name of the container where the Firefox View button is shown, null if the button has been removed.

`alltabsButtonAreaType`

A string of the name of the container where the Tab Overflow button (or All Tabs button) is shown, null if the button has been removed.

`hasMigratedBookmarks`

A boolean. true if the user ever used the Migration Wizard to migrate bookmarks since Firefox 113 released. Available in Firefox 113+; will not be true if the user had only ever migrated bookmarks prior to Firefox 113 being released.

`hasMigratedCSVPasswords`

A boolean. true if CSV passwords have been imported via the migration wizard since Firefox 116 released. Available in Firefox 116+; ; will not be true if the user had only ever migrated CSV passwords prior to Firefox 116 being released.

`hasMigratedHistory`

A boolean. true if the user ever used the Migration Wizard to migrate history since Firefox 113 released. Available in Firefox 113+; will not be true if the user had only ever migrated history prior to Firefox 113 being released.

`hasMigratedPasswords`

A boolean. true if the user ever used the Migration Wizard to migrate passwords since Firefox 113 released. Available in Firefox 113+; will not be true if the user had only ever migrated passwords prior to Firefox 113 being released.

`useEmbeddedMigrationWizard`

A boolean. true if the user is configured to use the embedded Migration Wizard in about:welcome.

`isRTAMO`

A boolean. true when RTAMO has been used to download Firefox, false otherwise.

`canCreateSelectableProfiles`

A boolean. true when both the current install and current profile support creating additional profiles using the SelectableProfileService; false otherwise.

`hasSelectableProfiles`

A boolean. true when the toolkit.profiles.storeID pref has a value. Indicates that the profile is part of a profile group managed by the SelectableProfileService, and the user has used the multiple profiles feature. false otherwise.

`unhandledCampaignAction`

A string. A special message action to be executed on first-run. For example, "SET_DEFAULT_BROWSER" when the user selected to set as default via the install marketing page and set default has not yet been automatically triggered, null otherwise. Currently supported actions include "PIN_AND_DEFAULT", "PIN_FIREFOX_TO_TASKBAR", and "SET_DEFAULT_BROWSER".

`isMSIX`

A boolean. true when hasPackageId is true on Windows, false otherwise.

`isDeviceMigration`

A boolean. true when support.mozilla.org has been used to download the browser as part of a "migration" campaign, for device migration guidance, false otherwise.

`screenImpressions`

An array that maps about:welcome screen IDs to their most recent impression timestamp. Should only be used for unique screen IDs to avoid unintentionally targeting messages with identical screen IDs.

Definition

declare const screenImpressions: { [key: string]: Array<UnixEpochNumber> };

`systemArch`

The architecture of this Firefox build: x86, x86-64 or aarch64.

Definition

declare const systemArch: string | null;

`totalSearches`

Returns the number of times a user has completed a search in the URL Bar. The number is arbitrarily capped at 100.

`profileGroupId`

Returns the stable profile group ID used for data reporting.

`currentProfileId`

The integer-valued identifier of the current selectable profile, as reported by SelectableProfileService, converted to a string.

`profileGroupProfileCount`

The number of profiles in the current profile group or zero if either the feature is not enabled or the user has not created any profiles.

`backupsInfo`

Provides information about the backups a user has in the default directory.

Definition

declare const backupsInfo: {
  // True if exactly one backup was found.
  found: boolean;

  // True if multiple backups were found.
  multipleBackupsFound: boolean;

  // Absolute path to the selected backup to restore when `found` is true.
  // Null when no single file is selected (none or multiple).
  backupFileToRestore: string | null;
};

`backupArchiveEnabled`

Indicates whether the archive function is enabled by BackupService.

`backupRestoreEnabled`

Indicates whether the restore function is enabled by BackupService.

`isEncryptedBackup`

Indicates whether a user has selected an encrypted or non-encrypted backup method during the spotlight onboarding flow. (Refers to the messaging-system-action.backupChooser pref.)