@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

  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>

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>

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

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|