oculr-ngx

An analytics library that makes collecting data in an Angular app simple.

What does it do?

Oculr is an Angular library that helps you capture analytic events occurring in your app. The following features give you insight into what your users are doing in your app and how your app is handling data and errors in the background.

• Page views
• API calls
• Errors
• Content display
• Button and link interactions
• Form control interactions
• Sensitive information control interactions
• General app events

How can it help?

Oculr helps you know what you don't know.

Are your users finding the content you want them to? Are they getting stuck on a page or question? Is your app making redundant calls to an API? Is a feature not working leading to a subpar experience? These are just some of the questions Oculr can help answer.

Where does the data go?

Where you want it.

Oculr can point to any destination that you want to use for tracking analytic data. By default it comes with a couple preconfigured options for HTTP APIs and the console. Oculr also features the ability to shape the data based on your needs before being sent to an API.

Quick start

Install Oculr.

npm install oculr-ngx --save

Import Oculr to your app's Angular AppModule.

import { OculrAngularModule } from 'oculr-ngx';

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

Configure Oculr during app initialization in AppModule.

import { ConfigurationService, Destinations } from 'oculr-ngx';

@NgModule({
  providers: [
    {
      provide: APP_INITIALIZER,
      useFactory: initializeAppFactory,
      deps: [ConfigurationService],
      multi: true,
    },
  ],
})
export class AppModule {}

function initializeAppFactory(oculrConfigService: ConfigurationService): () => Observable<boolean> {
  oculrConfigService.loadAppConfig({
    logHttpTraffic: true,
    destinations: [
      {
        name: Destinations.Console,
        sendCustomEvents: false,
      },
    ],
  });
  return () => of(true);
}

Then add the oculrClick directive to any button in your app.

<button id="continue" oculrClick>Continue</button>

Run your app and you will see an analytic event get logged to your console when clicking the button.

Now that it's working you will likely want it to do more then log a single click to your console. Please check out our Full API for more hands-on details to get the most out of Oculr.

Documentation

• Full API
• Configuration
• Directives
• Services

Updates

• Check out our improvements
• See our latest release

Contributing

Want to help?

We're excited about your interest in the project. Have an idea, want to contribute some code, found a bug, expand some documentation? Awesome! Check out our contribution guide and then take a look at our issues and discussions. We recommend issues that have been labeled as help wanted or good first issue.

Local setup

Local setup and a quick few steps.

git clone https://github.com/progressive-insurance/oculr-ngx
cd oculr-ngx
npm install
npm run test

We recommend the following extensions to make the contribution process as seamless as possible.

• ESLint
• Prettier

Code of conduct

Help us make this project open and inclusive. Please follow our Code of Conduct.