@graffico/legal 0.3.12 → 0.3.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +374 -359
- package/dist/index.d.ts +78 -17
- package/dist/index.js +2 -2
- package/dist/next.d.cts +5 -1
- package/dist/next.d.ts +5 -1
- package/dist/server.d.ts +19 -4
- package/dist/server.js +1 -1
- package/package.json +78 -78
package/README.md
CHANGED
|
@@ -1,359 +1,374 @@
|
|
|
1
|
-
# @graffico/legal
|
|
2
|
-
|
|
3
|
-
CMP GDPR drop-in per React / Next.js. Banner + modale, policy server-rendered, **tracker terzi che caricano solo dopo consenso**, plugin Next.js per security headers.
|
|
4
|
-
|
|
5
|
-
```bash
|
|
6
|
-
pnpm add @graffico/legal
|
|
7
|
-
```
|
|
8
|
-
|
|
9
|
-
---
|
|
10
|
-
|
|
11
|
-
## 1. Setup minimo
|
|
12
|
-
|
|
13
|
-
`src/config/legal.ts`:
|
|
14
|
-
|
|
15
|
-
```ts
|
|
16
|
-
import type { CompanyConfig } from "@graffico/legal";
|
|
17
|
-
|
|
18
|
-
export const legalConfig: CompanyConfig = {
|
|
19
|
-
name: "Mia Azienda",
|
|
20
|
-
domain: "azienda.it",
|
|
21
|
-
owners: "Mario Rossi",
|
|
22
|
-
addresses: "Via Roma 1, Milano",
|
|
23
|
-
vatNumbers: "01234567890",
|
|
24
|
-
email: "privacy@azienda.it",
|
|
25
|
-
policyVersion: "2026.05", // cambiarla invalida i consensi vecchi
|
|
26
|
-
services: ["google-analytics", "facebook-pixel", "contact-form"],
|
|
27
|
-
primaryColor: "#2c5282",
|
|
28
|
-
language: "it",
|
|
29
|
-
};
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
`app/layout.tsx`:
|
|
33
|
-
|
|
34
|
-
```tsx
|
|
35
|
-
import { LegalProvider } from "@graffico/legal/server";
|
|
36
|
-
import { legalConfig } from "@/config/legal";
|
|
37
|
-
|
|
38
|
-
export default function RootLayout({ children }) {
|
|
39
|
-
return (
|
|
40
|
-
<html>
|
|
41
|
-
<body>
|
|
42
|
-
<LegalProvider config={legalConfig}>{children}</LegalProvider>
|
|
43
|
-
</body>
|
|
44
|
-
</html>
|
|
45
|
-
);
|
|
46
|
-
}
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
`<LegalProvider>` monta automaticamente banner + modale + floating toggle.
|
|
50
|
-
|
|
51
|
-
### Tailwind / globals.css
|
|
52
|
-
|
|
53
|
-
La libreria usa Tailwind utility classes inline (niente CSS bundle). Devi dire al JIT di Tailwind di scansionare i file della libreria, altrimenti banner e modale appariranno senza stili.
|
|
54
|
-
|
|
55
|
-
**Tailwind v4** — aggiungi una direttiva `@source` in `src/app/globals.css` (o equivalente):
|
|
56
|
-
|
|
57
|
-
```css
|
|
58
|
-
@import "tailwindcss";
|
|
59
|
-
@source "../../node_modules/@graffico/legal/dist/**/*.{js,cjs}";
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
> Il path `../../` parte da `src/app/`. Se il tuo `globals.css` sta altrove, regola la profondità relativa. In monorepo con workspace, il dist è raggiungibile via `node_modules` simlink.
|
|
63
|
-
|
|
64
|
-
**Tailwind v3** — aggiungi al `tailwind.config.js`:
|
|
65
|
-
|
|
66
|
-
```js
|
|
67
|
-
module.exports = {
|
|
68
|
-
content: [
|
|
69
|
-
"./src/**/*.{js,ts,jsx,tsx}",
|
|
70
|
-
"./node_modules/@graffico/legal/dist/**/*.{js,cjs}",
|
|
71
|
-
],
|
|
72
|
-
};
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
---
|
|
76
|
-
|
|
77
|
-
## 2. Tracker — drop-in con consenso integrato
|
|
78
|
-
|
|
79
|
-
Importi il componente Legal, passi le API key. Lo script parte **solo dopo consenso**.
|
|
80
|
-
|
|
81
|
-
```tsx
|
|
82
|
-
import {
|
|
83
|
-
ConsentModeBoot,
|
|
84
|
-
GoogleAnalyticsLegal,
|
|
85
|
-
GoogleAdsLegal,
|
|
86
|
-
MetaPixelLegal,
|
|
87
|
-
HotjarLegal,
|
|
88
|
-
GTMLegal,
|
|
89
|
-
EmailJSLegal,
|
|
90
|
-
} from "@graffico/legal";
|
|
91
|
-
|
|
92
|
-
<LegalProvider config={legalConfig}>
|
|
93
|
-
<ConsentModeBoot /> {/* Google Consent Mode v2 default = denied */}
|
|
94
|
-
<GoogleAnalyticsLegal gaId="G-XXXX" />
|
|
95
|
-
<GoogleAdsLegal
|
|
96
|
-
conversionId="AW-XXXX"
|
|
97
|
-
conversions={{ formSubmit: { sendTo: "AW-XXXX/abc", value: 1, currency: "EUR" } }}
|
|
98
|
-
/>
|
|
99
|
-
<MetaPixelLegal pixelId="123456" events={["Lead", "Contact"]} />
|
|
100
|
-
<HotjarLegal siteId={1234567} />
|
|
101
|
-
<EmailJSLegal
|
|
102
|
-
serviceId={process.env.NEXT_PUBLIC_EMAILJS_SERVICE_ID!}
|
|
103
|
-
templateId={process.env.NEXT_PUBLIC_EMAILJS_TEMPLATE_ID!}
|
|
104
|
-
publicKey={process.env.NEXT_PUBLIC_EMAILJS_USER_ID!}
|
|
105
|
-
/>
|
|
106
|
-
{children}
|
|
107
|
-
</LegalProvider>
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
| Componente | Categoria default | Script gated | Note |
|
|
111
|
-
|---|---|---|---|
|
|
112
|
-
| `ConsentModeBoot` | — | — | Boot gtag stub + Consent Mode v2. **Sempre per primo.** |
|
|
113
|
-
| `GoogleAnalyticsLegal` | `statistical` | `gtag/js?id=G-…` | Anonymize IP on di default. |
|
|
114
|
-
| `GoogleAdsLegal` | `marketing` | `gtag/js?id=AW-…` | Mappa conversioni dichiarativa. |
|
|
115
|
-
| `MetaPixelLegal` | `marketing` | `fbevents.js` | Whitelist `events` opzionale. Su revoca → `fbq('consent','revoke')`. |
|
|
116
|
-
| `HotjarLegal` | `statistical` | `static.hotjar.com/c/hotjar-…` | Session recording + heatmap. |
|
|
117
|
-
| `GTMLegal` | `marketing` | `gtm.js?id=GTM-…` | Lascia ai tag interni la granularità. |
|
|
118
|
-
| `EmailJSLegal` | — (art. 6.1.b) | — | Config holder per `useEmailJS()`. |
|
|
119
|
-
|
|
120
|
-
---
|
|
121
|
-
|
|
122
|
-
## 3. Hook trigger eventi
|
|
123
|
-
|
|
124
|
-
Nei tuoi componenti `"use client"`:
|
|
125
|
-
|
|
126
|
-
```tsx
|
|
127
|
-
import { useGAEvent, useMetaEvent, useAdsConversion, useHotjarEvent } from "@graffico/legal";
|
|
128
|
-
|
|
129
|
-
const trackGA = useGAEvent();
|
|
130
|
-
const trackLead = useMetaEvent("Lead");
|
|
131
|
-
const fireConversion = useAdsConversion("formSubmit");
|
|
132
|
-
const trackHj = useHotjarEvent();
|
|
133
|
-
|
|
134
|
-
// Tutti diventano no-op senza consenso — chiama liberamente
|
|
135
|
-
trackGA("button_click", { id: "hero" });
|
|
136
|
-
trackLead({ value: 99, currency: "EUR" });
|
|
137
|
-
fireConversion();
|
|
138
|
-
trackHj("scroll_to_pricing");
|
|
139
|
-
```
|
|
140
|
-
|
|
141
|
-
---
|
|
142
|
-
|
|
143
|
-
## 4. Form contatto con consenso
|
|
144
|
-
|
|
145
|
-
```tsx
|
|
146
|
-
"use client";
|
|
147
|
-
import { useEmailJS, ConsentCheckbox } from "@graffico/legal";
|
|
148
|
-
|
|
149
|
-
export function ContactForm() {
|
|
150
|
-
const { send, status } = useEmailJS();
|
|
151
|
-
|
|
152
|
-
async function onSubmit(e: React.FormEvent<HTMLFormElement>) {
|
|
153
|
-
e.preventDefault();
|
|
154
|
-
const res = await send(e.currentTarget);
|
|
155
|
-
if (!res.ok) console.warn(res.error); // CONSENT_MISSING | CONFIG_MISSING | SEND_FAILED
|
|
156
|
-
}
|
|
157
|
-
|
|
158
|
-
return (
|
|
159
|
-
<form onSubmit={onSubmit}>
|
|
160
|
-
<input name="name" required />
|
|
161
|
-
<input name="email" type="email" required />
|
|
162
|
-
<textarea name="message" required />
|
|
163
|
-
<ConsentCheckbox /> {/* obbligatorio: blocca submit se non spuntato */}
|
|
164
|
-
<button disabled={status === "loading"}>Invia</button>
|
|
165
|
-
</form>
|
|
166
|
-
);
|
|
167
|
-
}
|
|
168
|
-
```
|
|
169
|
-
|
|
170
|
-
`send()` inietta automaticamente nel payload mail: `_consentId`, `_consentTimestamp`, `_policyVersion` (
|
|
171
|
-
|
|
172
|
-
---
|
|
173
|
-
|
|
174
|
-
## 5. Pagine policy
|
|
175
|
-
|
|
176
|
-
Auto-renderizzate dalla config — incluse sezioni Processors / Transfers / Retention / DPO se valorizzati.
|
|
177
|
-
|
|
178
|
-
```tsx
|
|
179
|
-
// app/privacy-policy/page.tsx
|
|
180
|
-
import { PrivacyPolicy } from "@graffico/legal/server";
|
|
181
|
-
import { legalConfig } from "@/config/legal";
|
|
182
|
-
export default () => <PrivacyPolicy config={legalConfig} />;
|
|
183
|
-
|
|
184
|
-
// app/cookie-policy/page.tsx
|
|
185
|
-
import { CookiePolicy } from "@graffico/legal/server";
|
|
186
|
-
export default () => <CookiePolicy config={legalConfig} />;
|
|
187
|
-
```
|
|
188
|
-
|
|
189
|
-
---
|
|
190
|
-
|
|
191
|
-
## 6. Gate per embed terzi
|
|
192
|
-
|
|
193
|
-
```tsx
|
|
194
|
-
import { ConsentGate, useConsentCategory } from "@graffico/legal";
|
|
195
|
-
|
|
196
|
-
<ConsentGate
|
|
197
|
-
category="
|
|
198
|
-
fallback={<p>Abilita
|
|
199
|
-
>
|
|
200
|
-
<iframe src="https://youtube.com/embed/…" />
|
|
201
|
-
</ConsentGate>
|
|
202
|
-
```
|
|
203
|
-
|
|
204
|
-
---
|
|
205
|
-
|
|
206
|
-
## 7. Next.js plugin — security headers
|
|
207
|
-
|
|
208
|
-
CSP derivata dai `services[]` + `processors[]`. HSTS, X-Frame, Permissions-Policy, COOP, Referrer-Policy.
|
|
209
|
-
|
|
210
|
-
```ts
|
|
211
|
-
// next.config.ts
|
|
212
|
-
import { withLegal } from "@graffico/legal/next";
|
|
213
|
-
import { legalConfig } from "@/config/legal";
|
|
214
|
-
|
|
215
|
-
const nextConfig = { /* … */ };
|
|
216
|
-
|
|
217
|
-
export default withLegal(nextConfig, legalConfig, {
|
|
218
|
-
cspReportOnly: process.env.CSP_ENFORCE !== "1", // rollout: 7gg report-only → enforce
|
|
219
|
-
});
|
|
220
|
-
```
|
|
221
|
-
|
|
222
|
-
Per `netlify.toml`:
|
|
223
|
-
|
|
224
|
-
```ts
|
|
225
|
-
import { emitNetlifyHeaders } from "@graffico/legal/next";
|
|
226
|
-
console.log(emitNetlifyHeaders(legalConfig));
|
|
227
|
-
```
|
|
228
|
-
|
|
229
|
-
---
|
|
230
|
-
|
|
231
|
-
## 8. `CompanyConfig`
|
|
232
|
-
|
|
233
|
-
```ts
|
|
234
|
-
interface CompanyConfig {
|
|
235
|
-
name: string;
|
|
236
|
-
domain: string;
|
|
237
|
-
owners: string;
|
|
238
|
-
addresses: string | string[];
|
|
239
|
-
vatNumbers: string | string[];
|
|
240
|
-
email: string;
|
|
241
|
-
|
|
242
|
-
policyVersion?: string; // cambiarla invalida i consensi pregressi
|
|
243
|
-
lastUpdated?: string; // ISO date, default oggi
|
|
244
|
-
|
|
245
|
-
services?: ServiceReference[]; // tracker dichiarati (preset id o oggetto), guidano anche il testo del banner
|
|
246
|
-
processors?: Processor[]; // destinatari/responsabili esterni
|
|
247
|
-
retention?: RetentionMap; // tempi di conservazione per categoria
|
|
248
|
-
dpo?: DpoInfo; // se nominato (art. 37 GDPR)
|
|
249
|
-
|
|
250
|
-
theme?: "light" | "dark";
|
|
251
|
-
primaryColor?: string;
|
|
252
|
-
language?: "it" | "en";
|
|
253
|
-
togglePosition?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
|
|
254
|
-
}
|
|
255
|
-
|
|
256
|
-
interface Processor {
|
|
257
|
-
name: string;
|
|
258
|
-
purpose: string;
|
|
259
|
-
country: string;
|
|
260
|
-
transferBasis?: string; // "DPF + SCC 2021/914", "SCC", …
|
|
261
|
-
privacyUrl?: string;
|
|
262
|
-
}
|
|
263
|
-
|
|
264
|
-
interface RetentionMap {
|
|
265
|
-
contactForms?: string; // "90d"
|
|
266
|
-
analytics?: string; // "14m"
|
|
267
|
-
marketing?: string; // "2y"
|
|
268
|
-
[k: string]: string | undefined;
|
|
269
|
-
}
|
|
270
|
-
|
|
271
|
-
interface DpoInfo {
|
|
272
|
-
name: string;
|
|
273
|
-
email: string;
|
|
274
|
-
phone?: string;
|
|
275
|
-
}
|
|
276
|
-
```
|
|
277
|
-
|
|
278
|
-
---
|
|
279
|
-
|
|
280
|
-
## 9. Conformità GDPR / ePrivacy — cosa fa già la lib
|
|
281
|
-
|
|
282
|
-
- **TTL consenso 180 giorni** (`CONSENT_TTL_MS`), allineato al Garante 10/06/2021. Scaduto → re-prompt.
|
|
283
|
-
- **Re-prompt automatico** al cambio `policyVersion`.
|
|
284
|
-
- **Auto-decline su GPC / DNT** (`navigator.globalPrivacyControl`, `Sec-GPC`) senza UI.
|
|
285
|
-
- **
|
|
286
|
-
- **Parità grafica reject/accept** nel banner (Garante 10/06/2021 §4).
|
|
287
|
-
- **Categorie indipendenti**: `necessary` / `statistical` / `marketing`. Default OFF.
|
|
288
|
-
- **Finalità reali nel banner e nella cookie policy**: citano misurazione e/o marketing e profilazione solo se in uso, dedotti da `services[]` e dai tracker `*Legal` / `ConsentGate` montati. Senza `services[]` resta il testo generico (misurazione).
|
|
289
|
-
- **Modale accessibile** (WCAG 2.1 livello A): dialog con focus gestito, Tab confinato, `Esc` chiude senza salvare, interruttori `role="switch"` usabili da tastiera.
|
|
290
|
-
- **Niente cookie wall**: il sito resta fruibile senza consenso.
|
|
291
|
-
- **Zero telemetria** della libreria stessa.
|
|
292
|
-
|
|
293
|
-
---
|
|
294
|
-
|
|
295
|
-
## 10. Service preset (id stringa per `services[]`)
|
|
296
|
-
|
|
297
|
-
| Categoria | Id |
|
|
298
|
-
|---|---|
|
|
299
|
-
| Analytics | `google-analytics`, `microsoft-clarity`, `hotjar` |
|
|
300
|
-
| Marketing | `facebook-pixel`, `google-ads`, `linkedin-insight`, `tiktok-pixel` |
|
|
301
|
-
| Tag manager | `google-tag-manager` |
|
|
302
|
-
| Pagamenti | `stripe`, `paypal` |
|
|
303
|
-
| Contenuti | `youtube`, `google-maps`, `google-fonts` |
|
|
304
|
-
| Form / mail | `contact-form`, `mailchimp`, `newsletter` |
|
|
305
|
-
|
|
306
|
-
Servizio inline custom:
|
|
307
|
-
|
|
308
|
-
```ts
|
|
309
|
-
{
|
|
310
|
-
id: "crm",
|
|
311
|
-
name: "CRM Interno",
|
|
312
|
-
category: "provided", // "automatic" | "provided" | "marketing"
|
|
313
|
-
consentCategory: "necessary", // "necessary" | "statistical" | "marketing"
|
|
314
|
-
purposes: ["Gestione clienti"],
|
|
315
|
-
dataCollected: ["Email", "Nome"],
|
|
316
|
-
}
|
|
317
|
-
```
|
|
318
|
-
|
|
319
|
-
`consentCategory` è la categoria del banner che abilita il servizio e decide quali finalità citano banner e cookie policy (`necessary` = nessun consenso da banner). Se manca viene dedotta da `cookies[].type` e `lawfulBasis`; se non è deducibile il banner resta sul testo generico.
|
|
320
|
-
|
|
321
|
-
`google-tag-manager` è `marketing` perché `GTMLegal` parte col consenso marketing. Se il container carica solo statistiche:
|
|
322
|
-
|
|
323
|
-
```tsx
|
|
324
|
-
services: [{ ...SERVICE_PRESETS["google-tag-manager"], consentCategory: "statistical" }]
|
|
325
|
-
<GTMLegal containerId="GTM-XXXX" category="statistical" />
|
|
326
|
-
```
|
|
327
|
-
|
|
328
|
-
---
|
|
329
|
-
|
|
330
|
-
## 11. API export
|
|
331
|
-
|
|
332
|
-
**`@graffico/legal/server`** — `LegalProvider`, `PrivacyPolicy`, `CookiePolicy`.
|
|
333
|
-
|
|
334
|
-
**`@graffico/legal`** (client) —
|
|
335
|
-
- Tracker: `ConsentModeBoot`, `GoogleAnalyticsLegal`, `GoogleAdsLegal`, `MetaPixelLegal`, `HotjarLegal`, `GTMLegal`, `EmailJSLegal`
|
|
336
|
-
- Hook: `useConsent`, `useConsentCategory`, `useIsHydrated`, `useGAEvent`, `useAdsConversion`, `useMetaEvent`, `useHotjarEvent`, `useHotjarIdentify`, `useEmailJS`, `useT`, `useLegalLanguage`
|
|
337
|
-
- UI: `ConsentBanner`, `PreferenceModal`, `FloatingConsentToggle`, `ConsentGate`, `ConsentCheckbox`, `ServiceGrid`
|
|
338
|
-
- Azioni: `acceptAll`, `declineAll`, `savePreferences`, `resetConsent`, `setModalOpen`, `setLanguage`
|
|
339
|
-
- Primitive: `subscribeConsent`, `getConsentSnapshot`, `CONSENT_TTL_MS`, `SERVICE_PRESETS`
|
|
340
|
-
|
|
341
|
-
**`@graffico/legal/next`** — `withLegal`, `emitNetlifyHeaders`, `buildLegalHeaders`, `buildCspFromConfig`.
|
|
342
|
-
|
|
343
|
-
---
|
|
344
|
-
|
|
345
|
-
## Aggiornare
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
-
|
|
354
|
-
-
|
|
355
|
-
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
1
|
+
# @graffico/legal
|
|
2
|
+
|
|
3
|
+
CMP GDPR drop-in per React / Next.js. Banner + modale, policy server-rendered, **tracker terzi che caricano solo dopo consenso**, plugin Next.js per security headers.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
pnpm add @graffico/legal
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## 1. Setup minimo
|
|
12
|
+
|
|
13
|
+
`src/config/legal.ts`:
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import type { CompanyConfig } from "@graffico/legal";
|
|
17
|
+
|
|
18
|
+
export const legalConfig: CompanyConfig = {
|
|
19
|
+
name: "Mia Azienda",
|
|
20
|
+
domain: "azienda.it",
|
|
21
|
+
owners: "Mario Rossi",
|
|
22
|
+
addresses: "Via Roma 1, Milano",
|
|
23
|
+
vatNumbers: "01234567890",
|
|
24
|
+
email: "privacy@azienda.it",
|
|
25
|
+
policyVersion: "2026.05", // cambiarla invalida i consensi vecchi
|
|
26
|
+
services: ["google-analytics", "facebook-pixel", "contact-form"],
|
|
27
|
+
primaryColor: "#2c5282",
|
|
28
|
+
language: "it",
|
|
29
|
+
};
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
`app/layout.tsx`:
|
|
33
|
+
|
|
34
|
+
```tsx
|
|
35
|
+
import { LegalProvider } from "@graffico/legal/server";
|
|
36
|
+
import { legalConfig } from "@/config/legal";
|
|
37
|
+
|
|
38
|
+
export default function RootLayout({ children }) {
|
|
39
|
+
return (
|
|
40
|
+
<html>
|
|
41
|
+
<body>
|
|
42
|
+
<LegalProvider config={legalConfig}>{children}</LegalProvider>
|
|
43
|
+
</body>
|
|
44
|
+
</html>
|
|
45
|
+
);
|
|
46
|
+
}
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
`<LegalProvider>` monta automaticamente banner + modale + floating toggle.
|
|
50
|
+
|
|
51
|
+
### Tailwind / globals.css
|
|
52
|
+
|
|
53
|
+
La libreria usa Tailwind utility classes inline (niente CSS bundle). Devi dire al JIT di Tailwind di scansionare i file della libreria, altrimenti banner e modale appariranno senza stili.
|
|
54
|
+
|
|
55
|
+
**Tailwind v4** — aggiungi una direttiva `@source` in `src/app/globals.css` (o equivalente):
|
|
56
|
+
|
|
57
|
+
```css
|
|
58
|
+
@import "tailwindcss";
|
|
59
|
+
@source "../../node_modules/@graffico/legal/dist/**/*.{js,cjs}";
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
> Il path `../../` parte da `src/app/`. Se il tuo `globals.css` sta altrove, regola la profondità relativa. In monorepo con workspace, il dist è raggiungibile via `node_modules` simlink.
|
|
63
|
+
|
|
64
|
+
**Tailwind v3** — aggiungi al `tailwind.config.js`:
|
|
65
|
+
|
|
66
|
+
```js
|
|
67
|
+
module.exports = {
|
|
68
|
+
content: [
|
|
69
|
+
"./src/**/*.{js,ts,jsx,tsx}",
|
|
70
|
+
"./node_modules/@graffico/legal/dist/**/*.{js,cjs}",
|
|
71
|
+
],
|
|
72
|
+
};
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## 2. Tracker — drop-in con consenso integrato
|
|
78
|
+
|
|
79
|
+
Importi il componente Legal, passi le API key. Lo script parte **solo dopo consenso**.
|
|
80
|
+
|
|
81
|
+
```tsx
|
|
82
|
+
import {
|
|
83
|
+
ConsentModeBoot,
|
|
84
|
+
GoogleAnalyticsLegal,
|
|
85
|
+
GoogleAdsLegal,
|
|
86
|
+
MetaPixelLegal,
|
|
87
|
+
HotjarLegal,
|
|
88
|
+
GTMLegal,
|
|
89
|
+
EmailJSLegal,
|
|
90
|
+
} from "@graffico/legal";
|
|
91
|
+
|
|
92
|
+
<LegalProvider config={legalConfig}>
|
|
93
|
+
<ConsentModeBoot /> {/* Google Consent Mode v2 default = denied */}
|
|
94
|
+
<GoogleAnalyticsLegal gaId="G-XXXX" />
|
|
95
|
+
<GoogleAdsLegal
|
|
96
|
+
conversionId="AW-XXXX"
|
|
97
|
+
conversions={{ formSubmit: { sendTo: "AW-XXXX/abc", value: 1, currency: "EUR" } }}
|
|
98
|
+
/>
|
|
99
|
+
<MetaPixelLegal pixelId="123456" events={["Lead", "Contact"]} />
|
|
100
|
+
<HotjarLegal siteId={1234567} />
|
|
101
|
+
<EmailJSLegal
|
|
102
|
+
serviceId={process.env.NEXT_PUBLIC_EMAILJS_SERVICE_ID!}
|
|
103
|
+
templateId={process.env.NEXT_PUBLIC_EMAILJS_TEMPLATE_ID!}
|
|
104
|
+
publicKey={process.env.NEXT_PUBLIC_EMAILJS_USER_ID!}
|
|
105
|
+
/>
|
|
106
|
+
{children}
|
|
107
|
+
</LegalProvider>
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
| Componente | Categoria default | Script gated | Note |
|
|
111
|
+
|---|---|---|---|
|
|
112
|
+
| `ConsentModeBoot` | — | — | Boot gtag stub + Consent Mode v2. **Sempre per primo.** |
|
|
113
|
+
| `GoogleAnalyticsLegal` | `statistical` | `gtag/js?id=G-…` | Anonymize IP on di default. |
|
|
114
|
+
| `GoogleAdsLegal` | `marketing` | `gtag/js?id=AW-…` | Mappa conversioni dichiarativa. |
|
|
115
|
+
| `MetaPixelLegal` | `marketing` | `fbevents.js` | Whitelist `events` opzionale. Su revoca → `fbq('consent','revoke')`. |
|
|
116
|
+
| `HotjarLegal` | `statistical` | `static.hotjar.com/c/hotjar-…` | Session recording + heatmap. |
|
|
117
|
+
| `GTMLegal` | `marketing` | `gtm.js?id=GTM-…` | Lascia ai tag interni la granularità. |
|
|
118
|
+
| `EmailJSLegal` | — (art. 6.1.b) | — | Config holder per `useEmailJS()`. |
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## 3. Hook trigger eventi
|
|
123
|
+
|
|
124
|
+
Nei tuoi componenti `"use client"`:
|
|
125
|
+
|
|
126
|
+
```tsx
|
|
127
|
+
import { useGAEvent, useMetaEvent, useAdsConversion, useHotjarEvent } from "@graffico/legal";
|
|
128
|
+
|
|
129
|
+
const trackGA = useGAEvent();
|
|
130
|
+
const trackLead = useMetaEvent("Lead");
|
|
131
|
+
const fireConversion = useAdsConversion("formSubmit");
|
|
132
|
+
const trackHj = useHotjarEvent();
|
|
133
|
+
|
|
134
|
+
// Tutti diventano no-op senza consenso — chiama liberamente
|
|
135
|
+
trackGA("button_click", { id: "hero" });
|
|
136
|
+
trackLead({ value: 99, currency: "EUR" });
|
|
137
|
+
fireConversion();
|
|
138
|
+
trackHj("scroll_to_pricing");
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
---
|
|
142
|
+
|
|
143
|
+
## 4. Form contatto con consenso
|
|
144
|
+
|
|
145
|
+
```tsx
|
|
146
|
+
"use client";
|
|
147
|
+
import { useEmailJS, ConsentCheckbox } from "@graffico/legal";
|
|
148
|
+
|
|
149
|
+
export function ContactForm() {
|
|
150
|
+
const { send, status } = useEmailJS();
|
|
151
|
+
|
|
152
|
+
async function onSubmit(e: React.FormEvent<HTMLFormElement>) {
|
|
153
|
+
e.preventDefault();
|
|
154
|
+
const res = await send(e.currentTarget);
|
|
155
|
+
if (!res.ok) console.warn(res.error); // CONSENT_MISSING | CONFIG_MISSING | SEND_FAILED
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
return (
|
|
159
|
+
<form onSubmit={onSubmit}>
|
|
160
|
+
<input name="name" required />
|
|
161
|
+
<input name="email" type="email" required />
|
|
162
|
+
<textarea name="message" required />
|
|
163
|
+
<ConsentCheckbox /> {/* obbligatorio: blocca submit se non spuntato */}
|
|
164
|
+
<button disabled={status === "loading"}>Invia</button>
|
|
165
|
+
</form>
|
|
166
|
+
);
|
|
167
|
+
}
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
`send()` inietta automaticamente nel payload mail: `_consentId`, `_consentTimestamp`, `_policyVersion` (riferimenti della scelta cookie art. 7.1).
|
|
171
|
+
|
|
172
|
+
---
|
|
173
|
+
|
|
174
|
+
## 5. Pagine policy
|
|
175
|
+
|
|
176
|
+
Auto-renderizzate dalla config — incluse sezioni Processors / Transfers / Retention / DPO se valorizzati.
|
|
177
|
+
|
|
178
|
+
```tsx
|
|
179
|
+
// app/privacy-policy/page.tsx
|
|
180
|
+
import { PrivacyPolicy } from "@graffico/legal/server";
|
|
181
|
+
import { legalConfig } from "@/config/legal";
|
|
182
|
+
export default () => <PrivacyPolicy config={legalConfig} />;
|
|
183
|
+
|
|
184
|
+
// app/cookie-policy/page.tsx
|
|
185
|
+
import { CookiePolicy } from "@graffico/legal/server";
|
|
186
|
+
export default () => <CookiePolicy config={legalConfig} />;
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
---
|
|
190
|
+
|
|
191
|
+
## 6. Gate per embed terzi
|
|
192
|
+
|
|
193
|
+
```tsx
|
|
194
|
+
import { ConsentGate, useConsentCategory } from "@graffico/legal";
|
|
195
|
+
|
|
196
|
+
<ConsentGate
|
|
197
|
+
category="externalContent"
|
|
198
|
+
fallback={<p>Abilita i contenuti esterni per vedere il video.</p>}
|
|
199
|
+
>
|
|
200
|
+
<iframe src="https://youtube.com/embed/…" />
|
|
201
|
+
</ConsentGate>
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
---
|
|
205
|
+
|
|
206
|
+
## 7. Next.js plugin — security headers
|
|
207
|
+
|
|
208
|
+
CSP derivata dai `services[]` + `processors[]`. HSTS, X-Frame, Permissions-Policy, COOP, Referrer-Policy.
|
|
209
|
+
|
|
210
|
+
```ts
|
|
211
|
+
// next.config.ts
|
|
212
|
+
import { withLegal } from "@graffico/legal/next";
|
|
213
|
+
import { legalConfig } from "@/config/legal";
|
|
214
|
+
|
|
215
|
+
const nextConfig = { /* … */ };
|
|
216
|
+
|
|
217
|
+
export default withLegal(nextConfig, legalConfig, {
|
|
218
|
+
cspReportOnly: process.env.CSP_ENFORCE !== "1", // rollout: 7gg report-only → enforce
|
|
219
|
+
});
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
Per `netlify.toml`:
|
|
223
|
+
|
|
224
|
+
```ts
|
|
225
|
+
import { emitNetlifyHeaders } from "@graffico/legal/next";
|
|
226
|
+
console.log(emitNetlifyHeaders(legalConfig));
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
---
|
|
230
|
+
|
|
231
|
+
## 8. `CompanyConfig`
|
|
232
|
+
|
|
233
|
+
```ts
|
|
234
|
+
interface CompanyConfig {
|
|
235
|
+
name: string;
|
|
236
|
+
domain: string;
|
|
237
|
+
owners: string;
|
|
238
|
+
addresses: string | string[];
|
|
239
|
+
vatNumbers: string | string[];
|
|
240
|
+
email: string;
|
|
241
|
+
|
|
242
|
+
policyVersion?: string; // cambiarla invalida i consensi pregressi
|
|
243
|
+
lastUpdated?: string; // ISO date, default oggi
|
|
244
|
+
|
|
245
|
+
services?: ServiceReference[]; // tracker dichiarati (preset id o oggetto), guidano anche il testo del banner
|
|
246
|
+
processors?: Processor[]; // destinatari/responsabili esterni
|
|
247
|
+
retention?: RetentionMap; // tempi di conservazione per categoria
|
|
248
|
+
dpo?: DpoInfo; // se nominato (art. 37 GDPR)
|
|
249
|
+
|
|
250
|
+
theme?: "light" | "dark";
|
|
251
|
+
primaryColor?: string;
|
|
252
|
+
language?: "it" | "en";
|
|
253
|
+
togglePosition?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
interface Processor {
|
|
257
|
+
name: string;
|
|
258
|
+
purpose: string;
|
|
259
|
+
country: string;
|
|
260
|
+
transferBasis?: string; // "DPF + SCC 2021/914", "SCC", …
|
|
261
|
+
privacyUrl?: string;
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
interface RetentionMap {
|
|
265
|
+
contactForms?: string; // "90d"
|
|
266
|
+
analytics?: string; // "14m"
|
|
267
|
+
marketing?: string; // "2y"
|
|
268
|
+
[k: string]: string | undefined;
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
interface DpoInfo {
|
|
272
|
+
name: string;
|
|
273
|
+
email: string;
|
|
274
|
+
phone?: string;
|
|
275
|
+
}
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
---
|
|
279
|
+
|
|
280
|
+
## 9. Conformità GDPR / ePrivacy — cosa fa già la lib
|
|
281
|
+
|
|
282
|
+
- **TTL consenso 180 giorni** (`CONSENT_TTL_MS`), allineato al Garante 10/06/2021. Scaduto → re-prompt.
|
|
283
|
+
- **Re-prompt automatico** al cambio `policyVersion`.
|
|
284
|
+
- **Auto-decline su GPC / DNT** (`navigator.globalPrivacyControl`, `Sec-GPC`) senza UI.
|
|
285
|
+
- **Registrazione della scelta**: `consentId` UUID + `timestamp` ISO + `policyVersion` + `source`, salvati solo nel browser dell'utente e inviati nel payload mail. Registrano la scelta (Garante 10/06/2021, par. 7.1), ma non sono un archivio del Titolare.
|
|
286
|
+
- **Parità grafica reject/accept** nel banner (Garante 10/06/2021 §4).
|
|
287
|
+
- **Categorie indipendenti**: `necessary` / `statistical` / `marketing`. Default OFF.
|
|
288
|
+
- **Finalità reali nel banner e nella cookie policy**: citano misurazione e/o marketing e profilazione solo se in uso, dedotti da `services[]` e dai tracker `*Legal` / `ConsentGate` montati. Senza `services[]` resta il testo generico (misurazione).
|
|
289
|
+
- **Modale accessibile** (WCAG 2.1 livello A): dialog con focus gestito, Tab confinato, `Esc` chiude senza salvare, interruttori `role="switch"` usabili da tastiera.
|
|
290
|
+
- **Niente cookie wall**: il sito resta fruibile senza consenso.
|
|
291
|
+
- **Zero telemetria** della libreria stessa.
|
|
292
|
+
|
|
293
|
+
---
|
|
294
|
+
|
|
295
|
+
## 10. Service preset (id stringa per `services[]`)
|
|
296
|
+
|
|
297
|
+
| Categoria | Id |
|
|
298
|
+
|---|---|
|
|
299
|
+
| Analytics | `google-analytics`, `microsoft-clarity`, `hotjar` |
|
|
300
|
+
| Marketing | `facebook-pixel`, `google-ads`, `linkedin-insight`, `tiktok-pixel` |
|
|
301
|
+
| Tag manager | `google-tag-manager` |
|
|
302
|
+
| Pagamenti | `stripe`, `paypal` |
|
|
303
|
+
| Contenuti | `youtube`, `google-maps`, `google-fonts` |
|
|
304
|
+
| Form / mail | `contact-form`, `mailchimp`, `newsletter` |
|
|
305
|
+
|
|
306
|
+
Servizio inline custom:
|
|
307
|
+
|
|
308
|
+
```ts
|
|
309
|
+
{
|
|
310
|
+
id: "crm",
|
|
311
|
+
name: "CRM Interno",
|
|
312
|
+
category: "provided", // "automatic" | "provided" | "marketing"
|
|
313
|
+
consentCategory: "necessary", // "necessary" | "statistical" | "marketing"
|
|
314
|
+
purposes: ["Gestione clienti"],
|
|
315
|
+
dataCollected: ["Email", "Nome"],
|
|
316
|
+
}
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
`consentCategory` è la categoria del banner che abilita il servizio e decide quali finalità citano banner e cookie policy (`necessary` = nessun consenso da banner). Se manca viene dedotta da `cookies[].type` e `lawfulBasis`; se non è deducibile il banner resta sul testo generico.
|
|
320
|
+
|
|
321
|
+
`google-tag-manager` è `marketing` perché `GTMLegal` parte col consenso marketing. Se il container carica solo statistiche:
|
|
322
|
+
|
|
323
|
+
```tsx
|
|
324
|
+
services: [{ ...SERVICE_PRESETS["google-tag-manager"], consentCategory: "statistical" }]
|
|
325
|
+
<GTMLegal containerId="GTM-XXXX" category="statistical" />
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
---
|
|
329
|
+
|
|
330
|
+
## 11. API export
|
|
331
|
+
|
|
332
|
+
**`@graffico/legal/server`** — `LegalProvider`, `PrivacyPolicy`, `CookiePolicy`, `SERVICE_PRESETS`, `resolveService`.
|
|
333
|
+
|
|
334
|
+
**`@graffico/legal`** (client) —
|
|
335
|
+
- Tracker: `ConsentModeBoot`, `GoogleAnalyticsLegal`, `GoogleAdsLegal`, `MetaPixelLegal`, `HotjarLegal`, `GTMLegal`, `EmailJSLegal`
|
|
336
|
+
- Hook: `useConsent`, `useConsentCategory`, `useIsHydrated`, `useGAEvent`, `useAdsConversion`, `useMetaEvent`, `useHotjarEvent`, `useHotjarIdentify`, `useEmailJS`, `useT`, `useLegalLanguage`
|
|
337
|
+
- UI: `ConsentBanner`, `PreferenceModal`, `FloatingConsentToggle`, `ConsentGate`, `ConsentCheckbox`, `ServiceGrid`
|
|
338
|
+
- Azioni: `acceptAll`, `declineAll`, `savePreferences`, `resetConsent`, `setModalOpen`, `setLanguage`
|
|
339
|
+
- Primitive: `subscribeConsent`, `getConsentSnapshot`, `CONSENT_TTL_MS`, `SERVICE_PRESETS`
|
|
340
|
+
|
|
341
|
+
**`@graffico/legal/next`** — `withLegal`, `emitNetlifyHeaders`, `buildLegalHeaders`, `buildCspFromConfig`.
|
|
342
|
+
|
|
343
|
+
---
|
|
344
|
+
|
|
345
|
+
## Aggiornare alla 0.3.14
|
|
346
|
+
|
|
347
|
+
- **Preset lato server:** `SERVICE_PRESETS` e `resolveService` si importano anche da `@graffico/legal/server`. La config del sito, letta anche dal server, può estendere un preset invece di copiarlo: `{ ...SERVICE_PRESETS["contact-form"], dataCollected: [...] }`. Dall'entry client l'import restituirebbe un riferimento client, non l'oggetto.
|
|
348
|
+
|
|
349
|
+
## Aggiornare alla 0.3.13
|
|
350
|
+
|
|
351
|
+
- **Mappe, video e altri embed:** usare `ConsentGate category="externalContent"` al posto di `marketing` o `statistical`. I preset `google-maps`, `youtube` e `google-fonts` ora appartengono a questa categoria.
|
|
352
|
+
- **Google Fonts:** il preset indica il caricamento remoto, che richiede consenso. Con `next/font` i font sono self-hosted: togliere `google-fonts` da `services`.
|
|
353
|
+
- **Revoca:** togliere un consenso statistico o marketing già dato ricarica la pagina, perché è l'unico modo per fermare gli script già caricati.
|
|
354
|
+
- **Banner e footer:** la X chiude senza consenso, come Rifiuta. `<ConsentPreferencesLink />` va messo nel footer di ogni sito.
|
|
355
|
+
- **Cookie policy:** la riga `graffico-legal-consent` ora è automatica: togliere eventuali dichiarazioni manuali.
|
|
356
|
+
- **Retention:** `14m`, `2y` e simili vengono scritti per esteso. Per voci personalizzate usare come chiave un testo leggibile.
|
|
357
|
+
- **Percorsi:** se le policy non stanno su `/privacy-policy` e `/cookie-policy`, impostare `privacyPolicyPath` e `cookiePolicyPath` nella config.
|
|
358
|
+
- **Testi:** banner e policy cambiano. Aumentare `policyVersion` se il sito usa mappe, video o marketing.
|
|
359
|
+
|
|
360
|
+
## Aggiornare un sito già online
|
|
361
|
+
|
|
362
|
+
Il banner ora cita le finalità reali del sito. Se il sito dichiara `facebook-pixel`, `linkedin-insight`, `tiktok-pixel`, `google-ads`, `google-tag-manager`, `youtube` o `google-maps`, il testo passa da «misurazione» a «(misurazione,) marketing e profilazione»: chi ha cliccato «Accetta» col vecchio testo ha dato il consenso al marketing senza che il banner lo citasse. Insieme all'aggiornamento cambia `policyVersion` nella config del sito (es. `"2026.09"`) e aggiorna `lastUpdated`, così il banner viene riproposto e il consenso raccolto di nuovo. Sugli altri siti non serve.
|
|
363
|
+
|
|
364
|
+
---
|
|
365
|
+
|
|
366
|
+
## Requisiti
|
|
367
|
+
|
|
368
|
+
- React ≥ 18 (App Router consigliato)
|
|
369
|
+
- Tailwind opzionale (la UI usa classi Tailwind)
|
|
370
|
+
- `@emailjs/browser` ≥ 4 — peer optional, solo se usi `EmailJSLegal`
|
|
371
|
+
|
|
372
|
+
---
|
|
373
|
+
|
|
374
|
+
Made by **Graffico Studio**.
|