@c15t/react 2.0.4 → 2.2.0-canary-20260727202135

package/docs/integrations/logrocket.md

@@ -0,0 +1,175 @@
+---
+title: LogRocket
+description: Session replay and monitoring loaded after measurement consent with
+  LogRocket's browser SDK.
+group: integrations
+icon: logrocket
+---
+[LogRocket](https://logrocket.com) records session replay, frontend errors, network activity, console logs, and user behavior so product and engineering teams can debug production sessions. c15t loads `LogRocket.min.js` with `crossorigin="anonymous"` and then calls `window.LogRocket.init('org-slug/app-slug')`.
+
+## Integrate with c15t
+
+**React**
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/react';
+import { logRocket } from '@c15t/scripts/logrocket';
+
+const scripts = [
+  logRocket({
+    appId: 'YOUR_ORG_SLUG/YOUR_APP_SLUG',
+    initOptions: {
+      dom: {
+        inputSanitizer: true,
+      },
+    },
+  }),
+];
+
+export function ConsentProvider({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: 'https://your-instance.c15t.dev',
+        scripts,
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+**Next.js**
+
+```tsx
+'use client';
+
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/nextjs';
+import { logRocket } from '@c15t/scripts/logrocket';
+
+const scripts = [
+  logRocket({
+    appId: 'YOUR_ORG_SLUG/YOUR_APP_SLUG',
+    initOptions: {
+      dom: {
+        inputSanitizer: true,
+      },
+    },
+  }),
+];
+
+export function ConsentProvider({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        scripts,
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+**JavaScript**
+
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+import { logRocket } from '@c15t/scripts/logrocket';
+
+getOrCreateConsentRuntime({
+  mode: 'hosted',
+  backendURL: 'https://your-instance.c15t.dev',
+  scripts: [
+    logRocket({
+      appId: 'YOUR_ORG_SLUG/YOUR_APP_SLUG',
+      initOptions: {
+        dom: {
+          inputSanitizer: true,
+        },
+      },
+    }),
+  ],
+});
+```
+
+## How c15t loads it
+
+* **Category:** `measurement` (Analytics)
+* **Loads when:** measurement consent is granted
+* **On revocation:** unloaded - c15t removes the script element from the DOM. LogRocket does not document a web SDK consent opt-out or stop-recording API equivalent to Clarity or Mixpanel consent methods, and removing the loader does not stop an already-initialized recorder in the current page view. Revocation fully takes effect on the next page load.
+
+The helper maps the script-tag snippet into the manifest engine:
+
+```ts
+logRocket({
+  appId: 'YOUR_ORG_SLUG/YOUR_APP_SLUG',
+})
+```
+
+It loads `https://cdn.logrocket.io/LogRocket.min.js` with `crossorigin="anonymous"` and calls:
+
+```ts
+window.LogRocket?.init('YOUR_ORG_SLUG/YOUR_APP_SLUG', initOptions)
+```
+
+after the script load event. `appId` is required and must be in `org/app` format.
+
+## Privacy and sanitization
+
+LogRocket captures user behavior for replay, so configure sanitization before deploying it. LogRocket documents DOM redaction with `data-private`, automatic text/input/image sanitization, and network request/response sanitizers. Password fields are never recorded, but other sensitive inputs, DOM nodes, network payloads, Redux state, and Redux actions should be explicitly excluded.
+
+Pass JSON-serializable LogRocket init options as `initOptions`:
+
+```ts
+logRocket({
+  appId: 'YOUR_ORG_SLUG/YOUR_APP_SLUG',
+  initOptions: {
+    dom: {
+      inputSanitizer: true,
+      textSanitizer: true,
+      imageSanitizer: true,
+      privateClassNameBlocklist: ['private-profile'],
+      privateAttributeBlocklist: ['data-hide-from-replay'],
+    },
+  },
+})
+```
+
+Only pass values that can safely cross the manifest boundary. Avoid functions, class instances, prototypes, `Map`, `Set`, or other non-JSON types unless you are constructing a manual `Script` outside the manifest helper. LogRocket also supports function-based network sanitizers; use a manual `Script` if you need those callbacks.
+
+To proxy or self-host the loader, pass a custom URL. LogRocket's proxy setup also chain-loads a logger bundle, so set `asyncScriptUrl` as well — otherwise the async bundle is still fetched from LogRocket's CDN:
+
+```ts
+logRocket({
+  appId: 'YOUR_ORG_SLUG/YOUR_APP_SLUG',
+  scriptUrl: 'https://analytics.example.com/LogRocket.min.js',
+  asyncScriptUrl: 'https://analytics.example.com/logger.min.js',
+})
+```
+
+## Types
+
+### LogRocketOptions
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`LogRocketOptions\`|
+|Source Path|\`./packages/scripts/src/vendors/analytics/logrocket.ts\`|
+
+\*ExtractedTypeTable: Could not extract "LogRocketOptions" from "./packages/scripts/src/vendors/analytics/logrocket.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+### Script
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`Script\`|
+|Source Path|\`./packages/core/src/libs/script-loader/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "Script" from "./packages/core/src/libs/script-loader/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

package/docs/integrations/matomo-analytics.md

@@ -0,0 +1,171 @@
+---
+title: Matomo Analytics
+description: Load Matomo with c15t and keep Matomo's queue aligned with measurement consent.
+group: integrations
+icon: matomo
+---
+Matomo gives you privacy-focused web analytics with self-hosted and cloud deployment options. The `matomoAnalytics()` helper sets up Matomo's `_paq` queue, points it at your tracker, and can queue consent-aware commands before the vendor bundle loads.
+
+## Integrate with c15t
+
+**React**
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/react';
+import { matomoAnalytics } from '@c15t/scripts/matomo-analytics';
+
+const scripts = [
+  matomoAnalytics({
+    matomoUrl: 'https://analytics.example.com',
+    siteId: 1,
+  }),
+];
+
+export function ConsentProvider({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: 'https://your-instance.c15t.dev',
+        scripts,
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+**Next.js**
+
+```tsx
+'use client';
+
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/nextjs';
+import { matomoAnalytics } from '@c15t/scripts/matomo-analytics';
+
+const scripts = [
+  matomoAnalytics({
+    matomoUrl: 'https://analytics.example.com',
+    siteId: 1,
+  }),
+];
+
+export function ConsentProvider({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        scripts,
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+**JavaScript**
+
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+import { matomoAnalytics } from '@c15t/scripts/matomo-analytics';
+
+getOrCreateConsentRuntime({
+  mode: 'hosted',
+  backendURL: 'https://your-instance.c15t.dev',
+  scripts: [
+    matomoAnalytics({
+      matomoUrl: 'https://analytics.example.com',
+      siteId: 1,
+    }),
+  ],
+});
+```
+
+## How c15t loads it
+
+* **Category:** `measurement` (Analytics)
+* **Loads when:** measurement consent is granted by default
+* **Consent mode option:** with `defaultConsent`, the helper switches to `alwaysLoad: true` and uses Matomo queue commands to grant/forget consent without unloading the SDK.
+
+## Configure the integration
+
+If you want Matomo to manage consent internally, set `defaultConsent` to one
+of these values:
+
+* `'required'` queues Matomo's `requireConsent` command so no tracking runs
+  until consent is granted.
+* `'given'` queues Matomo's `setConsentGiven` command so tracking starts as
+  granted by default.
+
+When `defaultConsent` is omitted, c15t uses the standard script-loader flow:
+Matomo only loads after `measurement` consent is granted.
+
+```ts
+import { matomoAnalytics } from '@c15t/scripts/matomo-analytics';
+
+matomoAnalytics({
+  matomoUrl: 'https://analytics.example.com',
+  siteId: 1,
+  defaultConsent: 'required',
+});
+```
+
+## Tracking events in your app
+
+Matomo's runtime API is queue-based (`window._paq`). When the script is not loaded yet, pushing to `_paq` is still safe as long as the queue exists. The helper creates `_paq` during setup.
+
+From React:
+
+```tsx
+import { useCallback } from 'react';
+import { useConsentManager } from '@c15t/react';
+
+function SignupExample() {
+  const { has } = useConsentManager();
+
+  const trackSignup = useCallback(() => {
+    if (has('measurement')) {
+      window._paq?.push(['trackEvent', 'signup', 'completed']);
+    }
+  }, [has]);
+
+  return <button onClick={trackSignup}>Sign up</button>;
+}
+```
+
+From plain JavaScript:
+
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+
+const { consentStore } = getOrCreateConsentRuntime();
+
+if (consentStore.getState().has('measurement')) {
+  window._paq?.push(['trackEvent', 'signup', 'completed']);
+}
+```
+
+## Types
+
+### MatomoAnalyticsOptions
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`MatomoAnalyticsOptions\`|
+|Source Path|\`./packages/scripts/src/vendors/analytics/matomo-analytics.ts\`|
+
+\*ExtractedTypeTable: Could not extract "MatomoAnalyticsOptions" from "./packages/scripts/src/vendors/analytics/matomo-analytics.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+### Script
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`Script\`|
+|Source Path|\`./packages/core/src/libs/script-loader/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "Script" from "./packages/core/src/libs/script-loader/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*