@c15t/scripts 3.0.0-alpha.1 → 3.0.0-alpha.2
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/AGENTS.md +4 -0
- package/README.md +3 -3
- package/dist/e2e-test-utils.js +5 -3
- package/dist/events.js +218 -0
- package/dist/registry.js +30 -0
- package/dist/vendors/ads-and-pixels/pinterest-tag.js +123 -0
- package/dist/vendors/analytics/google-tag.js +14 -2
- package/dist/vendors/analytics/one-dollar-stats.js +30 -0
- package/dist/vendors/analytics/segment.js +10 -1
- package/dist/vendors/functional/front-chat.js +64 -0
- package/dist/vendors/tag-managers/google-tag-manager.js +17 -3
- package/dist-types/events.d.ts +46 -0
- package/dist-types/registry.d.ts +27 -0
- package/dist-types/vendors/ads-and-pixels/pinterest-tag.d.ts +295 -0
- package/dist-types/vendors/analytics/google-tag.d.ts +3 -1
- package/dist-types/vendors/analytics/one-dollar-stats.d.ts +39 -0
- package/dist-types/vendors/analytics/segment.d.ts +7 -1
- package/dist-types/vendors/functional/front-chat.d.ts +62 -0
- package/dist-types/vendors/tag-managers/google-tag-manager.d.ts +3 -1
- package/docs/README.md +4 -0
- package/docs/customization/overview.md +4 -3
- package/docs/customization/recipes.md +4 -2
- package/docs/customization/tokens.md +66 -3
- package/docs/frameworks/javascript/script-loader.md +6 -0
- package/docs/frameworks/next/script-loader.md +18 -12
- package/docs/frameworks/react/script-loader.md +6 -0
- package/docs/guides/consent-state.md +327 -0
- package/docs/guides/shared-consent-controls.md +158 -0
- package/docs/integrations/adobe-analytics.md +1 -1
- package/docs/integrations/ahrefs-analytics.md +1 -1
- package/docs/integrations/amplitude.md +1 -1
- package/docs/integrations/clearbit.md +1 -1
- package/docs/integrations/cloudflare-web-analytics.md +1 -1
- package/docs/integrations/cloudflare-zaraz.md +1 -1
- package/docs/integrations/crisp.md +1 -1
- package/docs/integrations/databuddy.md +1 -1
- package/docs/integrations/fathom-analytics.md +1 -1
- package/docs/integrations/front-chat.md +322 -0
- package/docs/integrations/google-maps.md +1 -1
- package/docs/integrations/google-tag-manager.md +1 -1
- package/docs/integrations/google-tag.md +1 -1
- package/docs/integrations/granular-consent.md +3 -1
- package/docs/integrations/heap.md +1 -1
- package/docs/integrations/hightouch.md +1 -1
- package/docs/integrations/hotjar.md +1 -1
- package/docs/integrations/intercom.md +1 -1
- package/docs/integrations/linkedin-insights.md +1 -1
- package/docs/integrations/logrocket.md +1 -1
- package/docs/integrations/matomo-analytics.md +1 -1
- package/docs/integrations/meta-pixel.md +1 -1
- package/docs/integrations/microsoft-clarity.md +1 -1
- package/docs/integrations/microsoft-uet.md +1 -1
- package/docs/integrations/mixpanel-analytics.md +1 -1
- package/docs/integrations/one-dollar-stats.md +305 -0
- package/docs/integrations/openai-pixel.md +1 -1
- package/docs/integrations/overview.md +17 -14
- package/docs/integrations/pinterest-tag.md +321 -0
- package/docs/integrations/pirsch.md +1 -1
- package/docs/integrations/plausible-analytics.md +1 -1
- package/docs/integrations/posthog.md +1 -1
- package/docs/integrations/promptwatch.md +1 -1
- package/docs/integrations/reddit-pixel.md +1 -1
- package/docs/integrations/rudderstack.md +1 -1
- package/docs/integrations/rybbit-analytics.md +1 -1
- package/docs/integrations/segment.md +1 -1
- package/docs/integrations/snapchat-pixel.md +1 -1
- package/docs/integrations/tiktok-pixel.md +1 -1
- package/docs/integrations/umami-analytics.md +1 -1
- package/docs/integrations/vercel-analytics.md +1 -1
- package/docs/integrations/x-pixel.md +1 -1
- package/docs/integrations/youtube.md +1 -1
- package/docs/upgrade-v3.md +129 -1
- package/package.json +25 -2
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import type { ConsentSnapshot, Script } from '@c15t/core';
|
|
2
|
+
/** Flat event metadata accepted by the shared dispatcher. */
|
|
3
|
+
export type EventProperties = Record<string, string | number | boolean>;
|
|
4
|
+
/** Runtime inputs: the host owns event names, c15t owns delivery eligibility. */
|
|
5
|
+
export interface EventDispatcherOptions {
|
|
6
|
+
scripts: readonly Script[];
|
|
7
|
+
getSnapshot: () => ConsentSnapshot;
|
|
8
|
+
/** SDKs needing explicit SPA pageviews. Omit SDKs that track history themselves. */
|
|
9
|
+
pageviews?: readonly string[];
|
|
10
|
+
/** Injectable browser globals for testing or embedded runtimes. */
|
|
11
|
+
globals?: object;
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Deliver events only to configured integrations with current analytics consent.
|
|
15
|
+
* Denied events are discarded, and a vendor error does not stop other deliveries.
|
|
16
|
+
*
|
|
17
|
+
* @param options - Scripts, current consent snapshot, optional SPA integrations
|
|
18
|
+
* and browser globals used to call their SDKs.
|
|
19
|
+
* @returns A dispatcher with `track` for named events and `pageview` for SPA
|
|
20
|
+
* navigation. The first pageview seeds the path without sending; later calls
|
|
21
|
+
* ignore duplicate paths and hash-only changes. Only configured `pageviews`
|
|
22
|
+
* integrations receive navigation events.
|
|
23
|
+
* @example
|
|
24
|
+
* ```ts
|
|
25
|
+
* const events = createEventDispatcher({ scripts, getSnapshot: kernel.getSnapshot,
|
|
26
|
+
* pageviews: ['segment'] });
|
|
27
|
+
* events.pageview(location.pathname);
|
|
28
|
+
* events.track('search', { length: 4 });
|
|
29
|
+
* events.pageview('/results');
|
|
30
|
+
* ```
|
|
31
|
+
*/
|
|
32
|
+
export declare const createEventDispatcher: (options: EventDispatcherOptions) => {
|
|
33
|
+
/**
|
|
34
|
+
* Seed the initial path, then deliver permitted navigation events.
|
|
35
|
+
* @param path - Current path, including any query and hash. Hash-only changes are ignored.
|
|
36
|
+
* @returns Nothing. The first call and duplicate paths do not send events.
|
|
37
|
+
*/
|
|
38
|
+
pageview(path: string): void;
|
|
39
|
+
/**
|
|
40
|
+
* Send a named event to each configured, currently permitted integration.
|
|
41
|
+
* @param event - Application event name understood by the configured SDKs.
|
|
42
|
+
* @param properties - Flat metadata copied for each vendor delivery.
|
|
43
|
+
* @returns Nothing. Denied events are discarded and SDK errors are isolated.
|
|
44
|
+
*/
|
|
45
|
+
track(event: string, properties?: EventProperties): void;
|
|
46
|
+
};
|
package/dist-types/registry.d.ts
CHANGED
|
@@ -193,6 +193,15 @@ export declare const builtInScriptIntegrations: readonly [{
|
|
|
193
193
|
readonly label: 'Mixpanel Analytics';
|
|
194
194
|
readonly packageSubpath: 'mixpanel-analytics';
|
|
195
195
|
readonly vendor: 'mixpanel-analytics';
|
|
196
|
+
}, {
|
|
197
|
+
readonly consentCategory: 'measurement';
|
|
198
|
+
readonly docsSlug: 'one-dollar-stats';
|
|
199
|
+
readonly hint: 'Website analytics with no API key';
|
|
200
|
+
readonly integrationCategory: 'analytics';
|
|
201
|
+
readonly key: 'oneDollarStats';
|
|
202
|
+
readonly label: 'OneDollarStats';
|
|
203
|
+
readonly packageSubpath: 'one-dollar-stats';
|
|
204
|
+
readonly vendor: 'one-dollar-stats';
|
|
196
205
|
}, {
|
|
197
206
|
readonly consentCategory: 'measurement';
|
|
198
207
|
readonly docsSlug: 'hotjar';
|
|
@@ -319,6 +328,15 @@ export declare const builtInScriptIntegrations: readonly [{
|
|
|
319
328
|
readonly label: 'Crisp';
|
|
320
329
|
readonly packageSubpath: 'crisp';
|
|
321
330
|
readonly vendor: 'crisp';
|
|
331
|
+
}, {
|
|
332
|
+
readonly consentCategory: 'functionality';
|
|
333
|
+
readonly docsSlug: 'front-chat';
|
|
334
|
+
readonly hint: 'Live chat widget';
|
|
335
|
+
readonly integrationCategory: 'functional';
|
|
336
|
+
readonly key: 'frontChat';
|
|
337
|
+
readonly label: 'Front Chat';
|
|
338
|
+
readonly packageSubpath: 'front-chat';
|
|
339
|
+
readonly vendor: 'front-chat';
|
|
322
340
|
}, {
|
|
323
341
|
readonly consentCategory: 'functionality';
|
|
324
342
|
readonly docsSlug: 'intercom';
|
|
@@ -346,6 +364,15 @@ export declare const builtInScriptIntegrations: readonly [{
|
|
|
346
364
|
readonly label: 'OpenAI Pixel (ChatGPT Ads)';
|
|
347
365
|
readonly packageSubpath: 'openai-pixel';
|
|
348
366
|
readonly vendor: 'openai-pixel';
|
|
367
|
+
}, {
|
|
368
|
+
readonly consentCategory: 'marketing';
|
|
369
|
+
readonly docsSlug: 'pinterest-tag';
|
|
370
|
+
readonly hint: 'Pinterest ads tracking';
|
|
371
|
+
readonly integrationCategory: 'ads-and-pixels';
|
|
372
|
+
readonly key: 'pinterestTag';
|
|
373
|
+
readonly label: 'Pinterest Tag';
|
|
374
|
+
readonly packageSubpath: 'pinterest-tag';
|
|
375
|
+
readonly vendor: 'pinterest-tag';
|
|
349
376
|
}, {
|
|
350
377
|
readonly consentCategory: 'marketing';
|
|
351
378
|
readonly docsSlug: 'reddit-pixel';
|
|
@@ -0,0 +1,295 @@
|
|
|
1
|
+
import type { Script } from '@c15t/core';
|
|
2
|
+
/**
|
|
3
|
+
* The 20 Pinterest Tag event types accepted by `pintrk('track', ...)`.
|
|
4
|
+
*
|
|
5
|
+
* Conversion tracking and reporting require one of these names. Any other
|
|
6
|
+
* string is treated as a user-defined event, which Pinterest makes available
|
|
7
|
+
* for audience targeting only.
|
|
8
|
+
*
|
|
9
|
+
* @see {@link https://help.pinterest.com/en/business/article/add-event-codes} Add event codes
|
|
10
|
+
*/
|
|
11
|
+
export type PinterestTagEventName = 'pagevisit' | 'viewcategory' | 'search' | 'addtocart' | 'checkout' | 'watchvideo' | 'signup' | 'lead' | 'custom' | 'addpaymentinfo' | 'addtowishlist' | 'initiatecheckout' | 'subscribe' | 'viewcontent' | 'contact' | 'schedule' | 'findlocation' | 'customizeproduct' | 'submitapplication' | 'starttrial';
|
|
12
|
+
/**
|
|
13
|
+
* A product entry in `PinterestTagEventData.line_items`.
|
|
14
|
+
*
|
|
15
|
+
* Pinterest reads product-level details from `line_items`, not from the
|
|
16
|
+
* top level of the event data.
|
|
17
|
+
*/
|
|
18
|
+
export interface PinterestTagLineItem {
|
|
19
|
+
/** Product name, for example `Parker Boots`. */
|
|
20
|
+
product_name?: string;
|
|
21
|
+
/** Product identifier or SKU. */
|
|
22
|
+
product_id?: string;
|
|
23
|
+
/** Product category, for example `Shoes`. */
|
|
24
|
+
product_category?: string;
|
|
25
|
+
/** Variant identifier, for example `1414-Red`. */
|
|
26
|
+
product_variant_id?: string;
|
|
27
|
+
/** Human-readable variant, for example `Red`. */
|
|
28
|
+
product_variant?: string;
|
|
29
|
+
/** Unit price of the product. */
|
|
30
|
+
product_price?: number;
|
|
31
|
+
/** Quantity of this product in the event. */
|
|
32
|
+
product_quantity?: number;
|
|
33
|
+
/** Brand name. */
|
|
34
|
+
product_brand?: string;
|
|
35
|
+
[key: string]: unknown;
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Currency codes Pinterest accepts in `PinterestTagEventData.currency`.
|
|
39
|
+
*
|
|
40
|
+
* Pinterest converts the reported value to your advertiser account currency.
|
|
41
|
+
*/
|
|
42
|
+
export type PinterestTagCurrency = 'AED' | 'AMD' | 'ARS' | 'AUD' | 'AZN' | 'BAM' | 'BGN' | 'BHD' | 'BMD' | 'BND' | 'BOB' | 'BRL' | 'BSD' | 'CAD' | 'CHF' | 'CLP' | 'CNY' | 'COP' | 'CRC' | 'CZK' | 'DKK' | 'DOP' | 'EGP' | 'EUR' | 'FJD' | 'GBP' | 'GEL' | 'GIP' | 'HKD' | 'HNL' | 'HRK' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'ISK' | 'JMD' | 'JPY' | 'KGS' | 'KRW' | 'KWD' | 'KZT' | 'MAD' | 'MDL' | 'MOP' | 'MXN' | 'MYR' | 'NOK' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PHP' | 'PKR' | 'PLN' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'SAR' | 'SEK' | 'SGD' | 'THB' | 'TRY' | 'TWD' | 'UAH' | 'USD' | 'UYU' | 'VND' | 'ZAR';
|
|
43
|
+
/**
|
|
44
|
+
* Event data accepted by `pintrk('track', ...)`.
|
|
45
|
+
*
|
|
46
|
+
* Pinterest documents the same field set for every event type; which fields
|
|
47
|
+
* are meaningful depends on the event. All event data is available for
|
|
48
|
+
* audience targeting, but only `value` and `order_quantity` appear in paid
|
|
49
|
+
* and organic conversion reporting. Any additional keys are forwarded
|
|
50
|
+
* unchanged.
|
|
51
|
+
*/
|
|
52
|
+
export interface PinterestTagEventData {
|
|
53
|
+
/**
|
|
54
|
+
* Unique event identifier used to deduplicate against Conversions API
|
|
55
|
+
* events. Pinterest also accepts this under `eventID` or `eid`.
|
|
56
|
+
*/
|
|
57
|
+
event_id?: string;
|
|
58
|
+
/** Case-sensitive alias for `event_id`. */
|
|
59
|
+
eventID?: string;
|
|
60
|
+
/** Case-sensitive alias for `event_id`. */
|
|
61
|
+
eid?: string;
|
|
62
|
+
/**
|
|
63
|
+
* Total monetary value for commerce events such as `checkout`.
|
|
64
|
+
*
|
|
65
|
+
* Available in conversion reporting.
|
|
66
|
+
*/
|
|
67
|
+
value?: number;
|
|
68
|
+
/**
|
|
69
|
+
* Total number of items in the order.
|
|
70
|
+
*
|
|
71
|
+
* Available in conversion reporting.
|
|
72
|
+
*/
|
|
73
|
+
order_quantity?: number;
|
|
74
|
+
/**
|
|
75
|
+
* Currency code for `value`, for example `USD`. Required for `addtocart`
|
|
76
|
+
* and `checkout` in catalog sales campaigns.
|
|
77
|
+
*/
|
|
78
|
+
currency?: PinterestTagCurrency | (string & Record<never, never>);
|
|
79
|
+
/**
|
|
80
|
+
* Order identifier for `checkout` events. Required for conversion
|
|
81
|
+
* analysis reporting.
|
|
82
|
+
*/
|
|
83
|
+
order_id?: string;
|
|
84
|
+
/** Promo code applied to the order. */
|
|
85
|
+
promo_code?: string;
|
|
86
|
+
/** Property or store name, for example `Athleta`. */
|
|
87
|
+
property?: string;
|
|
88
|
+
/** Query text for `search` events. */
|
|
89
|
+
search_query?: string;
|
|
90
|
+
/** Video title for `watchvideo` events. */
|
|
91
|
+
video_title?: string;
|
|
92
|
+
/** Lead type for `lead` events, for example `Newsletter`. */
|
|
93
|
+
lead_type?: string;
|
|
94
|
+
/** Products associated with the event. */
|
|
95
|
+
line_items?: PinterestTagLineItem[];
|
|
96
|
+
[key: string]: unknown;
|
|
97
|
+
}
|
|
98
|
+
/**
|
|
99
|
+
* Options passed as the third argument to `pintrk('load', tagId, options)`.
|
|
100
|
+
*/
|
|
101
|
+
export interface PinterestTagLoadOptions {
|
|
102
|
+
/**
|
|
103
|
+
* Email address (plain or SHA-256 hashed) for Pinterest enhanced match.
|
|
104
|
+
*
|
|
105
|
+
* Only provide this when your application has separately obtained the
|
|
106
|
+
* appropriate user consent to share it with Pinterest.
|
|
107
|
+
*/
|
|
108
|
+
em?: string;
|
|
109
|
+
/**
|
|
110
|
+
* Hashed external user identifier used by Pinterest for attribution.
|
|
111
|
+
*/
|
|
112
|
+
external_id?: string;
|
|
113
|
+
[key: string]: unknown;
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* Optional callback passed as the last argument to `pintrk('track', ...)`.
|
|
117
|
+
*
|
|
118
|
+
* @param didInit - `true` when Pinterest constructed the event call
|
|
119
|
+
* successfully, `false` when it detected an error.
|
|
120
|
+
* @param error - Error description when `didInit` is `false`, otherwise
|
|
121
|
+
* `undefined`.
|
|
122
|
+
*/
|
|
123
|
+
export type PinterestTagEventCallback = (didInit: boolean, error?: string) => void;
|
|
124
|
+
interface PinterestTagFunction {
|
|
125
|
+
(command: 'load', tagId: string, options?: PinterestTagLoadOptions): void;
|
|
126
|
+
(command: 'page'): void;
|
|
127
|
+
(command: 'track', eventName: PinterestTagEventName | (string & Record<never, never>), eventData?: PinterestTagEventData, callback?: PinterestTagEventCallback): void;
|
|
128
|
+
(command: 'setconsent', consent: boolean): void;
|
|
129
|
+
(command: 'set', data: Record<string, unknown>): void;
|
|
130
|
+
(command: string, ...args: unknown[]): void;
|
|
131
|
+
}
|
|
132
|
+
declare global {
|
|
133
|
+
interface Window {
|
|
134
|
+
pintrk?: PinterestTagFunction & {
|
|
135
|
+
queue?: unknown[][];
|
|
136
|
+
version?: string;
|
|
137
|
+
};
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
/**
|
|
141
|
+
* Pinterest Tag vendor manifest.
|
|
142
|
+
*
|
|
143
|
+
* Mirrors Pinterest's v3 base code: a `pintrk` stub that pushes argument
|
|
144
|
+
* arrays onto `pintrk.queue`, `pintrk.version = "3.0"`, then the async
|
|
145
|
+
* `core.js` loader.
|
|
146
|
+
*
|
|
147
|
+
* Pinterest exposes a runtime consent API via `pintrk('setconsent', boolean)`.
|
|
148
|
+
* `setconsent(false)` stops events and clears Pinterest's first-party
|
|
149
|
+
* storage, so the script persists after consent revocation and receives the
|
|
150
|
+
* updated consent state instead of being removed from the document.
|
|
151
|
+
*/
|
|
152
|
+
export declare const pinterestTagManifest: {
|
|
153
|
+
readonly kind: "c15t.vendor-manifest";
|
|
154
|
+
readonly schemaVersion: 1;
|
|
155
|
+
readonly bootstrap: [{
|
|
156
|
+
readonly ifUndefined: true;
|
|
157
|
+
readonly name: 'pintrk';
|
|
158
|
+
readonly properties: {
|
|
159
|
+
readonly version: '3.0';
|
|
160
|
+
};
|
|
161
|
+
readonly queue: {
|
|
162
|
+
readonly property: 'queue';
|
|
163
|
+
};
|
|
164
|
+
readonly queueFormat: 'array';
|
|
165
|
+
readonly type: 'defineStubFunction';
|
|
166
|
+
}];
|
|
167
|
+
readonly category: 'marketing';
|
|
168
|
+
readonly install: [{
|
|
169
|
+
readonly args: ["load", "{{tagId}}"];
|
|
170
|
+
readonly global: 'pintrk';
|
|
171
|
+
readonly type: 'callGlobal';
|
|
172
|
+
}, {
|
|
173
|
+
readonly args: ["setconsent", true];
|
|
174
|
+
readonly global: 'pintrk';
|
|
175
|
+
readonly type: 'callGlobal';
|
|
176
|
+
}, {
|
|
177
|
+
readonly args: ["page"];
|
|
178
|
+
readonly global: 'pintrk';
|
|
179
|
+
readonly type: 'callGlobal';
|
|
180
|
+
}, {
|
|
181
|
+
readonly async: true;
|
|
182
|
+
readonly src: '{{scriptUrl}}';
|
|
183
|
+
readonly type: 'loadScript';
|
|
184
|
+
}];
|
|
185
|
+
readonly onConsentDenied: [{
|
|
186
|
+
readonly args: ["setconsent", false];
|
|
187
|
+
readonly global: 'pintrk';
|
|
188
|
+
readonly type: 'callGlobal';
|
|
189
|
+
}];
|
|
190
|
+
readonly onConsentGranted: [{
|
|
191
|
+
readonly args: ["setconsent", true];
|
|
192
|
+
readonly global: 'pintrk';
|
|
193
|
+
readonly type: 'callGlobal';
|
|
194
|
+
}];
|
|
195
|
+
readonly persistAfterConsentRevoked: true;
|
|
196
|
+
readonly vendor: 'pinterest-tag';
|
|
197
|
+
};
|
|
198
|
+
export interface PinterestTagOptions {
|
|
199
|
+
/**
|
|
200
|
+
* Your Pinterest Tag ID.
|
|
201
|
+
* @example `2613654212508`
|
|
202
|
+
*/
|
|
203
|
+
tagId: string;
|
|
204
|
+
/**
|
|
205
|
+
* Optional payload passed to `pintrk('load', tagId, loadOptions)`, for
|
|
206
|
+
* example enhanced match values.
|
|
207
|
+
*
|
|
208
|
+
* Do not provide user identifiers unless the appropriate consent and
|
|
209
|
+
* privacy requirements have already been satisfied.
|
|
210
|
+
*/
|
|
211
|
+
loadOptions?: PinterestTagLoadOptions;
|
|
212
|
+
/**
|
|
213
|
+
* Queue the default `pintrk('page')` page-visit event during setup.
|
|
214
|
+
* @default true
|
|
215
|
+
*/
|
|
216
|
+
trackPageVisit?: boolean;
|
|
217
|
+
/** Pinterest Tag loader URL. */
|
|
218
|
+
scriptUrl?: string;
|
|
219
|
+
}
|
|
220
|
+
/**
|
|
221
|
+
* Creates a Pinterest Tag script.
|
|
222
|
+
*
|
|
223
|
+
* This script persists after consent is revoked because Pinterest exposes
|
|
224
|
+
* `pintrk('setconsent', boolean)`, which lets c15t disable tracking and clear
|
|
225
|
+
* Pinterest's first-party storage without removing the script element.
|
|
226
|
+
*
|
|
227
|
+
* @param options.tagId - Pinterest Tag ID used in `pintrk('load', ...)`.
|
|
228
|
+
* Numeric string from Pinterest Ads Manager, for example `'2613654212508'`.
|
|
229
|
+
* @param options.loadOptions - Optional object passed as the third argument to
|
|
230
|
+
* `pintrk('load', tagId, loadOptions)`, for example `{ em: 'user@example.com' }`.
|
|
231
|
+
* @param options.trackPageVisit - Whether to queue the default `pintrk('page')`
|
|
232
|
+
* call during setup. Defaults to `true`.
|
|
233
|
+
* @param options.scriptUrl - Override for Pinterest's `core.js` loader URL.
|
|
234
|
+
* @returns A resolved c15t `Script` configuration that defines the `pintrk`
|
|
235
|
+
* queue stub, queues `load`, `setconsent`, and optionally `page`, then loads
|
|
236
|
+
* Pinterest's `core.js`.
|
|
237
|
+
*
|
|
238
|
+
* @example
|
|
239
|
+
* ```ts
|
|
240
|
+
* const script = pinterestTag({
|
|
241
|
+
* tagId: '2613654212508',
|
|
242
|
+
* loadOptions: { em: 'user@example.com' },
|
|
243
|
+
* trackPageVisit: false,
|
|
244
|
+
* });
|
|
245
|
+
* ```
|
|
246
|
+
*
|
|
247
|
+
* @see {@link https://help.pinterest.com/en/business/article/install-the-pinterest-tag} Pinterest Tag documentation
|
|
248
|
+
*/
|
|
249
|
+
export declare const pinterestTag: ({ tagId, loadOptions, trackPageVisit, scriptUrl, }: PinterestTagOptions) => Script;
|
|
250
|
+
/**
|
|
251
|
+
* Tracks a Pinterest Tag event.
|
|
252
|
+
*
|
|
253
|
+
* This helper is a no-op until Pinterest has been initialized by c15t, so it
|
|
254
|
+
* is safe to call before marketing consent is granted. It does not bypass
|
|
255
|
+
* consent: after revocation Pinterest's own `setconsent(false)` state
|
|
256
|
+
* suppresses the event.
|
|
257
|
+
*
|
|
258
|
+
* @param eventName - One of Pinterest's 20 event types or a user-defined
|
|
259
|
+
* event name.
|
|
260
|
+
* @param eventData - Optional event data, including `event_id` for Tag plus
|
|
261
|
+
* Conversions API deduplication.
|
|
262
|
+
* @param callback - Optional `(didInit, error)` callback Pinterest invokes
|
|
263
|
+
* after constructing the event call. Useful for surfacing tag errors in
|
|
264
|
+
* development.
|
|
265
|
+
*
|
|
266
|
+
* @example
|
|
267
|
+
* ```ts
|
|
268
|
+
* pinterestTagEvent('checkout', {
|
|
269
|
+
* event_id: 'event-123',
|
|
270
|
+
* value: 99.99,
|
|
271
|
+
* order_quantity: 1,
|
|
272
|
+
* currency: 'USD',
|
|
273
|
+
* order_id: 'order-123',
|
|
274
|
+
* line_items: [
|
|
275
|
+
* {
|
|
276
|
+
* product_name: 'Parker Boots',
|
|
277
|
+
* product_id: '1414',
|
|
278
|
+
* product_price: 99.99,
|
|
279
|
+
* product_quantity: 1,
|
|
280
|
+
* },
|
|
281
|
+
* ],
|
|
282
|
+
* });
|
|
283
|
+
* ```
|
|
284
|
+
*
|
|
285
|
+
* @example
|
|
286
|
+
* ```ts
|
|
287
|
+
* pinterestTagEvent('lead', { lead_type: 'Newsletter' }, (didInit, error) => {
|
|
288
|
+
* if (!didInit) {
|
|
289
|
+
* console.error(error);
|
|
290
|
+
* }
|
|
291
|
+
* });
|
|
292
|
+
* ```
|
|
293
|
+
*/
|
|
294
|
+
export declare const pinterestTagEvent: (eventName: PinterestTagEventName | (string & Record<never, never>), eventData?: PinterestTagEventData, callback?: PinterestTagEventCallback) => void;
|
|
295
|
+
export {};
|
|
@@ -49,6 +49,8 @@ export declare const gtagManifest: {
|
|
|
49
49
|
readonly vendor: 'gtag';
|
|
50
50
|
};
|
|
51
51
|
export interface GtagOptions {
|
|
52
|
+
/** Parameters forwarded to gtag config. */
|
|
53
|
+
config?: Record<string, unknown>;
|
|
52
54
|
/**
|
|
53
55
|
* Your gtag id
|
|
54
56
|
* @example `G-XXXXXXX`
|
|
@@ -90,4 +92,4 @@ export interface GtagOptions {
|
|
|
90
92
|
* @param options - The options for the gtag script.
|
|
91
93
|
* @returns The Google Tag Manager script.
|
|
92
94
|
*/
|
|
93
|
-
export declare const gtag: ({ id, category, consentMapping, script, }: GtagOptions) => Script;
|
|
95
|
+
export declare const gtag: ({ id, config, category, consentMapping, script, }: GtagOptions) => Script;
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import type { Script } from '@c15t/core';
|
|
2
|
+
/** The classic script from OneDollarStats' installation instructions. */
|
|
3
|
+
export declare const ONE_DOLLAR_STATS_SCRIPT_SRC = "https://assets.onedollarstats.com/stonks.js";
|
|
4
|
+
/** OneDollarStats is loaded only after measurement consent is granted. */
|
|
5
|
+
export declare const oneDollarStatsManifest: {
|
|
6
|
+
readonly kind: "c15t.vendor-manifest";
|
|
7
|
+
readonly schemaVersion: 1;
|
|
8
|
+
readonly category: 'measurement';
|
|
9
|
+
readonly install: [{
|
|
10
|
+
readonly defer: true;
|
|
11
|
+
readonly src: "https://assets.onedollarstats.com/stonks.js";
|
|
12
|
+
readonly type: 'loadScript';
|
|
13
|
+
}];
|
|
14
|
+
readonly vendor: 'one-dollar-stats';
|
|
15
|
+
};
|
|
16
|
+
export interface OneDollarStatsOptions {
|
|
17
|
+
/**
|
|
18
|
+
* Bare hostname, such as `docs.example.com`. Overrides the event hostname
|
|
19
|
+
* on every host, including production. Required for local dev mode.
|
|
20
|
+
*/
|
|
21
|
+
hostname?: string;
|
|
22
|
+
/**
|
|
23
|
+
* Tracker settings forwarded as `data-*` attributes. Use string values,
|
|
24
|
+
* e.g. `devmode: 'true'`, `autocollect: 'false'`, or a custom `url`.
|
|
25
|
+
* Setting `'hash-routing': 'false'` omits the presence-based attribute.
|
|
26
|
+
*/
|
|
27
|
+
[setting: string]: string | undefined;
|
|
28
|
+
}
|
|
29
|
+
/**
|
|
30
|
+
* Creates a consent-gated OneDollarStats script. No API key is required.
|
|
31
|
+
* The tracker reads data attributes from `document.currentScript` and
|
|
32
|
+
* handles client-side navigation itself.
|
|
33
|
+
*
|
|
34
|
+
* @param options - Tracker settings without the `data-` prefix.
|
|
35
|
+
* @returns The OneDollarStats script configuration.
|
|
36
|
+
* @throws {Error} When hostname is not a bare host, or a setting name is not
|
|
37
|
+
* a valid attribute name or its value is not a string.
|
|
38
|
+
*/
|
|
39
|
+
export declare const oneDollarStats: (options?: OneDollarStatsOptions) => Script;
|
|
@@ -131,6 +131,10 @@ export declare const segmentManifest: {
|
|
|
131
131
|
}];
|
|
132
132
|
readonly category: 'measurement';
|
|
133
133
|
readonly install: [{
|
|
134
|
+
readonly path: ["analytics", "_loadOptions"];
|
|
135
|
+
readonly type: 'setGlobalPath';
|
|
136
|
+
readonly value: '{{loadOptions}}';
|
|
137
|
+
}, {
|
|
134
138
|
readonly global: 'analytics';
|
|
135
139
|
readonly method: 'page';
|
|
136
140
|
readonly type: 'callGlobal';
|
|
@@ -142,6 +146,8 @@ export declare const segmentManifest: {
|
|
|
142
146
|
readonly vendor: 'segment';
|
|
143
147
|
};
|
|
144
148
|
export interface SegmentOptions {
|
|
149
|
+
/** Options consumed by Analytics.js on initialization. */
|
|
150
|
+
loadOptions?: Record<string, unknown>;
|
|
145
151
|
/** Your Segment write key. */
|
|
146
152
|
writeKey: string;
|
|
147
153
|
/** Queue the initial `analytics.page()` call during setup. */
|
|
@@ -155,4 +161,4 @@ export interface SegmentOptions {
|
|
|
155
161
|
* @param options - The options for the Segment script.
|
|
156
162
|
* @returns The Segment script configuration.
|
|
157
163
|
*/
|
|
158
|
-
export declare const segment: ({ writeKey, trackPageView, scriptUrl, }: SegmentOptions) => Script;
|
|
164
|
+
export declare const segment: ({ writeKey, loadOptions, trackPageView, scriptUrl, }: SegmentOptions) => Script;
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
import type { Script } from '@c15t/core';
|
|
2
|
+
declare global {
|
|
3
|
+
interface Window {
|
|
4
|
+
FrontChat?: (command: string, options?: Record<string, unknown>) => unknown;
|
|
5
|
+
}
|
|
6
|
+
}
|
|
7
|
+
/** Front Chat loader and consent-gated widget initialisation. */
|
|
8
|
+
export declare const frontChatManifest: {
|
|
9
|
+
readonly kind: "c15t.vendor-manifest";
|
|
10
|
+
readonly schemaVersion: 1;
|
|
11
|
+
readonly category: 'functionality';
|
|
12
|
+
readonly install: [{
|
|
13
|
+
readonly async: true;
|
|
14
|
+
readonly src: '{{scriptSrc}}';
|
|
15
|
+
readonly type: 'loadScript';
|
|
16
|
+
}];
|
|
17
|
+
readonly onLoadGranted: [{
|
|
18
|
+
readonly args: ["init", "{{initOptions}}"];
|
|
19
|
+
readonly global: 'FrontChat';
|
|
20
|
+
readonly type: 'callGlobal';
|
|
21
|
+
}];
|
|
22
|
+
readonly vendor: 'front-chat';
|
|
23
|
+
};
|
|
24
|
+
export interface FrontChatOptions {
|
|
25
|
+
/** Public chat ID from the Front channel's installation snippet. */
|
|
26
|
+
chatId: string;
|
|
27
|
+
/** Show Front's default launcher. @default true */
|
|
28
|
+
useDefaultLauncher?: boolean;
|
|
29
|
+
/** Custom or proxied Front Chat bundle URL. */
|
|
30
|
+
scriptSrc?: string;
|
|
31
|
+
/** CSP nonce forwarded to the loader and Front's generated scripts. */
|
|
32
|
+
nonce?: string;
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* Creates a Front Chat script gated on functionality consent.
|
|
36
|
+
*
|
|
37
|
+
* Keep c15t's default reload-on-revocation behaviour enabled to stop an
|
|
38
|
+
* already-running widget. Removing its loader cannot unload the SDK.
|
|
39
|
+
*
|
|
40
|
+
* @param options - Front channel and launcher configuration.
|
|
41
|
+
* @returns The Front Chat script configuration.
|
|
42
|
+
* @throws {Error} When chatId is missing or empty. Copy the public ID from
|
|
43
|
+
* the Front channel's installation snippet.
|
|
44
|
+
* @example
|
|
45
|
+
* frontChat({ chatId: 'YOUR_FRONT_CHAT_ID' });
|
|
46
|
+
* @see https://help.front.com/en/articles/2049
|
|
47
|
+
*/
|
|
48
|
+
export declare const frontChat: (options: FrontChatOptions) => Script;
|
|
49
|
+
/**
|
|
50
|
+
* Requests widget removal and session cleanup through Front's SDK.
|
|
51
|
+
*
|
|
52
|
+
* Optionally call it from `onBeforeConsentRevocationReload`. Front does not
|
|
53
|
+
* provide a completion promise, so this does not guarantee cleanup before
|
|
54
|
+
* navigation.
|
|
55
|
+
* Safe to call during SSR or before the SDK loads.
|
|
56
|
+
*
|
|
57
|
+
* @returns Nothing.
|
|
58
|
+
* @example
|
|
59
|
+
* shutdownFrontChat();
|
|
60
|
+
* @see https://dev.frontapp.com/docs/chat-sdk-reference
|
|
61
|
+
*/
|
|
62
|
+
export declare const shutdownFrontChat: () => void;
|
|
@@ -54,6 +54,8 @@ export declare const googleTagManagerManifest: {
|
|
|
54
54
|
readonly vendor: 'google-tag-manager';
|
|
55
55
|
};
|
|
56
56
|
export interface GoogleTagManagerOptions {
|
|
57
|
+
/** Container queue name. Defaults to dataLayer. */
|
|
58
|
+
dataLayer?: string;
|
|
57
59
|
/**
|
|
58
60
|
* Your Google Tag Manager container ID. Begins with 'GTM-'.
|
|
59
61
|
* @example `GTM-1234XXX`
|
|
@@ -91,4 +93,4 @@ export interface GoogleTagManagerOptions {
|
|
|
91
93
|
* @param options - The options for the Google Tag Manager script.
|
|
92
94
|
* @returns The Google Tag Manager script.
|
|
93
95
|
*/
|
|
94
|
-
export declare const googleTagManager: ({ id, updateEventName, consentMapping, }: GoogleTagManagerOptions) => Script;
|
|
96
|
+
export declare const googleTagManager: ({ id, dataLayer, updateEventName, consentMapping, }: GoogleTagManagerOptions) => Script;
|
package/docs/README.md
CHANGED
|
@@ -30,6 +30,7 @@ These docs describe v3. Start with Inth hosted setup, identify the framework, ro
|
|
|
30
30
|
- [Understand consent state](./guides/consent-state.md): Distinguish policy resolution, effective permissions, explicit choices, notices and privacy signals.
|
|
31
31
|
- [Data fetching and transports](./guides/data-fetching.md): Choose cached manifests, backend init or offline policy resolution, and understand where consent records are saved.
|
|
32
32
|
- [Choose a deployment mode](./guides/deployment-modes.md): Choose who runs your consent backend, then select manifest, init or offline resolution for your deployment.
|
|
33
|
+
- [Share consent controls across frameworks](./guides/shared-consent-controls.md): Use the same c15t script lifecycle, external consent source, and event controls in every framework.
|
|
33
34
|
- [Troubleshoot consent](./guides/troubleshooting.md): Diagnose missing banners, early vendor requests, lost choices and hydration differences.
|
|
34
35
|
- [Verify consent before shipping](./guides/verify-consent.md): Test requests, policy resolution, persistence, navigation and preference changes in a production build.
|
|
35
36
|
|
|
@@ -54,6 +55,7 @@ These docs describe v3. Start with Inth hosted setup, identify the framework, ro
|
|
|
54
55
|
- [Crisp](./integrations/crisp.md): Configure Crisp with c15t v3, understand functionality permission and verify loading and revocation.
|
|
55
56
|
- [Databuddy](./integrations/databuddy.md): Configure Databuddy's initial and updated consent state with c15t v3.
|
|
56
57
|
- [Fathom Analytics](./integrations/fathom-analytics.md): Configure Fathom Analytics with c15t v3, understand measurement permission and verify loading and revocation.
|
|
58
|
+
- [Front Chat](./integrations/front-chat.md): Load the Front Chat widget with functionality permission, forward CSP nonces and clear the session on revocation.
|
|
57
59
|
- [Google Maps](./integrations/google-maps.md): Prevent a map iframe from mounting before the required permission.
|
|
58
60
|
- [Google Tag](./integrations/google-tag.md): Configure gtag with c15t Consent Mode signals and understand its loading behavior.
|
|
59
61
|
- [Google Tag Manager](./integrations/google-tag-manager.md): Load GTM with c15t consent signals and verify the tags inside your container.
|
|
@@ -69,8 +71,10 @@ These docs describe v3. Start with Inth hosted setup, identify the framework, ro
|
|
|
69
71
|
- [Microsoft Clarity](./integrations/microsoft-clarity.md): Configure Microsoft Clarity with c15t v3, understand measurement permission and verify loading and revocation.
|
|
70
72
|
- [Microsoft UET](./integrations/microsoft-uet.md): Configure Microsoft UET with c15t v3, understand marketing permission and verify loading and revocation.
|
|
71
73
|
- [Mixpanel](./integrations/mixpanel-analytics.md): Configure Mixpanel with c15t v3, understand measurement permission and verify loading and revocation.
|
|
74
|
+
- [OneDollarStats](./integrations/one-dollar-stats.md): Load the OneDollarStats tracker with measurement permission, forward its settings and verify loading and revocation.
|
|
72
75
|
- [OpenAI Pixel](./integrations/openai-pixel.md): Configure the OpenAI Measurement Pixel for ChatGPT Ads with c15t v3, manage marketing permission and verify conversion delivery.
|
|
73
76
|
- [Overview](./integrations/overview.md): Find all c15t integrations for analytics, tag managers, advertising, chat and embedded content.
|
|
77
|
+
- [Pinterest Tag](./integrations/pinterest-tag.md): Configure the Pinterest Tag with c15t v3, track typed events and verify marketing permission, revocation and reload.
|
|
74
78
|
- [Pirsch](./integrations/pirsch.md): Configure Pirsch with c15t v3, understand measurement permission and verify loading and revocation.
|
|
75
79
|
- [Plausible Analytics](./integrations/plausible-analytics.md): Configure Plausible Analytics with c15t v3, understand measurement permission and verify loading and revocation.
|
|
76
80
|
- [PostHog](./integrations/posthog.md): Choose PostHog loading and cookieless behavior, configure the region, and synchronize v3 permissions.
|
|
@@ -34,10 +34,11 @@ layout can be restored by the policy renderer.
|
|
|
34
34
|
## Use the adapter's configuration shape
|
|
35
35
|
|
|
36
36
|
React and Next.js accept provider `theme`, `presentation` and `components`
|
|
37
|
-
options. Vue and Nuxt expose their own shared configuration, including CSS
|
|
37
|
+
options, and render theme tokens with `ConsentTheme` on the server. Vue and Nuxt expose their own shared configuration, including CSS
|
|
38
38
|
`tokens` and component slots. Svelte accepts its provider options and theme
|
|
39
|
-
|
|
40
|
-
|
|
39
|
+
slots; SvelteKit renders the token CSS from a server `load`. Astro serializes
|
|
40
|
+
integration options, renders the theme tokens on the server and uses the
|
|
41
|
+
selected adapter for dialogs. Do not move a configuration object between frameworks without checking
|
|
41
42
|
the target types.
|
|
42
43
|
|
|
43
44
|
Read [tokens and CSS](./tokens.md),
|
|
@@ -26,8 +26,10 @@ export const brandTheme = defineTheme({
|
|
|
26
26
|
|
|
27
27
|
```
|
|
28
28
|
|
|
29
|
-
Install `@c15t/ui` to use `defineTheme` directly.
|
|
30
|
-
|
|
29
|
+
Install `@c15t/ui` to use `defineTheme` directly. Render
|
|
30
|
+
`<ConsentTheme theme={brandTheme} />` on the server for the tokens, and pass
|
|
31
|
+
`brandTheme` as `theme` in your existing React or Next.js provider options for
|
|
32
|
+
the action styles. Keep your Inth mode and script
|
|
31
33
|
configuration. The theme source above is also imported by the runnable example,
|
|
32
34
|
so the rendered result and the documentation use the same values.
|
|
33
35
|
|