		{
		"name": "analytics-client",
		"version": "0.11.2",
		"version": "0.12.0-update-docs-a04e6b670fd2c76116522e4b7045b67fefca8c57",
		"description": "Convenient builders to compose analytics tools",
		@@ -5,0 +5,0 @@ "repository": {

package.json

		{
		"name": "analytics-client",
		"version": "0.11.2",
		"version": "0.12.0-update-docs-a04e6b670fd2c76116522e4b7045b67fefca8c57",
		"description": "Convenient builders to compose analytics tools",
		@@ -5,0 +5,0 @@ "repository": {

README.md

		@@ -5,2 +5,4 @@ Analytics client
		Client part of analytics services used at balena.
		The client talks to [analytics-backend](https://github.com/balena-io/analytics-backend) which processes the incoming events before forwarding them to the relevant parties, referred here as the final destinations.
		Currently the only final destination is Amplitude. We have plans to support more final destinations going forward, like Sentry.

		@@ -64,1 +66,42 @@ ## Installation
		```

		## Configuration

		We use environment configuration on the [analytics-backend](https://github.com/balena-io/analytics-backend) to mask the actual API tokens of the final destination services of these events.
		We expose easy to remember names to map the destination specific tokens to `projectName` variable used as part of client initialization. analytics-backend uses the value of `projectName` to reason where to pipe the event flow.
		The masking helps with preventing abuse and the mapping makes the configuration more flexible to support multiple final destinations.
		Reach out to the data team when in doubt which project to use or if you need to define a new project.

		In the final destinations, we separate staging and production environments. We use the same `projectName` value but different tokens to differentiate the production and staging environments. So you only need to update `endpoint` to pick the right destination.

		Use the staging environment for testing purposes by setting `endpoint` in the `createClient` initialization to `data.balena-staging.com`. Once you are happy with your tests and ready to go live, update the `endpoint` to `data.balena-cloud.com` for production environment.

		Additionally, identify your component using the parameter `componentName`. It's best to keep the value short yet descriptive.

		Please ask Operation folks for `#access` to the relevant project in your final destination so you can validate that the tracked events show as expected.

		Finally, there is the optional configuration parameter `componentVersion` to track the version of a component sending each event. This is useful to track changes across new component versions so we strongly recommend tracking it.

		## Web tracker

		[`WebTracker`](src/web.ts) exposes an events tracking interface suitable for web apps. It provides a simple `Page View` event tracking with page loading metrics via `trackPageView`.

		When initializing `createWebTracker`, set `prefix` as a short string that describes your project. All events tracked by `WebTracker` will have this `prefix` in their name.
		We use this prefixing method to identify and group events in the final destination for organization purposes and helping the analysts traverse the events with ease.
		This is especially useful when there are multiple components sending events to the same project in the final destination. To give an example, our marketing website, docs pages and blog all send `Page View` event but these are prefixed respectively `Marketing`, `Docs` and `Blog`. So the final event name is `[Marketing] Page View`, `[Docs] Page View`, etc. Furthermore, this method makes it easier to identify all the `Marketing` events.

		## Identifying users

		By default the client tracks `deviceId` to identify the current device of the end user. `deviceId` is a UUID generated automatically by the client. Use `setUserId` method to identify authenticated user. At least one of these identifiers is required to successfully track an event.

		In most cases the device refers to the browser of the user (or Electron application for the case of Etcher). By persisting the `deviceId` in the local storage, we are able to identify the events coming from the same user in order to create a timeline of component usage.

		It is possible to generate a new device identifier and also override an existing device identifier. We use these methods especially when we need to link multiple device identifiers that we know belonging to the same user.
		For instance, a balenaCloud user might login to the dashboard from multiple browsers and also use balenaCLI. We would like to create a coherent timeline that captures all their activity and display it under the same user in order to make a sound analysis of their balena platform usage. As long as all the components `setUserId` as soon as the authentication happens, we are able to link all the events with separate `deviceId` values that came even before the authentication on the backend side.

		[`AnalyticsUrlParams`](src/url-params.ts) helps with linking anonymous `deviceId` values that each component sends individually. For instance we use this method to link Etcher users clicking on EFP link to land on our blog website and eventually signup to balenaCloud. When the user clicks on the blog link in EFP, we append the `deviceId` generated by EFP component to the URL. Then the blog parses the URL to match EFP `deviceId` with blog `deviceId`. In a similar fashion, the signup links on the blog website also includes EFP `deviceId` as well as blog `deviceId`. When the user lands on balenaCloud dashboard and authenticates, we link all the user activity and list it under the same timeline. We need to make these jumps as there are 3 components tracking events and there are multiple domains involved. The benefit is we are able to look into a user's EFP and blog activity before signing up to balenaCloud.


		## Questions?

		Reach out to the data team in `r/analytics` flow for guidance and troubleshooting.

dist/bundle.js

Sorry, the diff of this file is too big to display

analytics-client - npm Package Compare versions

Improved metrics