@nommos_test/events_angular

An angular library made up of directives, services and modules to set up tracking of users' actions as events on an angular site. This library uses the @nommos_test/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_test/events_angular provides:

• A Module that connects to a storage(Rabbit Web socket) and setup an environment for events Tracking.
• Directives and Services provide features to setup tracking on a particular element or action.
• Construction of Event Object with the aide of @nommos_test/core library
• Publishing of tracked events for storage

2. Compatibility

| Technology | Version | |-----------|---------| | Node.js | ≥ 14.x | | TypeScript | ≥ 4.7 | | Angular | >= 14.0 <= 22.0 | | @nommos_test/core | >= 0.0.1 | | Browser Support | Modern browsers + evergreen versions |

3. File Structure

| Folder | Description | |--------|-------------| | services/ | Singleton services for data collection and tracked events publishing used across the domain | | directives/ | directives related to events tracking | | **.module.ts | modules related to events tracking |

4. Module Setup

// app.module.ts  
import { ActivityTrackerModule } from '@nommos_test/events_angular';
import { ConnectionConfig, UrlTrackingKey  } from '@nommos_test/core';
import { NgModule } from '@angular/core';

const trackerConfig: ConnectionConfig = {
      token: 'YOUR_TOKEN',
      mode: 'dev',
    };
const urlTrackingKey: UrlTrackingKey =  { source: 'source' }

@NgModule({
  ...
  imports: [ActivityTrackerModule.forRoot(trackerConfig, urlTrackingKey)]
  ...
})
export class AppModule {}

// main.ts (standalone bootstrap)
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app/app.component';
import { provideActivityTracker } from '@nommos_test/events_angular';
import { ConnectionConfig, UrlTrackingKey  } from '@nommos_test/core';

const trackerConfig: ConnectionConfig = {
      token: 'YOUR_TOKEN',
      mode: 'dev',
    };
const urlTrackingKey: UrlTrackingKey =  { source: 'source' }

bootstrapApplication(AppComponent, {
  providers: [
    ...provideActivityTracker(trackerConfig, urlTrackingKey),
  ],
});

// app.config.ts (standalone config)
import { ApplicationConfig } from '@angular/core';
import { provideActivityTracker } from '@nommos_test/events_angular';
import { ConnectionConfig, UrlTrackingKey  } from '@nommos_test/core';

const trackerConfig: ConnectionConfig = {
      token: 'YOUR_TOKEN',
      mode: 'dev',
    };
const urlTrackingKey: UrlTrackingKey =  { source: 'source' }

export const appConfig: ApplicationConfig = {
  providers: [
    ...provideActivityTracker(trackerConfig, urlTrackingKey),
    // ... other providers
  ],
};

// main.ts import { bootstrapApplication } from '@angular/platform-browser'; import { appConfig } from './app/app.config'; import { App } from './app/app';

bootstrapApplication(App, appConfig).catch((err) => console.error(err));

## 6. API Documentation

### 6.1 Services
#### `Service: TrackerService`
##### `Method: trackEvent`
###### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
|`action` |`ANALYTICS_ACTION`| true | **required** | Action carried by a User being tracked|
|`state` |`ANALYTICS_ACTION_STATE`| true | **required** | State associated to the action being tracked|
|`data` |`Record<string, unknown> \| null`| false | `null` | Extra  information associated to the action being tracked|
|`toggle` |`boolean`| false | `true` | Boolean parameter to toggle selection state associated to the action or not|
|`selected` |`boolean \| null`| false | `null` | Boolean parameter to set the selection state associated to the action. Has priority over the `toggle` parameter |
|`userId` |`string`| false | `''` | ID of the user whom carried out the action being tracked |

###### Returns `void`

###### Example

```ts
  // trackerService: TrackerService

 // Track if the site was visited
 trackerService.trackEvent(ANALYTICS_ACTION.VISIT, 
  ANALYTICS_ACTION_STATE.INIT,
  null,
  false,
  null,
  'uid-123-abc'
 );

 // Track if the registration/signin was selected
 // If this is called a second time with the same parameters registration/signin is marked as unselected 
 trackerService.trackEvent(ANALYTICS_ACTION.SIGNIN, 
  ANALYTICS_ACTION_STATE.SELECT,
  null,
  true,
  null,
  'uid-123-abc'
 );

 // Track if the registration/signin was submitted
 trackerService.trackEvent(ANALYTICS_ACTION.SIGNIN, 
  ANALYTICS_ACTION_STATE.SUBMIT,
  {
    login: "userName"
  },
  false,
  null,
  'uid-123-abc'
 );

6.2 Directives

Directive: TrackClickDirective

A directive that will set the action being tracked, form the event and publish it on clicking the element where it is set (Buttons, links or any clickable element).

Selector: [nommosTrackClick]

Inputs

| Input | Type | Default | Description | | ------| ---- | ------- |------------ | | nommosTrackClick | ANALYTICS_ACTION | required | The action identifier to track | | state | ANALYTICS_ACTION_STATE | ANALYTICS_ACTION_STATE.SELECT| State associated with the action (select, unselect, submit, etc.) | | data | Record<string, unknown> | undefined | Optional extra data associated to the event | | toggle| boolean| true| Enables toggling ( ANALYTICS_ACTION_STATE.SELECT to/from ANALYTICS_ACTION_STATE.UN_SELECT) of an action selection state by multiple elements| | multi | boolean | false | Allows multiple elements to change an action selection state, for each event tracked to have the selection state of the element where the action was triggered. It has priority over the toggle input | | userId | string | '' | Optional user ID linked to the action |

Example

• Component Ts

// dash-bord.component.ts

import { Component } from '@angular/core';
import { TrackClickDirective } from '@nommos_test/events_angular';
import { ANALYTICS_ACTION } from '@nommos_test/core';
import { UserService } from '../services/user/user.service'

@Component({
  selector: 'app-dashboard',
  standalone: true,
  imports: [TrackClickDirective],
  templateUrl: './dash-bord.component.html'
})
export class DashboardComponent {
  action = ANALYTICS_ACTION;

  construction(private readonly userService: UserService){}

  get userId() {
    return userService.user.id ?? '';
  }
}

• Component template

  <!-- dash-board.component.html -->
  <!--
    Tracking of Bet selection
  -->
  <button
  [nommosTrackClick]="action.BET"
  [data]="{outcomeId: event.outcomeId, event_id: event.id}" [userId]="userId">
  {{ event.odd }}
</button>

<!--
    Tracking of Tournament selection
  -->
  <li
  *ngFor="let item of items"
  (click)="selectTournament(item)"
  [nommosTrackClick]="action.TOURNAMENT"
  [data]="{ id: item.id, name: item.name }"
>
  {{ item.name }}
</li>

Directive: TrackSubmitDirective

A directive that will set the action being tracked, form the event and publish it on form submissions.

Selector: [nommosTrackClick]

Inputs

| Input | Type | Default | Description | | ------| ---- | ------- |------------ | | nommosTrackClick | ANALYTICS_ACTION | required | The action identifier to track | | data | Record<string, unknown> | undefined | Optional extra data associated to the event | | userId | string | '' | Optional user ID linked to the action |

Example

• Component Ts

// signin.component.ts
import { Component } from '@angular/core';
import { FormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';
import { TrackSubmitDirective } from '@nommos_test/events_angular-tracker';
import { ANALYTICS_ACTION } from '@nommos_test/core';

@Component({
  selector: 'app-signin',
  standalone: true,
  imports: [ReactiveFormsModule, TrackSubmitDirective],
  templateUrl: './signin.component.html'
})
export class SignInComponent {
  constructor(private fb: FormBuilder) {}

  form = this.fb.group({
    email: ['', [Validators.required, Validators.email]],
    password: ['', [Validators.required]],
  });

  onSubmit() {
    if (this.form.invalid) return;
    console.log('Submitting sign-in form:', this.form.value);
  }

  readonly SIGNIN_ACTION = ANALYTICS_ACTION.SIGN_IN;
}

• Component template

<!-- signin.component.html -->
  <form
  [formGroup]="form"
  (ngSubmit)="onSubmit()"
  [nommosTrackSubmit]="SIGNIN_ACTION"
  [data]="form.value"
>
  <div>
    <label>Email</label>
    <input formControlName="email" type="email" />
  </div>

  <div>
    <label>Password</label>
    <input formControlName="password" type="password" />
  </div>

  <button type="submit">
    Sign In
  </button>
</form>