npm package: @nommos/events_react
Description: An React-js library made up of a hook, a provider and wrapper components to set up tracking of users' actions as events on an react-js site. This library uses the `@nommos/core` library as base for the capturing of information associated with the url, the
Latest version: 0.0.30

# @nommos/events_react

An React-js library made up of a hook, a provider and wrapper components to set up tracking of users' actions as events on an react-js site. This library uses the `@nommos/core` library as base for the capturing of information associated with the url, the action carried, the user and the device used by user to carry out tracked actions on an angular site. These information are then bundled as an event object and published for storage and to be used later for analytics. 

## 1. Overview

`@nommos/events_react` provides:

- A Provider that creates and exposes an Event tracker class that connects to a storage(Rabbit Web socket) and setup an environment for events Tracking.
- A hook and wrapper components that provide features to setup tracking on a particular element/component or action.
- Construction of Event Object with the aide of `@nommos/core` library
- Publishing of tracked events for storage

## 2. Compatibility
| Technology | Version |
|-----------|---------|
| **Node.js** | ≥ 14.x |
| **TypeScript** | ≥ 4.7 |
| **react** | >=16.8.0 <20.0.0 |
| **@nommos/core** | >= 0.0.1 |
| **Browser Support** | Modern browsers + evergreen versions |

## 3. File Structure

| Folder | Description |
|--------|-------------|
| `components/` | Wrapper components for tracking of events on components / elements|
| `context/` | Context, provider and hook for events tracking  |

## 4. 🚀 Quick Start

4.1. Configure `NommosTrackerProvider` at the top of your app

```tsx
  import React from 'react';
  import ReactDOM from 'react-dom/client';
  import { NommosTrackerProvider } from '@nommos/events_react';
  import { ConnectionConfig, UrlTrackingKey } from '@nommos/core';
  import App from './App';
 
  const connectionConfig: ConnectionConfig = {
   token: 'YOUR_TOKEN',
   mode: 'dev',
  };

  const urlTrackingKey: UrlTrackingKey = {
    source: 'source',
    affiliateKey: 'ref',
    parrainageKey: 'parrain',
  };
 
  ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
    <React.StrictMode>
      <NommosTrackerProvider
          connectionConfig={connectionConfig}
          urlTrackingKey={urlTrackingKey}
        >
          <App />
      </NommosTrackerProvider>
    </React.StrictMode>
 );
 ```

5.2. Track events with `<NommosTrackClick>`

```tsx
import { useState } from 'react';
import { NommosTrackClick, NommosTrackSubmit } from '@nommos/events_react';
import { ANALYTICS_ACTION } from '@nommos/core';

function App() {

  return (
    <div style={{ maxWidth: 600, margin: '40px auto', fontFamily: 'sans-serif' }}>
      <h1>Nommos Track Click Example</h1>

      <section style={{ marginBottom: 40 }}>
        <h2>Click Tracking</h2>
        <p>Click the buttons below and send bet event selection/un-selection.</p>

        <NommosTrackClick action={ANALYTICS_ACTION.BET} data={{outComeId: "12345", eventId: "aeu-bbhsk-skj"}}>
          <button style={{ padding: '8px 16px', marginRight: 8 }}>
            Event 1
          </button>
        </NommosTrackClick>

        <NommosTrackClick action={ANALYTICS_ACTION.BET} data={{outComeId: "33046", eventId: "jah-cabd-fgc"}}>
          <button style={{ padding: '8px 16px', marginRight: 8 }}>
            Event 2
          </button>
        </NommosTrackClick>
      </section>

    </div>
  );
}

export default App;

```

5.3. Track submit events with `<NommosTrackSubmit>`

```tsx
import { useState } from 'react';
import { NommosTrackSubmit } from '@nommos/events_react';
import { ANALYTICS_ACTION } from '@nommos/core';

function App() {
  const [name, setName] = useState('');
  const [password, setPassword] = useState('');

  return (
    <div style={{ maxWidth: 600, margin: '40px auto', fontFamily: 'sans-serif' }}>
      <h1>Nommos Track Submit</h1>

      <section>
        <h2>Submit Tracking</h2>
        <p>Submit the form to send a login event.</p>

        <NommosTrackSubmit
          action={ANALYTICS_ACTION.SIGNIN}
          data={{ name }}
        >
          <form
            onSubmit={(e) => {
              e.preventDefault();
              console.log('Form submit handler called with name =', name);
            }}
          >
            <div style={{ marginBottom: 8 }}>
              <label>
                Name:{' '}
                <input
                  name="name"
                  value={name}
                  onChange={(e) => setName(e.target.value)}
                  style={{ padding: 4 }}
                />
              </label>
            </div>
            <div style={{ marginBottom: 8 }}>
              <label>
                Password:{' '}
                <input
                  name="password"
                  value={password}
                  onChange={(e) => setPassword(e.target.value)}
                  style={{ padding: 4 }}
                />
              </label>
            </div>
            <button type="submit" style={{ padding: '8px 16px' }}>
              Submit Form
            </button>
          </form>
        </NommosTrackSubmit>
      </section>
    </div>
  );
}

export default App;

```

5.4. Track events with `useNommosTracker` hook

```tsx
import { useNommosTracker } from '@nommos/events_react';
import { ANALYTICS_ACTION, ANALYTICS_ACTION_STATE } from '@nommos/core';
 
 function MyComponent() {
    const tracker = useNommosTracker();
 
    const handleClick = () => {
      tracker.track(ANALYTICS_ACTION.VISIT, ANALYTICS_ACTION_STATE.INIT);
    };
 
    return <button onClick={handleClick}>Mark Site as Visited</button>;
 }
```

## 6. API Documentation

### 6.1 Hooks
#### `Hook: useNommosTracker`
Hook to access the `EventTracker` from anywhere under a `<NommosTrackerProvider>`.
##### Returns `EventTracker`
The EventTracker instance for the current React subtree.
`throws` If called outside of a `<NommosTrackerProvider>`.

---
NB: check the readme of the `@nommos/core` library to know more about the `EventTracker` class.

### 6.2 Providers
#### `Provider: NommosTrackerProvider`
React provider that creates and exposes a `EventTracker` instance to its subtree. Wrap your application (or a part of it) with this provider to make tracking available via the `useNommosTracker()` hook and wrapper components like `<NommosTrackClick>` and `<NommosTrackSubmit>`.
##### Inputs
| Input | Type | Required | Description |
| ------| ---- | -------- |-------------|
| `connectionConfig`| `ConnectionConfig` | **required** | configuration config to initialize an instance of `EventTracker`|
| `urlTrackingKey`| `ConnectionConfig` | **required** | Object of query params to track from url to initialize an instance of `EventTracker`|