@se-studio/core-ui 0.0.0-next16-20260822103555

package/ANALYTICS.md

@@ -0,0 +1,160 @@
+# Analytics Integration Guide
+
+Core UI provides a flexible, provider-agnostic analytics system with built-in consent management support.
+
+## Overview
+
+The analytics system consists of three parts:
+1. **AnalyticsProvider**: React context for analytics
+2. **Adapters**: Implementations for specific providers (GTM, Segment, etc.)
+3. **Consent Management**: Integration with Orejime for GDPR compliance
+
+## Usage
+
+### 1. Setup Provider
+
+Wrap your application with `ConsentProvider` and `AnalyticsProvider`.
+
+```tsx
+// src/components/AnalyticsProviderWrapper.tsx
+'use client';
+
+import { 
+  AnalyticsProvider, 
+  ConsentProvider, 
+  ConsentAwareAdapter,
+  GoogleTagManagerAdapter,
+  useConsent 
+} from '@se-studio/core-ui';
+import { useMemo } from 'react';
+
+function AnalyticsProviderInner({ children, containerId }) {
+  const { hasConsent } = useConsent();
+
+  const adapter = useMemo(() => {
+    // 1. Create base adapter
+    const gtmAdapter = new GoogleTagManagerAdapter({
+      containerId
+    });
+
+    // 2. Wrap with consent awareness
+    return new ConsentAwareAdapter(gtmAdapter, 'google-tag-manager', hasConsent);
+  }, [hasConsent, containerId]);
+
+  return <AnalyticsProvider adapter={adapter}>{children}</AnalyticsProvider>;
+}
+
+export function AnalyticsProviderWrapper({ children, gtmContainerId }) {
+  return (
+    <ConsentProvider>
+      <AnalyticsProviderInner containerId={gtmContainerId}>{children}</AnalyticsProviderInner>
+    </ConsentProvider>
+  );
+}
+```
+
+### 2. Tracking Events
+
+Use the `useAnalytics` hook to track events.
+
+```tsx
+import { useAnalytics } from '@se-studio/core-ui';
+
+function SubscribeButton() {
+  const { trackClick, trackEvent } = useAnalytics();
+
+  return (
+    <button onClick={() => trackClick('Button', 'Subscribe', { location: 'footer' })}>
+      Subscribe
+    </button>
+  );
+}
+```
+
+## Google Tag Manager (GTM)
+
+The `GoogleTagManagerAdapter` supports both GTM Container ID and GA4 Measurement ID.
+
+```tsx
+const adapter = new GoogleTagManagerAdapter({
+  containerId: 'GTM-XXXXXXX', // Loads GTM script
+  // OR
+  measurementId: 'G-XXXXXXXX', // Loads gtag.js directly
+});
+```
+
+### GTM Data Layer Events
+
+The adapter pushes events to `window.dataLayer`:
+
+- **Page View**:
+  ```json
+  {
+    "event": "page_view",
+    "page_location": "https://...",
+    "page_path": "/about",
+    "page_title": "About Us"
+  }
+  ```
+
+- **Click**:
+  ```json
+  {
+    "event": "click",
+    "componentType": "Button",
+    "linkText": "Subscribe",
+    "location": "footer"
+  }
+  ```
+
+- **Custom Event**:
+  ```json
+  {
+    "event": "custom_event_name",
+    "property": "value"
+  }
+  ```
+
+## Multiple providers (GTM + HubSpot)
+
+Use `CompositeAnalyticsAdapter` to fan out events to several adapters. Wrap with `ConsentAwareAdapter` once at the top level.
+
+```tsx
+import {
+  AnalyticsProvider,
+  CompositeAnalyticsAdapter,
+  ConsentAwareAdapter,
+  GoogleTagManagerAdapter,
+} from '@se-studio/core-ui';
+import { HubSpotAnalyticsAdapter } from '@se-studio/hubspot';
+
+const composite = new CompositeAnalyticsAdapter([
+  new GoogleTagManagerAdapter({ containerId: gtmId }),
+  new HubSpotAnalyticsAdapter({ portalId: hubspotPortalId }),
+]);
+const adapter = new ConsentAwareAdapter(composite, 'analytics', hasConsent);
+```
+
+Add `AnalyticsPageTracker` inside the provider for soft-navigation page views (HubSpot SPA Mode B). Load HubSpot's bootstrap script in the root layout with `createHubSpotBootstrapScript()` (no args — uses `window.location.pathname` at script run time) from `@se-studio/hubspot`. Do not use `headers()` in the root layout for pathname; that forces dynamic rendering and breaks on-demand SSG pages in production.
+
+A/B test impressions: use `AbTestReporter` from `@se-studio/ab-testing/components` inside `AnalyticsProvider`. It calls `trackEvent('experiment_impression', …)` including `hubspotEvent` when configured in Contentful.
+
+## Custom Adapters
+
+Implement the `AnalyticsAdapter` interface to support other providers.
+
+```typescript
+import type { AnalyticsAdapter, ClickTrackingProperties, PageTrackingProperties } from '@se-studio/core-ui';
+
+export class MyCustomAdapter implements AnalyticsAdapter {
+  trackEvent(event: string, properties: Record<string, unknown>) {
+    // Send to provider
+  }
+  trackPage(url: string, properties: PageTrackingProperties) {
+    // Send page view
+  }
+  trackClick(properties: ClickTrackingProperties) {
+    // Send click
+  }
+}
+```