nagai/fune
3
0
Fork 0
forked from mirrors/gecko-dev
Code Pull requests Activity
fune/browser/components/newtab/content-src/asrouter/docs/targeting-attributes.md
Artur Iunusov c4ec4d7309 Bug 1671548 - Remove fission experiment support code and prefs, r=smaug, 
r=tritter

- backed out changesets: 1660057, 1667426, 1674214,
1669749, 1685801, 1667381
- fission.experiment support removed everywhere, including telemetry

Differential Revision: https://phabricator.services.mozilla.com/D165169
2023-01-17 10:05:36 +00:00

20 KiB
Raw Blame History

Targeting attributes

When you create ASRouter messages such as snippets, 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 colleted, 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

  • Has the user installed the unicorn addon?
addonsInfo.addons["unicornaddon@mozilla.org"]
  • Has the user installed and disabled the unicorn addon?
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;
  };
}

attributionData

An object containing information on exactly how Firefox was downloaded

Examples

  • Was the browser installed via the "back_to_school" campaign?
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

  • update, which has information about Firefox update channel

Examples

  • Is updating enabled?
browserSettings.update.enabled
  • Is beta channel?
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;
  }
}

currentDate

The current date at the moment message targeting is checked.

Examples

  • Is the current date after Oct 3, 2018?
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

  • Has the user opened the web console more than 10 times?
devToolsOpenedCount > 10

Definition

declare const devToolsOpenedCount: number;

isDefaultBrowser

Is Firefox the user's default browser?

Definition

declare const isDefaultBrowser: boolean;

firefoxVersion

The major Firefox version of the browser

Examples

  • Is the version of the browser greater than 63?
firefoxVersion > 63

Definition

declare const firefoxVersion: number;

locale

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

Examples

  • Is the locale of the browser either English (US) or German (Germany)?
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

  • Is the locale of the browser any English locale?
localeLanguageCode == "en"

Definition

declare const localeLanguageCode: string;

needsUpdate

Does the client have the latest available version installed

declare const needsUpdate: boolean;

pinnedSites

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

Examples

  • Has the user pinned any site on foo.com?
"foo.com" in pinnedSites|mapToProperty("host")
  • Does the user have a pinned duckduckgo.com search shortcut?
"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;

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

  • Was the profile never reset?
!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

  • Is the user in the "foo_test" cohort for snippets?
providerCohorts.snippets == "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

  • Is the user in Canada?
region == "CA"

Definition

declare const region: string;

searchEngines

Information about the current and available search engines.

Examples

  • Is the current default search engine set to google?
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 "amazondotcom"
type SearchEngineId = string;

sync

Information about synced devices.

Examples

  • Is at least 1 mobile device synced to this profile?
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

  • Is mozilla.com in the user's top frecent sites with a frececy greater than 400?
"mozilla.com" in topFrecentSites[.frecency >= 400]|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;
  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>

xpinstallEnabled

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

Definition

declare const xpinstallEnabled: boolean;

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;

isWhatsNewPanelEnabled

Boolean pref that controls if the What's New panel feature is enabled

Definition

declare const isWhatsNewPanelEnabled: 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;
  snippets: 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";

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 messageImpressions: { [key: string]: number };

Examples

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

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

  • Default about:home
Object {
  isDefault: true,
  isLocked: false,
  isCustomUrl: false,
  isWebExt: false,
  urls: [
    { url: "about:home", host: "" }
  ],
}
  • Default about:home with locked preference
Object {
  isDefault: true,
  isLocked: true,
  isCustomUrl: false,
  isWebExt: false,
  urls: [
    { url: "about:home", host: "" }
  ],
}
  • Custom URL
Object {
  isDefault: false,
  isLocked: false,
  isCustomUrl: true,
  isWebExt: false,
  urls: [
    { url: "https://www.google.com", host: "google.com" }
  ],
}
  • Custom URLs
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" }
  ],
}
  • Web extension
Object {
  isDefault: false,
  isLocked: false,
  isCustomUrl: false,
  isWebExt: true,
  urls: [
    { url: "moz-extension://123dsa43213acklncd/home.html", host: "" }
  ],
}

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

  • Default about:newtab
Object {
  isDefault: true,
  isCustomUrl: false,
  isWebExt: false,
  url: "about:newtab",
  host: "",
}
  • Custom URL
Object {
  isDefault: false,
  isCustomUrl: true,
  isWebExt: false,
  url: "https://www.google.com",
  host: "google.com",
}
  • Web extension
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.

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.

colorwaysActive

A boolean. true when there are Colorways available.

userEnabledActiveColorway

A boolean. true when user has an active Colorway theme enabled.

inMr2022Holdback

A boolean. true when the user is in the Major Release 2022 holdback study.

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.