analytics-service (aka Analytics Service Angular)

Usage

After you npm install or ng add the package you'll need to initialize the module in your application's module.

import { AnalyticsServiceModule } from 'analytics-service';

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

Pass in the analytics service configuration to the forRoot() function to register your providers. For example, here is a simple configuration for the Amplitude provider...

const AnalyticsConfig: AnalyticsServiceConfiguration = {
  analyticsProviderConfig: [
    {
      providerType: AnalyticsProviderType.amplitude,
      provider: new AmplitudeProvider({
        apiKey: environment.amplitudeApiKey
      }),
    }
  ],
  logLevel: "DEBUG"
}

Once the module is set up you can inject the AnalyticsService wherever you need it to track data and events about your user.

import { AnalyticEvent, AnalyticsService } from 'analytics-service';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {

  constructor(
    private analyticsService: AnalyticsService,
  ) { }

  buttonClicked(): void {
    const event: AnalyticEvent = {
      name: 'button-clicked',
      properties: {
        'color': 'red',
        'amount': 4,
        'options': ['a', 'c']
      }
    }
    this.analyticsService.track(event)
  }
}

Service Functions

setCurrentUser()

Set the current user using a AnalyticsCurrentUser object. In most cases you will set it to a unique identify that represents the user. You can also set the user with properties. These properties will overwrite existing properties if they already exist on the user (subject to change depending on the analytics provider's implementation)

track()

Track an event for the current user using an AnalyticEvent object. Give it a name and optional properties to be associated to the event in the Analytic provider (subject to change depending on the analytics provider's implementation)

updateCurrentUser()

Adds or updates current user with supplied properties. It accepts an object. Please keep to values that are JSON serializable. (Subject to change depending on the analytics provider's implementation)

increment()

Increments the given user property by the amount specified using a AnalyticIncrement object. Most providers will start at 0 if it doesn't exist. (Subject to change depending on the analytics provider's implementation)

unsetCurrentUser()

Removes the current user from the provider. You can pass in a boolean to tell the provider to make the user anonymous after they have been unset. Some providers will not need to do anything additional. Others may need to regenerate device identifiers, or other information that can be tied back to the user that was previously set.

Providers

Analytic providers are classes that the analytic service can provide information to so that they can process and notify their analytics library as needed.

Included

Amplitude

If you want to save analytic information to Amplitude, use the AmplitudeProvider. While using the serivce, if you want to verify that your events are working, you can use the Chrome plugin to help track what's happening in your app with Amplitude.

Custom

You can create your own provider and provide it in the configuration if you'd like to integrate with an unsupported analytics software product. Make sure that your custom provider extends AnalyticsProvider implements the required functions(even if they do nothing), and add it to the configuration.

export class CustomProvider extends AnalyticsProvider {

  constructor() {
    super()
    // Any logic needed for the library you're integrating with.
  }

  public trackEvent(event: AnalyticEvent): void {
    // Do track logic
  }

  public setCurrentUser(currentUser: AnalyticsCurrentUser): void {
    // do setCurrentUser logic
  }

  public updateCurrentUser(properties: object): void {
    // do updateCurrentUser logic
  }

  public increment(incrementor: AnalyticIncrement): void {
    // do increment logic
  }

  public unsetCurrentUser(makeAnonymous: boolean): void {
    // do unsetCurrentUser logic
  }
}

Then pass an instance into the configuration.

const AnalyticsConfig: AnalyticsServiceConfiguration = {
  analyticsProviderConfig: [
    {}, // some provider
    {
      providerType: AnalyticsProviderType.custom,
      provider: new CustomProvider(),
    }
    {}, // another provider
  ],
}