core-outline 1.1.22 → 1.1.23

package/README.md

@@ -1,31 +1,44 @@
 # 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
 ```
 
-```sh
+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 +46,36 @@ 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 |
 
-To flag items purchased:
+All events include: `anonymous_id` (persistent across sessions), `session_id` (per tab), UTM parameters, page URL, page path, device type, OS, and browser name.
 
-```sh
-flag_item_purchased('ITEM_ID');
+## 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);
 ```