@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

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.

// 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: "[email protected]", // 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)

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

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

export const Status = () => {
    const {agreementAccepted, permissionsGranted} = usePrivacyPolicy();
    return (
        <div>
            accepted: {String(agreementAccepted)}; granted: {String(permissionsGranted)}
        </div>
    );
};

Modal window

Exports the modal component and its types:

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