Analytics Lib

Compile cmd:

cd /Users/ducdau/code/w3w/analytics-lib-js && npm run compile && npm pack

Install cmd:

cd /Users/ducdau/code/w3w/mapsite-frontend/app && npm install --save ../../analytics-lib-js/what3words-analytics-${PACKAGE_NUMBER}.tgz --legacy-peer-deps && rm -rf .next

Combined cmd:

cd /Users/ducdau/code/w3w/analytics-lib-js && npm run compile && npm pack && cd /Users/ducdau/code/w3w/mapsite-frontend/app && npm install --save ../../analytics-lib-js/what3words-analytics-${PACKAGE_NUMBER}.tgz --legacy-peer-deps && rm -rf .next

How to add new analytics events

1. clone our analytics library and create a new branch from main

2. add the new event strings and an appropriate name to events.ts

3. add the new events to the relevant tracker, so they will be sent to that system. The tracker here is Mixpanel, so add the cases to the existing list in mixpanel.ts. Some unit tests may need to be updated, depending on how the tests are written.

4. update the package.json (and package-lock.json) version number

5. at this point the code changes should look similar to this older PR and a PR can be raised for approval

6. When the changes are approved and merged, circleci will publish and tag using the version in the package.json file. When the pipeline is complete, create a new release in github using the tag that has been created.

7. Use the new analytics version in the application’s (eg mapsite’s) package.json

Testing new analytics events locally

The way I tend to test local analytics changes is by using npm pack. The following command will compile the analytics library locally and then use the local files as mapsite’s dependency. The paths will be different on each machine, and the package number from the analytics library must be used in the npm install section

cd /Users/frances/Workspace/analytics-js && npm run compile && npm pack && cd /Users/frances/Workspace/mapsite-frontend/app && npm install --save ../../analytics-js/what3words-analytics-${PACKAGE_NUMBER}.tgz --legacy-peer-deps && rm -rf .next && npm run dev

or to run each step one by one:

cd /Users/frances/Workspace/analytics-js # change to analytics library location on your machine npm run compile npm pack cd /Users/frances/Workspace/mapsite-frontend/app # change to app directory of mapsite's location on your machine npm install --save ../../analytics-js/what3words-analytics-${PACKAGE_NUMBER}.tgz --legacy-peer-deps # change the relative path to reflect your filesystem, and package number must be included rm -rf .next npm run dev

Using new analytics events when deploying

Some analytics changes may be complicated and merging them before testing can be problematic. The simplest way around this it to publish a “test” version of the library, which can be done locally.

1. update package.json and package-lock.json’s versions to something that is clearly not production ready, usually using the ticket number (eg 1.8.0-tt-9686). Do not skip this step.

2. run npm run compile and then npm publish (speak to @Frances Downey if access levels are not high enough)

3. sign in on npm and confirm the publish

4. you should receive and email saying the new version has been published, and you can use that version number in your application’s package.json (example)

Here’s an example of how devs have created “test” versions in the past. Each new attempt needs a unique version, hence the -1 -2 -3 etc additions.