core-outline 1.1.22 → 1.1.24

package/README.md

@@ -1,31 +1,55 @@
 # Core&Outline React Component
 
-A React component for integrating Core&Outline session recording and event tracking into your web application.
+A React component for automatically tracking user activity — page views, clicks, session duration, SPA navigation, and session recordings — and streaming events to your Core&Outline analytics warehouse.
 
 ## Installation
 
-Install the package using npm:
-
 ```sh
 npm install core-outline
 ```
 
-or using yarn:
-
 ```sh
 yarn add core-outline
 ```
 
+## Prerequisites
+
+Before adding the component to your app, create an SDK data source through the Hermes API to obtain your credentials. This requires your Firebase authentication token.
+
 ```sh
+curl -X POST https://atlas-orchestrator.atlas.coreoutline.com/api/ingest/sdk-sources \
+  -H "Authorization: Bearer <your-firebase-token>" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "My Website"}'
+```
+
+The response contains your `data_source_id`, `data_source_secret`, and `warehouse_id`. **The secret is shown once — store it securely.**
+
+```json
+{
+  "data_source_id": "3f4a1c2d-...",
+  "data_source_secret": "aB3xK9mZqR...",
+  "warehouse_id": "cad1acc0-...",
+  "name": "My Website"
+}
+```
+
+## Usage
+
+Wrap your app's root component with `<CoreOutline>`. All tracking is automatic from that point — no additional configuration is needed.
+
+```jsx
 import React from 'react';
-import CoreOutline from 'core-outline';
+import { CoreOutline } from 'core-outline';
 
 function App() {
   return (
     <CoreOutline
-    data_source_id={{ YOUR_DATA_SOURCE_ID }}
-    data_source_secret={{ YOUR_DATA_SOURCE_SECRET }}>
-      {/* Your app components */}
+      warehouse_id="cad1acc0-..."
+      data_source_id="3f4a1c2d-..."
+      data_source_secret="aB3xK9mZqR..."
+    >
+      {/* Your app */}
     </CoreOutline>
   );
 }
@@ -33,20 +57,70 @@ function App() {
 export default App;
 ```
 
-To flag items clicked or purchased:
+### Props
 
-```sh
-import { flag_item_clicked, flag_item_purchased } from 'core-outline;
-```
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `warehouse_id` | `string` | Yes | Your tenant warehouse UUID (returned from the SDK source creation call) |
+| `data_source_id` | `string` | Yes | The UUID of your SDK data source |
+| `data_source_secret` | `string` | Yes | The secret generated at data source creation |
 
-To flag items clicked:
+## What Gets Tracked Automatically
 
-```sh
-flag_item_clicked('ITEM_ID');
+| Event | Description |
+|-------|-------------|
+| `session_start` | Fires when the component mounts; captures browser, OS, device type, UTM params, referrer |
+| `pageview` | Fires on mount and on every SPA navigation (pushState / popstate) |
+| `item_clicked` | Fires on every click; captures element tag, id, class, and inner text |
+| `session_end` | Fires on tab close or visibility change; includes session duration and pageview count |
+| Session recording | rrweb-powered DOM recording uploaded at session end |
+
+All events include: `anonymous_id` (persistent across sessions), `session_id` (per tab), UTM parameters, page URL, page path, device type, OS, and browser name.
+
+## Manual Event Tracking
+
+For commerce events, call the exported helpers from anywhere in your app — no props required.
+
+```js
+import { flag_item_clicked, flag_item_purchased } from 'core-outline';
+
+// Track a product click
+flag_item_clicked('sku-123');
+
+// Track a purchase (price is optional, maps to value_num in ClickHouse)
+flag_item_purchased('sku-123', 49.99);
 ```
 
-To flag items purchased:
+## Data Pipeline
 
-```sh
-flag_item_purchased('ITEM_ID');
+Events flow through the following pipeline:
+
+```
+Browser → POST /api/ingest/events → RabbitMQ ({warehouse_id}.analytics.events)
+       → Consumer worker → ClickHouse atlas_analytics
 ```
+
+The ClickHouse tables populated are:
+
+| Table | Populated by |
+|-------|-------------|
+| `fact_event` | All events except session start/end |
+| `fact_session` | `session_start` and `session_end` events |
+| `fact_pageview` | `pageview` events |
+| `stg_events_sdk_event` | All events (raw staging) |
+| `stg_rrweb_event` | Session recording chunks |
+
+These tables are queried by the [atlas-analytics](https://analytics.atlas.coreoutline.com) API under `/metrics/saas/traffic`, `/metrics/saas/engagement`, and related endpoints.
+
+## Anonymous vs Session Identity
+
+- **`anonymous_id`** — a UUID stored in `localStorage`; persists across browser sessions, used to stitch cross-session user journeys.
+- **`session_id`** — a UUID stored in `sessionStorage`; reset on each new tab or browser close, matching the standard session definition.
+
+## Service URLs
+
+| Service | URL |
+|---------|-----|
+| Hermes API (credential management) | `https://atlas-orchestrator.atlas.coreoutline.com` |
+| Maia (data engineering / pipelines) | `https://data-engineering.atlas.coreoutline.com` |
+| Atlas Analytics API | `https://analytics.atlas.coreoutline.com` |