Skip to content

Latest commit

 

History

History
82 lines (52 loc) · 3.36 KB

README.md

File metadata and controls

82 lines (52 loc) · 3.36 KB
Raw

anonymous-user-id

CI Test Coverage Maintainability npm node-current GitHub

anonymous-user-id is a JavaScript library that allows you to anonymously identify unique users on your website without requiring them to store (and consent to) a tracking cookie. Instead, we generate a unique ID for each user based on information that can be pulled out of a regular HTTP request, mainly the source IP address and User-Agent header.

The method we use to do this is heavily inspired by Plausible Analytics, with BLAKE2s as the hash function.

Supported Algorithms

  • hash(salt + domain + ip + user_agent) - This is the same algorithm used by Plausible Analytics. It relies on a salt you need to rotate at least once a day, preventing you (or anyone else) from tracking the actions of a single user for longer than the lifespan of a single salt.

  • hash(hash(secret + date) + domain + ip + user_agent) - This is a modified (and less secure) variant of the original algorithm, meant for apps that can't reliably keep state (such as serverless functions), preventing them from storing a salt. Instead, we generate the salt from a long-lived secret (which you can set as e.g. an environment variable) and the current date.

Getting Started

Prerequisites

  • Node >= 10 (if using in Node)

Installing

npm:

npm i anonymous-user-id

yarn:

yarn add anonymous-user-id

Usage

For each algorithm this package supports, it exports a function you can use to generate an ID with it.

  • getAnonymousUserId(salt: string, request: RequestDetails)

    • implements hash(salt + domain + ip + user_agent)

  • getAnonymousUserIdWithSecret(secret: string, request: RequestDetails)

    • implements hash(hash(secret + date) + domain + ip + user_agent)

Example

import {
  getAnonymousUserId,
  getAnonymousUserIdWithSecret,
} from 'anonymous-user-id';

const requestDetails = {
  domain: 'test.test',
  ip: '1.1.1.1',
  userAgent: 'test/1.0',
};

const id1 = getAnonymousUserId('salt', requestDetails);
const id2 = getAnonymousUserIdWithSecret('secret', requestDetails);

Contributing

If you have Docker and Docker Compose installed, you can run docker-compose up to immediately get a working development environment for this package, with Jest running the tests in watch mode.

You can also use yarn link to use your local version of the package in a different project.

Authors

License

This project is licensed under the MIT License - see the LICENSE file for details.