@radai/event-services-rad-client v0.0.38

event-services-rad-client

Client for sending events to Rad AI's Event Services

Quickstart

Assumes:

• running in typescript
• using React
• using Vite

If any of these are not the case, you can still use the underlying packages @radai/event-services-gen-client and @radai/rad-service-client to compose your own client.

1. Install the package from npm:

npm install @radai/event-services-rad-client

2. Set the VITE_RADAI_INGEST_API_KEY environment variable to the access key for the Event Services API. See more about vite environment variables here.

VITE_RADAI_INGEST_API_KEY=XXX

3. In your react-app, wrap your component with the "EventServicesProvider"

// Page.tsx
import { EventServicesProvider, EventServiceEnv } from '@radai/event-services-rad-client';

import Page from './Page';

// wrap the Page component in the EventServicesProvider.
// This makes the `useEventTracking` hooks available to all components in the app.
ReactDOM.createRoot(
  document.getElementById('root') as HTMLElement
).render(
  <React.StrictMode>
    <EventServicesProvider env={EventServiceEnv.LOCAL}>
      <Page />
    </EventServicesProvider>
  </React.StrictMode>
);

4. Inside your component, you can use the useEventTracking hook to initalize the following functions: track, flush, setClientIds, reset.

Use setStaticAttributes to set attributes are the same across all events (must set "source") See the CloudStaticAttributes for more details.

Then, can use the track function to send events. Requries an event name and optional event metadata.

import { useEventTracking } from '@radai/event-services-rad-client';

export default function Page() {
  // note `useEventTracking` MUST be used inside of the EventServicesProvider
  const { track, flush, setStaticAttributes, reset } = useEventLifecycle();

  // set attributes that are the same across all events
  setStaticAttributes({ source: "QUICKSTART_DEMO" });

  return (
    <>
      <h1 className="text-4xl text-center my-4">Event Services Demo</h1>

      <div className="flex justify-center">
        <button
          className="px-4 py-2 bg-emerald-200 rounded-md"
          onClick={() => {
            track('testEvent', { userId: '123' });
          }}
        >
          Log Event
        </button>
      </div>
    </>
  );
}

5. If you would like to add event tracking to a non-react function, you can use the track function directly. Note: must still be within the context of a EventServicesProvider.

import { track } from "@radai/event-services-rad-client";

export const HelloWorld = () => {
  track("HelloWorld");
};

API

We are using TSDoc to document the API. Below are the available functions and components. DO NOT EDIT MANUALLY. RUN npm run tsdoc to update the API documentation.

Functions

• useEventLifecycle
• EventLifecycleProvider
• EventServicesProvider
• initializeEventManager
• getEventManager
• track
• reset
• flush
• resetManager

useEventLifecycle

Hook to access the functions to handle Event Lifecycle. Must be used in a component wrapped by the EventLifecycleProvider.

EventLifecycleProvider

React provider to wrap an app or component that needs to track events.

EventServicesProvider

React provider to handle the lifecycle of events as well as the client configuration.

This provider initializes the event services client and makes it available to all child components using the useEventLifecycle hook.

If you need to update the client configuration dynamically (e.g. token, headers, etc.), you can use the updateEventClientConfig function.

Parameters:

• env: - Event Service environment (local, dev, staging, prod)
• lifecycleConfig: - Optional configuration for the event lifecycle (batching, retry, etc.)
• children: - Optional children components

initializeEventManager

initialize the global EventManager with a trackFn, resetFn, and flushFn.

getEventManager

helper: get global instance of eventManager

track

track events inside of a EventManager context.

Parameters:

• event: - The name of the event to track (this will be the "type" of Event)
• eventOptions: - Optional additional fields to include in the event. Must be a JSON object.

reset

reset the EventManager context. Completely reset the tracking state.

flush

flush the EventManager context. Force the queue to immediately send all batched events.

resetManager

Constants

• DEFAULT_CONFIG
• EventLifecycleContext

DEFAULT_CONFIG

EventLifecycleContext

CloudEventClient

wraps the generated EventsService client with CloudEvent specific config/validation.

Methods

• setClientConfig
• getClientConfig
• setStaticAttributes
• getStaticAttributes
• whenStaticAttributesSet
• send

setClientConfig

setClientConfig: function to configure generated client (e.x. accessToken: "MY_ACCESS_TOKEN" )

Parameters:

• config: - the client configuration.

e.x. client = new CloudEventClient(EventServiceEnv.DEV); client.setClientConfig({ accessToken: "MY_ACCESS_TOKEN" });

getClientConfig

helper function to get the generated client's configuration.

setStaticAttributes

setStaticAttributes: initializes the CloudEvent configuration. Must include all required fields.

Parameters:

• staticAttributes: - static attributes for every event (e.g. source, userId, organization)

getStaticAttributes

getStaticAttributes: returns the static attributes for the client.

whenStaticAttributesSet

whenStaticAttributesSet: returns a promise that resolves when the static attributes are set.

send

Send events to the Event Service.

Parameters:

• events: - an array of JSON objects to send as events. Each object must have a "type" field.

EventManager

Singleton class to manage tracking events.

The class should get initalized one time. You can then use the track/reset/flush functions and know they will reference the same instance of the EventManager.

Methods

• initTrackFn
• initResetFn
• initFlushFn
• track
• reset
• flush

initTrackFn

Initializes tracking function for the EventManager.

Parameters:

• trackFn: - The function to track events.

initResetFn

initFlushFn

track

Tracks an event using the provided event name and options.

Parameters:

• event: - The name of the event to track.
• eventOptions: - Optional parameters for the event.

reset

flush

Properties

• trackFn
• resetFn
• flushFn

trackFn

resetFn

flushFn

Interfaces

• EventLifecycleConfig
• ClientStaticAttributes
• CloudStaticAttributes
• EventLifecycleContextType
• EventClient

EventLifecycleConfig

Configuration options for the EventLifecycleProvider.

ClientStaticAttributes

CloudStaticAttributes

Interface for the static attributes that are set on the client. These are the attributes that don't chnage between events. You can set these once and they will be included in every event you send.

See the required and optional fields below.

See the Event Service spec for more details: https://github.com/radaisystems/event-services/blob/main/components/event_services/models/cloudevent_schema.json

EventLifecycleContextType

interface representing the functions available in the EventLifecycleContext

EventClient

Client to wrap the generated EventsService client.