firefox-main/browser/components/asrouter/modules/ASRouterScreenUtils.sys.mjs (file symbol)

Source code

Revision control

Copy as Markdown

Other Tools

/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
const lazy = {};
ChromeUtils.defineESModuleGetters(lazy, {
ASRouter: "resource:///modules/asrouter/ASRouter.sys.mjs",
ASRouterTargeting: "resource:///modules/asrouter/ASRouterTargeting.sys.mjs",
SpecialMessageActions:
});
export const ASRouterScreenUtils = {
/**
* Filter the given screens in place with a predicate.
*
* @param {object[]} screens - The screens to filter.
* @param {Function} callback - The predicate for filtering the screens.
*/
async removeScreens(screens, callback) {
for (let i = 0; i < screens?.length; i++) {
if (await callback(screens[i], i)) {
screens.splice(i--, 1);
}
}
},
/**
* Given a JEXL expression, returns the evaluation of the expression or returns
* true if the expression did not evaluate successfully. This is also used for
* attribute targeting for the checklist feature.
*
* @param {string} targeting - The JEXL expression that will be evaluated
* @returns {boolean}
*/
async evaluateScreenTargeting(targeting) {
const result = await lazy.ASRouter.evaluateExpression({
expression: targeting,
context: lazy.ASRouterTargeting.Environment,
});
if (result?.evaluationStatus?.success) {
return result.evaluationStatus.result;
}
return true;
},
/**
* Returns the string identifier of an unhandled campaign action, if
* applicable otherwise false.
*
* @returns {string|boolean}
*/
async getUnhandledCampaignAction() {
const UNHANDLED_CAMPAIGN_ACTION_TARGETING = "unhandledCampaignAction";
let result = await lazy.ASRouter.evaluateExpression({
expression: UNHANDLED_CAMPAIGN_ACTION_TARGETING,
context: lazy.ASRouterTargeting.Environment,
});
return result?.evaluationStatus?.result || false;
},
/**
* Filter out screens whose targeting do not match.
*
* Given an array of screens, each screen will have it's `targeting` property
* evaluated, and removed if it's targeting evaluates to false. Screens that
* are kept additionally have their multiselect tiles filtered, so that
* checkboxes opting in to targeting are resolved before the screen renders.
*
* @param {object[]} screens - An array of screens that will be looped
* through to be evaluated for removal
* @returns {object[]} - A new array containing the screens that were not removed
*/
async evaluateTargetingAndRemoveScreens(screens) {
const filteredScreens = [...screens];
await this.removeScreens(filteredScreens, async screen => {
if (screen.targeting !== undefined) {
const result = await this.evaluateScreenTargeting(screen.targeting);
// A false evaluation means we want to remove the screen.
if (!result) {
return true;
}
}
// Resolve any opt-in multiselect checkbox targeting
//so the correct checkboxes are present on first paint.
await this.filterMultiSelectTargeting(screen);
return false;
});
return filteredScreens;
},
/**
*
* A multiselect tile's checkbox may include a `targeting` JEXL expression to
* conditionally render itself. We do this in the parent process before
* the screen is handed to content so it's evaluated before first paint.
* This is opt-in, a checkbox without `targeting` is always kept. A multiselect tile
* whose checkboxes are all filtered out is removed entirely
*
* @param {object} screen - The screen whose multiselect tiles to filter.
*/
async filterMultiSelectTargeting(screen) {
const tiles = screen?.content?.tiles;
if (!tiles) {
return;
}
const tilesArray = Array.isArray(tiles) ? tiles : [tiles];
for (const tile of tilesArray) {
if (tile?.type !== "multiselect" || !Array.isArray(tile.data)) {
continue;
}
const evaluatedCheckboxes = [];
for (const checkbox of tile.data) {
if (
checkbox?.targeting === undefined ||
(await this.evaluateScreenTargeting(checkbox.targeting))
) {
evaluatedCheckboxes.push(checkbox);
}
}
tile.data = evaluatedCheckboxes;
}
const isEmptyMultiSelect = tile =>
tile?.type === "multiselect" && !tile.data.length;
if (Array.isArray(tiles)) {
screen.content.tiles = tiles.filter(tile => !isEmptyMultiSelect(tile));
} else if (isEmptyMultiSelect(tiles)) {
delete screen.content.tiles;
}
},
async addScreenImpression(screen) {
await lazy.ASRouter.addScreenImpression(screen);
},
/**
* Whether the given screen has already recorded an impression.
*
* @param {string} screenId - The id of the screen to check.
* @returns {boolean}
*/
async hasSeenScreen(screenId) {
return Boolean(lazy.ASRouter.state.screenImpressions?.[screenId]);
},
/**
* Whether a special message action is allowed to fire automatically on screen
* impression. A MULTI_ACTION is allowed only when every nested action is
* itself an allowed action.
*
* @param {object} action - The special message action to validate.
* @returns {boolean}
*/
isAllowedImpressionAction(action) {
const ALLOWED_IMPRESSION_ACTIONS = [
"PIN_FIREFOX_TO_TASKBAR",
"PIN_FIREFOX_TO_START_MENU",
];
if (!action) {
return false;
}
if (action.type === "MULTI_ACTION") {
const actions = action.data?.actions;
return (
Array.isArray(actions) &&
!!actions.length &&
actions.every(nestedAction =>
ALLOWED_IMPRESSION_ACTIONS.includes(nestedAction?.type)
)
);
}
return ALLOWED_IMPRESSION_ACTIONS.includes(action.type);
},
/**
* Handle a special message action fired automatically when a screen is first
* shown, rather than by a button click. Only allowed actions (see
* `isAllowedImpressionAction`) may fire on impression. When the action sets
* `once`, it is skipped if the screen has already been seen.
*
* @param {object} data
* @param {object} data.action - The special message action to run.
* @param {boolean} [data.action.once] - Only fire on the screen's first view.
* @param {string} data.screen_id - The id of the screen firing the action.
* @param {Browser} browser - The xul:browser rendering the page.
* @returns {Promise<boolean>} Whether the action was dispatched. False when
* rejected by the allowlist or suppressed by `once`.
*/
async handleImpressionAction(data, browser) {
const { action, screen_id } = data;
if (!this.isAllowedImpressionAction(action)) {
return false;
}
if (action.once && (await this.hasSeenScreen(screen_id))) {
return false;
}
lazy.SpecialMessageActions.handleAction(
{ type: action.type, data: action.data },
browser
);
return true;
},
};