{"id":13596373,"url":"https://github.com/vesparny/fair-analytics","last_synced_at":"2025-04-12T23:39:17.935Z","repository":{"id":57232384,"uuid":"89372549","full_name":"vesparny/fair-analytics","owner":"vesparny","description":"📊  An analytics server that doesn't undermine user's privacy","archived":false,"fork":false,"pushed_at":"2018-05-14T17:19:55.000Z","size":227,"stargazers_count":747,"open_issues_count":8,"forks_count":25,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-04-12T23:39:12.630Z","etag":null,"topics":["analytics","distributed","fair","ga","nodejs","p2p"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vesparny.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-04-25T14:49:20.000Z","updated_at":"2025-01-18T13:09:12.000Z","dependencies_parsed_at":"2022-08-25T20:40:48.805Z","dependency_job_id":null,"html_url":"https://github.com/vesparny/fair-analytics","commit_stats":null,"previous_names":["vesparny/owt"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vesparny%2Ffair-analytics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vesparny%2Ffair-analytics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vesparny%2Ffair-analytics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vesparny%2Ffair-analytics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vesparny","download_url":"https://codeload.github.com/vesparny/fair-analytics/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248647255,"owners_count":21139081,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics","distributed","fair","ga","nodejs","p2p"],"created_at":"2024-08-01T16:02:22.217Z","updated_at":"2025-04-12T23:39:17.911Z","avatar_url":"https://github.com/vesparny.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Fair Analytics\n\n\u003e An analytics server that doesn't undermine user's privacy\n\n[![Travis](https://img.shields.io/travis/vesparny/fair-analytics.svg)](https://travis-ci.org/vesparny/fair-analytics)\n[![Code Coverage](https://img.shields.io/codecov/c/github/vesparny/fair-analytics.svg?style=flat-square)](https://codecov.io/github/vesparny/fair-analytics)\n[![David](https://img.shields.io/david/vesparny/fair-analytics.svg)](https://david-dm.org/vesparny/fair-analytics)\n[![npm](https://img.shields.io/npm/v/fair-analytics.svg)](https://www.npmjs.com/package/fair-analytics)\n[![npm](https://img.shields.io/npm/dm/fair-analytics.svg)](https://npm-stat.com/charts.html?package=fair-analytics\u0026from=2017-04-01)\n[![JavaScript Style Guide](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](http://standardjs.com/)\n[![MIT License](https://img.shields.io/npm/l/fair-analytics.svg?style=flat-square)](https://github.com/vesparny/fair-analytics/blob/master/LICENSE)\n\n## Motivations?\n\nGoogle Analytics is the de-facto standard in the web and mobile analytics service world.\n\n* It's easy to setup and start tracking users behaviors\n* It provides advanced reporting features.\n\nBut it has several serious privacy implications:\n\n* Most of the time personal data is collected without the explicit consent of the user, hence it undermines user's privacy\n* It's closed-source\n* It does not embrace transparency at all\n* Users cannot access tracked data because data ownership is granted only to the website/app owner (and sadly to Google)\n* It targets specific users and data collected is not anonymous\n\nInspired by an [interesting article](https://staltz.com/open-analytics.html) from [@staltz](https://github.com/staltz), and from the awesome work done by the [micro-analytics](https://github.com/micro-analytics/micro-analytics-cli) team, I decided to start working on a Google Analytics alternative.\n\n## What is Fair Analytics\n\nFair Analytics is an open, transparent, distributed and fair Google Analytics alternative.\n\n## Key features\n\n* **Fair** - It's meant to provide lightweight and anonymous analytics about traffic and usage, not to track behaviors nor geographical locations of users\n* **Distributed** - Raw traffic data is written in an append-only, secure, and distributed log. It uses [hypercore](https://github.com/mafintosh/hypercore) under the hood\n* **Transparent** - Raw traffic data is accessible to anyone. This makes it auditable and gives back its ownership to the crowd\n* **Easy** - It's easy to setup\n* **Flexible** - Even though Fair Analytics only stores raw data, it's pretty easy to listen to incoming events, enabling the user to manipulate/aggregate raw data in order to provide graphs or charts. Get fancy if you want to.\n\n\n## Setup\n\nThere are 2 ways of running Fair Analytics\n\n### CLI\n\n```bash\nnpm install -g fair-analytics\n\nfair-analytics\n\n```\n\nThe command accepts some options:\n\n```bash\n$ fair-analytics --help\n\n  Usage: fair-analytics [options] [command]\n\n  Commands:\n\n    help  Display help\n\n  Options:\n\n    -h, --help                       Output usage information\n    -H, --host [value]               Host to listen on (defaults to \"0.0.0.0\")\n    -m, --memory                     Use in-memory storage (disabled by default)\n    -o, --origin [value]             Accepts POST requests only from a specified origin (defaults to \"*\")\n    -p, --port \u003cn\u003e                   Port to listen on (defaults to 3000)\n    -s, --storage-directory [value]  Storage directory (defaults to process.cwd())\n    -v, --version                    Output the version number\n```\n\nThe instance is now running at `http://localhost:3000`\n\n### Programmatically\n\nAdd fair-analytics as a dependency to your project\n\n```js\nconst path = require('path')\nconst fa = require('fair-analytics')\n\nconst server = fa({\n  storageDirectory: path.resolve(__dirname)\n})\nconst { feed } = server\n\nfeed.on('ready', () =\u003e {\n  server.listen(3000, '0.0.0.0')\n})\n```\n\nThe instance is now running at `http://localhost:3000`\n\n## Deploy\n\nTODO\n\n* nginx\n* docker\n\n\n## Usage\n\n### Track events\n\nThe quickest way to start tracking usage is to use [fair-analytics-client-api](https://github.com/vesparny/fair-analytics-client-api)\n\nExample usage:\n\n```js\nimport fairAnalytics from 'fair-analytics-client-api'\n\n// create a fa instance\nconst fa = fairAnalytics({\n  url: 'https://fa.yoursite.com' // the URL of your hosted Fair Analytics instance\n})\n\n// track events\nfa.send({\n  event: 'pageView', // event is mandatory and can be anything\n  pathname: window.location.pathname\n})\n.then(res =\u003e {\n  if (res.ok) {\n    console.log('success')\n  }\n})\n.catch(err =\u003e {\n  console.error(err.message)\n})\n```\n\nPlease refer to the [fair-analytics-client-api documentation](https://github.com/vesparny/fair-analytics-client-api/#readme) for further details\n\n### Endpoints\n\nFair Analytics responds to 3 endpoints:\n\n##### GET /\n\nResponds with a basic homepage, displaying the `feed.key`\n\n##### POST /\n\nUsed to POST tracked events.\nResponds with 204 in case of success (the body MUST be an object containing at least an `event` parameter)\n\n##### GET /_live\n\nGets realtime updates via [server sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)\nUseful to create real-time dashboards\n\nConsuming real-time data is as easy as:\n\n```js\nif (window.EventSource) {\n  const source = new window.EventSource('https://fa.mysite.com/_live')\n\n  source.addEventListener('fair-analytics-event', (e) =\u003e {\n    console.log(e)\n  })\n\n  source.addEventListener('open', () =\u003e {\n    console.log('Connection was opened')\n  })\n\n  source.addEventListener('error', e =\u003e {\n    if (e.readyState === window.EventSource.CLOSED) {\n      console.log('Connection was closed')\n    }\n  })\n}\n```\n\n##### GET /_stats\n\nProvides an aggregated view of all the events stored, grouped by `event` and `pathname`\nIn this case data is persisted to a local JSON file using [lowdb](https://github.com/typicode/lowdb)\n\nHere is an example response:\n\n```json\n{  \n   \"pageView\":{  \n      \"/home\":{  \n         \"times\":640,\n         \"last\":\"2017-05-04T12:36:31.514Z\"\n      },\n      \"/about\":{  \n         \"times\":40,\n         \"last\":\"2017-05-04T12:36:31.514Z\"\n      }\n   }\n}\n```\n\n### Replicate raw data\n\nAs we said Fair Analytics is distributed.\nIt's easily possible to replicate raw data.\n\n```js\nconst hypercore = require('hypercore')\nconst swarm = require('hyperdiscovery')\nconst KEY = 'A FAIR ANALYTICS FEEED KEY'\nconst LOCALPATH = './replicated.dataset'\n\nconst feed = hypercore(LOCALPATH, KEY, {valueEncoding: 'json'})\nswarm(feed)\n\nfeed.on('ready', () =\u003e {\n  // this configuration will download all the feed\n  // and process new incoming data\n  // via the feed.on('data') callback\n  // in case you want to process all the feed (old and new)\n  // use only {tail: true, tail: true}\n\n  feed.createReadStream({\n    tail: true,\n    live: true,\n    start: feed.length,\n    snapshot: false\n  })\n  .on('data', console.log) // Use this callback to precess data as you like\n})\n```\n\n## Tests\n\n```sh\n$ npm test\n```\n\n## Change Log\n\nThis project adheres to [Semantic Versioning](http://semver.org/).  \nEvery release, along with the migration instructions, is documented in the [CHANGELOG.md](https://github.com/vesparny/fair-analytics/blob/master/CHANGELOG.md) file.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvesparny%2Ffair-analytics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvesparny%2Ffair-analytics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvesparny%2Ffair-analytics/lists"}