@c15t/scripts 3.0.0-alpha.2 → 3.0.0-alpha.4

package/docs/frameworks/vue/network-blocker.md

@@ -0,0 +1,99 @@
+---
+title: Network blocker
+description: Hold fetch and XMLHttpRequest calls in a Vue app until their
+  consent category is allowed, with rules passed to the c15t Vue plugin.
+group: frameworks
+---
+
+## Add rules
+
+The network blocker stops `fetch` and `XMLHttpRequest` calls that match a
+rule until the rule's category is allowed. Use it as a backstop for tracking
+calls your own code or a vendor SDK makes. Load vendor SDKs through
+[`scripts`](./scripts.md) first, so they do not run at all
+before consent.
+
+Define the rules in their own file:
+
+```ts title="src/network-blocker.ts"
+import type { UseNetworkBlockerOptions } from 'c15t/vue/vue-plugin';
+
+export const networkBlocker = {
+	onRequestBlocked: (info) => {
+		console.info('Blocked until consent', info.method, info.url);
+	},
+	rules: [
+		{ category: 'measurement', domain: 'google-analytics.com' },
+		{
+			category: 'marketing',
+			domain: 'facebook.com',
+			methods: ['POST'],
+			pathIncludes: '/tr',
+		},
+	],
+} satisfies UseNetworkBlockerOptions;
+```
+
+Pass them to the plugin in `src/main.ts`:
+
+```ts title="src/main.ts"
+app.use(c15tVue, {
+	backendURL: 'https://your-project.inth.app',
+	networkBlocker,
+	scripts,
+});
+```
+
+## Match requests with rules
+
+Each rule names a `domain` and the consent `category` a request needs. The
+domain also matches its subdomains, so `google-analytics.com` covers
+`www.google-analytics.com`. `pathIncludes` narrows a rule to paths that
+contain a substring, and `methods` narrows it to HTTP methods. `category`
+also takes conditions such as `{ and: ['measurement', 'marketing'] }`.
+
+Add `vendor` with a vendor ID to also block the request while the visitor has
+turned that vendor off. Rules for IAB TCF vendors use `vendorId` and the
+`iabPurposes` fields instead.
+
+| Option               | Default  | Purpose                                                       |
+| -------------------- | -------- | ------------------------------------------------------------- |
+| `rules`              | Required | The rules above.                                              |
+| `enabled`            | `true`   | `false` keeps the rules but stops blocking.                   |
+| `logBlockedRequests` | `true`   | Logs each blocked request with `console.warn`.                |
+| `onRequestBlocked`   | Unset    | Called with `{ method, url, rule }` for each blocked request. |
+
+## What a blocked request looks like
+
+A blocked `fetch` resolves to a `451` response with the status text
+`Request blocked by consent`, and nothing is sent. A blocked XHR is aborted
+and fires an `error` event. Requests that match no rule are not delayed.
+
+## When blocking starts
+
+The plugin starts holding matching requests when `app.use(c15tVue, ...)`
+runs, before your app mounts. While consent is unknown, a matching request
+waits instead of failing. Once the policy has loaded and the stored choice
+applies, a waiting request is sent if consent allows it and blocked
+otherwise. If the policy fails to load, optional categories stay denied and
+waiting requests are blocked.
+
+## What it cannot stop
+
+The blocker sees only `fetch` and `XMLHttpRequest` calls made after
+`app.use()` runs. It cannot stop:
+
+* Scripts in `index.html` and modules that run before `src/main.ts`.
+* Code that saved its own reference to `fetch` before the plugin installed.
+* `navigator.sendBeacon`, `WebSocket`, `EventSource`, and requests from
+  `<img>`, `<script>` and `<iframe>` elements, web workers and service
+  workers.
+
+Check `useConsent()` before you call a vendor from your own code, and treat
+the blocker as a backstop.
+
+## Verify
+
+Open the Network tab, clear site data and reload. Requests that match a rule
+do not appear until you allow their category, and the console lists each
+blocked request. Reject, reload, and check that they still do not appear.

package/docs/frameworks/vue/scripts.md

@@ -0,0 +1,93 @@
+---
+title: Scripts
+description: Load vendor scripts by consent category in a Vue app with the c15t
+  Vue plugin, and what happens when a visitor withdraws consent.
+group: frameworks
+---
+
+## Register vendor scripts
+
+A banner does not stop a script you load with a `<script>` tag in
+`index.html` or a vendor SDK you initialize yourself. Remove those loaders and
+register the vendor with c15t instead, so c15t loads it only while its
+category is allowed.
+
+Create the script configuration with the helpers from `@c15t/integrations`:
+
+```ts title="src/scripts.ts"
+import { posthog } from '@c15t/integrations/posthog';
+import { xPixel } from '@c15t/integrations/x-pixel';
+
+export const scripts = [
+	posthog({
+		id: 'phc_your_project_key',
+		initOptions: { cookieless_mode: 'never' },
+		loadMode: 'after-consent',
+	}),
+	xPixel({ pixelId: 'your-pixel-id' }),
+];
+```
+
+Pass it to the plugin as `scripts`:
+
+```ts title="src/main.ts"
+import { c15tVue } from 'c15t/vue/vue-plugin';
+import { createApp } from 'vue';
+
+import App from './App.vue';
+import { scripts } from './scripts';
+
+createApp(App)
+	.use(c15tVue, { backendURL: 'https://your-project.inth.app', scripts })
+	.mount('#app');
+```
+
+The plugin starts one script loader when the app mounts, after it has applied
+the visitor's stored choice and privacy signals. Do not also call
+`createScriptLoader` from a component. A component's `onMounted` runs before
+the plugin has read the stored choice, and each script would load twice.
+
+Every vendor guide under [integrations](../../integrations/overview.md) gives the
+helper and options for that vendor.
+
+## Embeds and other requests
+
+Scripts cover vendor code c15t loads for you. For the rest:
+
+* [Embeds](./embeds.md) gates iframes with `ConsentGate` or
+  the iframe blocker.
+* [Network blocker](./network-blocker.md) holds `fetch` and
+  XHR calls that match a rule until their category is allowed.
+
+## When a visitor withdraws consent
+
+Removing a script tag cannot stop code that already ran. When a save turns off
+a category or vendor that was allowed, c15t reloads the page so the new
+document starts with only permitted code. Set `reloadOnConsentRevoked: false`
+to handle revocation yourself, or use the
+[`onBeforeConsentRevocationReload` callback](https://c15t.com/docs/frameworks/vue/callbacks#before-a-revocation-reload)
+to run code before the reload.
+
+`clearOnRevocation` deletes first-party cookies and storage keys that belong to
+a category when it is withdrawn. See
+[clear on revocation](https://c15t.com/docs/frameworks/vue/clear-on-revocation).
+
+## Let visitors turn off one vendor
+
+A visitor can allow marketing and still switch off one vendor in it. Declare
+the vendors in the `vendors` option; helpers from `@c15t/integrations` already carry
+their vendor slug. See [vendor consent](https://c15t.com/docs/frameworks/vue/vendor-consent).
+
+## Content Security Policy
+
+Allow each vendor's script host in `script-src`. The plugin's `nonce` option
+adds a nonce to every script the loader creates. See
+[Content Security Policy](https://c15t.com/docs/frameworks/vue/content-security-policy).
+
+## Verify gating
+
+In a private window, open the Network tab and load the app under a policy that
+asks for consent. Requests to your vendors are absent.
+Allow one category and save, and only that category's vendors load. Withdraw
+it, and the page reloads without loading the vendor again.
+[Verify consent](../../guides/verify-consent.md) has the full checklist.