core-outline 1.1.21 → 1.1.23

package/README.md

@@ -1,50 +1,81 @@
-# CoreOutline React Component
-
-A React component for integrating Core&Outline session recording and event tracking into your web application.
-
-## Installation
-
-Install the package using npm:
-
-```sh
-npm install core-outline
-```
-
-or using yarn:
-
-```sh
-yarn add core-outline
-```
-
-```sh
-import React from 'react';
-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 */}
-    </CoreOutline>
-  );
-}
-
-export default App;
-```
-
-To flag items clicked or purchased:
-
-```sh
-import { flag_item_clicked, flag_item_purchased } from 'core-outline;
-```
-To flag items clicked:
-
-```sh
-flag_item_clicked('ITEM_ID');
-```
-To flag items purchased:
-
-```sh
-flag_item_purchased('ITEM_ID');
-```
+# Core&Outline React Component
+
+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
+
+```sh
+npm install core-outline
+```
+
+```sh
+yarn add core-outline
+```
+
+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';
+
+function App() {
+  return (
+    <CoreOutline
+      warehouse_id="cad1acc0-..."
+      data_source_id="3f4a1c2d-..."
+      data_source_secret="aB3xK9mZqR..."
+    >
+      {/* Your app */}
+    </CoreOutline>
+  );
+}
+
+export default App;
+```
+
+### Props
+
+| 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 |
+
+## What Gets Tracked Automatically
+
+| 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);
+```