Skip to content

[ConfigFeature] config feature docs update #1647

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 22, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 17 additions & 3 deletions injected/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,17 +33,31 @@ The exposed API is a global called contentScopeFeatures and has three methods:

These files stored in the features directory must include an init function and optionally update and load explained in the features lifecycle.

### `ConfigFeature` class
The [ConfigFeature](https://github.com/duckduckgo/content-scope-scripts/blob/main/injected/src/config-feature.js) class is extended by each feature to implement remote config handling. It provides the following methods:

`getFeatureSettingEnabled`
- For simple boolean settings, return true if the setting is 'enabled'

`getFeatureSetting`
- Return a specific setting from the feature settings

`recomputeSiteObject`
- Recomputes the site object for the feature, e.g when the URL has changed.

`ConfigFeature` class is also exportable and can be used by other scripts to build C-S-S like features that can handle remote configuration - currently used in [autofill.js](https://github.com/duckduckgo/duckduckgo-autofill/blob/main/src/site-specific-feature.js) to handle site specific autofill rules.

## Features Lifecycle

There are three stages that the content scope code is hooked into the platform:
- load
- `load`
- This should be reserved for work that should happen that could cause a delay in loading the feature.
- Given the current limitations of how we inject our code we don't have the Privacy Remote Configuration exceptions so authors should be wary of actually loading anything that would modify the page (and potentially breaking it).
- This limitation may be re-addressed in manifest v3
- One exception here is the first party cookie protections that are triggered on init to prevent race conditions.
- init
- `init`
- This is the main place that features are actually loaded into the extension.
- update
- `update`
- This allows the feature to be sent updates from the browser.
- If this is triggered before init, these updates will be queued and triggered straight after.

Expand Down
7 changes: 7 additions & 0 deletions injected/src/config-feature.js
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,13 @@ import { immutableJSONPatch } from 'immutable-json-patch';
import { camelcase, computeEnabledFeatures, matchHostname, parseFeatureSettings, computeLimitedSiteObject } from './utils.js';
import { URLPattern } from 'urlpattern-polyfill';

/**
* This class is extended by each feature to implement remote config handling:
* - Parsing the remote config, with conditional logic applied,
* - Providing API for features to check if they are enabled,
* - Providing API for features to get their config.
* - For external scripts, it provides API to update the site object for the feature, e.g when the URL has changed.
*/
export default class ConfigFeature {
/** @type {import('./utils.js').RemoteConfig | undefined} */
#bundledConfig;
Expand Down
Loading