@graffico/legal 0.3.7 → 0.3.9
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 +341 -341
- package/dist/index.d.ts +2 -0
- package/dist/index.js +2 -2
- package/dist/server.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,341 +1,341 @@
|
|
|
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` (prova legale 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="marketing"
|
|
198
|
-
fallback={<p>Abilita cookie marketing 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)
|
|
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
|
-
- **Prova legale**: `consentId` UUID + `timestamp` ISO + `policyVersion` + `source` in localStorage e nel payload mail.
|
|
286
|
-
- **Parità grafica reject/accept** nel banner (Garante 10/06/2021 §4).
|
|
287
|
-
- **Categorie indipendenti**: `necessary` / `statistical` / `marketing`. Default OFF.
|
|
288
|
-
- **Niente cookie wall**: il sito resta fruibile senza consenso.
|
|
289
|
-
- **Zero telemetria** della libreria stessa.
|
|
290
|
-
|
|
291
|
-
---
|
|
292
|
-
|
|
293
|
-
## 10. Service preset (id stringa per `services[]`)
|
|
294
|
-
|
|
295
|
-
| Categoria | Id |
|
|
296
|
-
|---|---|
|
|
297
|
-
| Analytics | `google-analytics`, `microsoft-clarity`, `hotjar` |
|
|
298
|
-
| Marketing | `facebook-pixel`, `google-ads`, `linkedin-insight`, `tiktok-pixel` |
|
|
299
|
-
| Tag manager | `google-tag-manager` |
|
|
300
|
-
| Pagamenti | `stripe`, `paypal` |
|
|
301
|
-
| Contenuti | `youtube`, `google-maps`, `google-fonts` |
|
|
302
|
-
| Form / mail | `contact-form`, `mailchimp`, `newsletter` |
|
|
303
|
-
|
|
304
|
-
Servizio inline custom:
|
|
305
|
-
|
|
306
|
-
```ts
|
|
307
|
-
{
|
|
308
|
-
id: "crm",
|
|
309
|
-
name: "CRM Interno",
|
|
310
|
-
category: "provided", // "automatic" | "provided" | "marketing"
|
|
311
|
-
purposes: ["Gestione clienti"],
|
|
312
|
-
dataCollected: ["Email", "Nome"],
|
|
313
|
-
}
|
|
314
|
-
```
|
|
315
|
-
|
|
316
|
-
---
|
|
317
|
-
|
|
318
|
-
## 11. API export
|
|
319
|
-
|
|
320
|
-
**`@graffico/legal/server`** — `LegalProvider`, `PrivacyPolicy`, `CookiePolicy`.
|
|
321
|
-
|
|
322
|
-
**`@graffico/legal`** (client) —
|
|
323
|
-
- Tracker: `ConsentModeBoot`, `GoogleAnalyticsLegal`, `GoogleAdsLegal`, `MetaPixelLegal`, `HotjarLegal`, `GTMLegal`, `EmailJSLegal`
|
|
324
|
-
- Hook: `useConsent`, `useConsentCategory`, `useIsHydrated`, `useGAEvent`, `useAdsConversion`, `useMetaEvent`, `useHotjarEvent`, `useHotjarIdentify`, `useEmailJS`, `useT`, `useLegalLanguage`
|
|
325
|
-
- UI: `ConsentBanner`, `PreferenceModal`, `FloatingConsentToggle`, `ConsentGate`, `ConsentCheckbox`, `ServiceGrid`
|
|
326
|
-
- Azioni: `acceptAll`, `declineAll`, `savePreferences`, `resetConsent`, `setModalOpen`, `setLanguage`
|
|
327
|
-
- Primitive: `subscribeConsent`, `getConsentSnapshot`, `CONSENT_TTL_MS`, `SERVICE_PRESETS`
|
|
328
|
-
|
|
329
|
-
**`@graffico/legal/next`** — `withLegal`, `emitNetlifyHeaders`, `buildLegalHeaders`, `buildCspFromConfig`.
|
|
330
|
-
|
|
331
|
-
---
|
|
332
|
-
|
|
333
|
-
## Requisiti
|
|
334
|
-
|
|
335
|
-
- React ≥ 18 (App Router consigliato)
|
|
336
|
-
- Tailwind opzionale (la UI usa classi Tailwind)
|
|
337
|
-
- `@emailjs/browser` ≥ 4 — peer optional, solo se usi `EmailJSLegal`
|
|
338
|
-
|
|
339
|
-
---
|
|
340
|
-
|
|
341
|
-
Made by **Graffico Studio**.
|
|
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` (prova legale 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="marketing"
|
|
198
|
+
fallback={<p>Abilita cookie marketing 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)
|
|
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
|
+
- **Prova legale**: `consentId` UUID + `timestamp` ISO + `policyVersion` + `source` in localStorage e nel payload mail.
|
|
286
|
+
- **Parità grafica reject/accept** nel banner (Garante 10/06/2021 §4).
|
|
287
|
+
- **Categorie indipendenti**: `necessary` / `statistical` / `marketing`. Default OFF.
|
|
288
|
+
- **Niente cookie wall**: il sito resta fruibile senza consenso.
|
|
289
|
+
- **Zero telemetria** della libreria stessa.
|
|
290
|
+
|
|
291
|
+
---
|
|
292
|
+
|
|
293
|
+
## 10. Service preset (id stringa per `services[]`)
|
|
294
|
+
|
|
295
|
+
| Categoria | Id |
|
|
296
|
+
|---|---|
|
|
297
|
+
| Analytics | `google-analytics`, `microsoft-clarity`, `hotjar` |
|
|
298
|
+
| Marketing | `facebook-pixel`, `google-ads`, `linkedin-insight`, `tiktok-pixel` |
|
|
299
|
+
| Tag manager | `google-tag-manager` |
|
|
300
|
+
| Pagamenti | `stripe`, `paypal` |
|
|
301
|
+
| Contenuti | `youtube`, `google-maps`, `google-fonts` |
|
|
302
|
+
| Form / mail | `contact-form`, `mailchimp`, `newsletter` |
|
|
303
|
+
|
|
304
|
+
Servizio inline custom:
|
|
305
|
+
|
|
306
|
+
```ts
|
|
307
|
+
{
|
|
308
|
+
id: "crm",
|
|
309
|
+
name: "CRM Interno",
|
|
310
|
+
category: "provided", // "automatic" | "provided" | "marketing"
|
|
311
|
+
purposes: ["Gestione clienti"],
|
|
312
|
+
dataCollected: ["Email", "Nome"],
|
|
313
|
+
}
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
---
|
|
317
|
+
|
|
318
|
+
## 11. API export
|
|
319
|
+
|
|
320
|
+
**`@graffico/legal/server`** — `LegalProvider`, `PrivacyPolicy`, `CookiePolicy`.
|
|
321
|
+
|
|
322
|
+
**`@graffico/legal`** (client) —
|
|
323
|
+
- Tracker: `ConsentModeBoot`, `GoogleAnalyticsLegal`, `GoogleAdsLegal`, `MetaPixelLegal`, `HotjarLegal`, `GTMLegal`, `EmailJSLegal`
|
|
324
|
+
- Hook: `useConsent`, `useConsentCategory`, `useIsHydrated`, `useGAEvent`, `useAdsConversion`, `useMetaEvent`, `useHotjarEvent`, `useHotjarIdentify`, `useEmailJS`, `useT`, `useLegalLanguage`
|
|
325
|
+
- UI: `ConsentBanner`, `PreferenceModal`, `FloatingConsentToggle`, `ConsentGate`, `ConsentCheckbox`, `ServiceGrid`
|
|
326
|
+
- Azioni: `acceptAll`, `declineAll`, `savePreferences`, `resetConsent`, `setModalOpen`, `setLanguage`
|
|
327
|
+
- Primitive: `subscribeConsent`, `getConsentSnapshot`, `CONSENT_TTL_MS`, `SERVICE_PRESETS`
|
|
328
|
+
|
|
329
|
+
**`@graffico/legal/next`** — `withLegal`, `emitNetlifyHeaders`, `buildLegalHeaders`, `buildCspFromConfig`.
|
|
330
|
+
|
|
331
|
+
---
|
|
332
|
+
|
|
333
|
+
## Requisiti
|
|
334
|
+
|
|
335
|
+
- React ≥ 18 (App Router consigliato)
|
|
336
|
+
- Tailwind opzionale (la UI usa classi Tailwind)
|
|
337
|
+
- `@emailjs/browser` ≥ 4 — peer optional, solo se usi `EmailJSLegal`
|
|
338
|
+
|
|
339
|
+
---
|
|
340
|
+
|
|
341
|
+
Made by **Graffico Studio**.
|