@hypexts/plugin-privacy-policy

Privacy Policy plugin for the Addon Bone (adnbn) framework. Provides a consent page, stores consent status, requests optional permissions, and utilities to check/open the policy page.

Features

- Dedicated privacy policy page (page), localization (locale), and a background script.
- Automatically opens the page on install and on update if consent has not been given.
- Stores flags:
- agreementAccepted — the user accepted the policy;
- permissionsGranted — the optional permissions specified in options were granted.
- Requests optional permissions (permissions, hostPermissions) and tracks their changes.
- API and a React hook to integrate with your UI.

Installation

``bash
npm i @hypexts/plugin-privacy-policy


install peer dependencies if needed


npm i adnbn addon-ui react react-dom
`

Wire up in adnbn configuration

Add the plugin to the plugins list and pass options.

`ts
// adnbn.config.ts
import {defineConfig} from "adnbn";
import privacyPolicy from "@hypexts/plugin-privacy-policy";

export default defineConfig({
plugins: [
privacyPolicy({
name: "@app.name", // i18n key of the app name
title: "@privacy_policy.label", // i18n key of the page title
email: "support@example.com", // placeholder {{email}} in markdown
url: "https://example.com/privacy", // base URL to load {lang}.md from
// icon?: "active",
// permissions?: ["downloads", "clipboardWrite"],
// hostPermissions?: ["https://.example.com/"],
// dataCollectionPermissions?: ["browsingActivity"],
}),
],
});
`

Notes:

- The plugin adds the "storage" permission, automatically adds the policy url to hostPermissions, and declares the provided permissions/hostPermissions as optional.
- The dataCollectionPermissions option is specific to Firefox (Gecko) optional data collection permissions. If used, it automatically includes browsingActivity, technicalAndInteraction, and websiteContent.
- The policy markdown is loaded from ${url}/{language}.md (falls back to English on failure). The following placeholders are supported in the text: {{email}}, {{app_name}}.

API (short)

`ts
import {
getPrivacyPolicyPageUrl,
openPrivacyPolicyPage,
getPrivacyPolicyOptions,
isAgreementAccepted,
isPermissionsGranted,
onPrivacyPolicyChanged,
type PrivacyPolicyStorage,
} from "@hypexts/plugin-privacy-policy/api";

// open the policy page in a new/existing tab
await openPrivacyPolicyPage();

// read current states
const accepted = await isAgreementAccepted();
const granted = await isPermissionsGranted();

// subscribe to changes (returns an unsubscribe function)
const unsubscribe = onPrivacyPolicyChanged(state => {
console.log(state.agreementAccepted, state.permissionsGranted);
});
`

React hook

`tsx
import React from "react";
import {usePrivacyPolicy} from "@hypexts/plugin-privacy-policy/hooks";

export const Status = () => {
const {agreementAccepted, permissionsGranted} = usePrivacyPolicy();
return (



);
};
`

Modal window

Exports the modal component and its types:

`ts
import PrivacyModal, {type PrivacyModalProps, type PrivacyModalActions} from "@hypexts/plugin-privacy-policy/modal";
``

Types are available in d.ts. Usage depends on your UI flow.

Localization

The plugin uses the adnbn LocaleProvider. The package ships with keys (examples):

- privacy_policy.loading
- privacy_policy.error_message
- privacy_policy.try_again
- privacy_policy.delete
- privacy_policy.agree
- @privacy_policy.label — page title

You can override/extend translations with your own resources.

License

BUSL-1.1