{"id":24449187,"url":"https://github.com/codeniko/simple-tracker","last_synced_at":"2025-04-13T00:11:24.158Z","repository":{"id":57361050,"uuid":"131745237","full_name":"codeniko/simple-tracker","owner":"codeniko","description":"Easy client-side tracking library to log events, metrics, errors, and messages","archived":false,"fork":false,"pushed_at":"2018-10-10T06:46:26.000Z","size":96,"stargazers_count":25,"open_issues_count":0,"forks_count":7,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-03-26T18:11:13.154Z","etag":null,"topics":[],"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/codeniko.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2018-05-01T17:58:00.000Z","updated_at":"2024-05-05T22:41:45.000Z","dependencies_parsed_at":"2022-09-06T22:21:00.421Z","dependency_job_id":null,"html_url":"https://github.com/codeniko/simple-tracker","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeniko%2Fsimple-tracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeniko%2Fsimple-tracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeniko%2Fsimple-tracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeniko%2Fsimple-tracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codeniko","download_url":"https://codeload.github.com/codeniko/simple-tracker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248589784,"owners_count":21129680,"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":[],"created_at":"2025-01-21T00:37:36.798Z","updated_at":"2025-04-13T00:11:24.139Z","avatar_url":"https://github.com/codeniko.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Simple Tracker\n===============\n[![NPM version](https://img.shields.io/npm/v/simple-tracker.svg)](https://npmjs.org/package/simple-tracker)\n[![Build Status](https://travis-ci.com/codeniko/simple-tracker.svg?branch=master)](https://travis-ci.com/codeniko/simple-tracker)\n[![codecov](https://codecov.io/gh/codeniko/simple-tracker/branch/master/graph/badge.svg)](https://codecov.io/gh/codeniko/simple-tracker)\n![gzip size](http://img.badgesize.io/https://unpkg.com/simple-tracker@latest/dist/simple-tracker.min.js?compression=gzip)\n[![dependencies](https://david-dm.org/codeniko/simple-tracker.svg)](https://david-dm.org/codeniko/simple-tracker)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/codeniko/simple-tracker/blob/master/LICENSE)\n\nEasy client-side tracking library to log events, metrics, errors, and messages. Send data to any server endpoint for log management and event tracking services like Google Analytics, Splunk, ELK/Logstash, Loggly, Open Web Analytics, etc...\n\nYou can make use of Simple Tracker one of two ways. You can install through [npm and use it as a module](#installation-through-npm-as-module), or you can [include the uglified script file in your HTML page](#installation-in-html).\n\nInspiration\n------------\nIf you run an adblocker or a trackerblocker plugin in your browser, page requests to google analytics and other well known tracking libraries get blocked causing you to lose valuable metrics/logs from your websites. To circumvent these blockers, you'd have to write some javascript on your pages to send tracking data to an endpoint that won't be blocked and configure a server or cloud function to proxy this data to a service of your choice. Simple Tracker is the first piece to that solution. It's a light-weight client library that makes sending tracking data simple.\n\nIf you're looking to connect your tracking data sent from Simple Tracker to a cloud function, [check out these example AWS Lambda functions](examples/server-examples) which proxies the data to a free log management service called [Loggly](https://www.loggly.com/).\n\n\nInstallation through NPM as module\n------------\nIn command line, run:\n```sh\nnpm install simple-tracker\n```\nIn code:\n```javascript\nimport tracker from 'simple-tracker' // or const tracker = require('simple-tracker')\n\n// initialize tracker endpoint and settings\ntracker.push({\n  endpoint: '/endpoint', // Endpoint to send tracking data to\n  attachClientContext: true, // Attach various client context, such as useragent, platform, and page url\n});\n```\n\nYou only need to initialize endpoint and settings as above once. After initializing, simply import `tracker` in other modules or components:\n```javascript\nimport tracker from 'simple-tracker' // or const tracker = require('simple-tracker')\n\ntracker.push({ event: 'pageview' })\n```\nHere is a live example page: [https://codeniko.github.io/simple-tracker/examples/all-functions.html](https://codeniko.github.io/simple-tracker/examples/all-functions.html)\n\n\nInstallation in HTML\n------------\nPlace the following on your page. While you can use the script at the [CDN link](https://unpkg.com/simple-tracker@latest/dist/simple-tracker.min.js) below, I recommend you to download the script and host it yourself.\n```html\n\u003cscript type=\"text/javascript\" src=\"https://unpkg.com/simple-tracker@latest/dist/simple-tracker.min.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  // initialize tracker endpoint and settings\n  tracker.push({\n    endpoint: '/endpoint', // Endpoint to send tracking data to\n    attachClientContext: true, // Attach various client context, such as useragent, platform, and page url\n  });\n\u003c/script\u003e\n```\n\nHere is a live example page: [https://codeniko.github.io/simple-tracker/examples/all-functions.html](https://codeniko.github.io/simple-tracker/examples/all-functions.html)\n\nQuick Usage\n-----\nLogging text:\n```javascript\ntracker.push('some text to track');\n```\n\nLogging JSON:\n```javascript\ntracker.push({\n  message: 'my tracking string',\n  values: [1, 2, 3, 'a', 'b', 'c']\n});\n```\n\nThis will send a POST request containing a sessionId, and client context if enabled (enabled by default). An example request payload:\n```json\n{\n  \"sessionId\": \"11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000\",\n  \"message\": \"my tracking string\",\n  \"values\": [1, 2, 3, \"a\", \"b\", \"c\"],\n  \"context\": {\n    \"url\": \"https://nfeld.com/\",\n    \"userAgent\": \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36\",\n    \"platform\": \"MacIntel\"\n  }\n}\n```\n\nThere are also several convenience functions defined to push common tracking data such as `tracker.logEvent(event)`, `tracker.logMessage('message')`, and `tracker.logMetric('metric', 'value')`. [You can find examples of these and more below.](#tracker-functions)\n\nSession Id\n-----\nSimple Tracker makes use of cookies to persist the sessionId that accompanies all tracking data. If the sessionId is not explicitly set in [configuration](#all-configurations), one will be generated as a UUIDv4 string. Regardless if explicitly set or generated, the sessionId will be stored in a cookie named `trcksesh` and will be destroyed when session ends (browser closes)\n\nAll configurations\n-----\n```javascript\ntracker.push({\n  endpoint: '/endpoint', // Endpoint to send tracking data to\n  sessionId: 'SESSION_ID', // Explicitly set a session id\n  sendCaughtExceptions: true/false, // Send exceptions caught by browser. DEFAULT: false\n  attachClientContext: true/false, // Attach client context to requests. Includes: useragent, platform, and page url. DEFAULT: true\n  attachSessionId: true/false, // Attach sessionId to requests. DEFAULT: true\n  devMode: true/false // Toggle dev mode. If enabled, outgoing requests are blocked and logged for debugging instead. DEFAULT: false\n});\n```\n\nAdding to client context object\n-----\nYou can add your own values to persist inside of the client context object, or even overwrite the object entirely. You can access the object with `tracker.clientContext`. Any values you add to the clientContext object will go out on every tracking request\n```javascript\n// assign more values\ntracker.clientContext.username = 'codeniko',\ntracker.clientContext.location = 'San Francisco, CA'\n\n// overwriting context entirely\ntracker.clientContext = {\n  username = 'codeniko',\n  location = 'San Francisco, CA'\n}\n```\n\nTracker functions\n-----\nHere is a live example page showing all of the convenience functions:  \n[https://codeniko.github.io/simple-tracker/examples/all-functions.html](https://codeniko.github.io/simple-tracker/examples/all-functions.html)\n\n`logEvent(event, additionalParams)`: Log an event that occurred, with optional additionalParams\n```javascript\ntracker.logEvent('contact_form_submitted', { name: 'niko', fromEmail: 'niko@nfeld.com' });\n\n// Request: POST /endpoint\n{\n  \"type\": \"event\",\n  \"event\": \"contact_form_submitted\",\n  \"sessionId\": \"11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000\",\n  \"name\": \"niko\",\n  \"fromEmail\": \"niko@nfeld.com\"\n}\n```\n\n`logMessage(message, optionalLevel)`: Log simple message, with optional level as second argument\n```javascript\ntracker.logMessage('some message', 'info');\n\n// Request: POST /endpoint\n{\n  \"type\": \"message\",\n  \"message\": \"some message\",\n  \"level\": \"info\",\n  \"sessionId\": \"11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000\"\n}\n```\n\n`logException(exceptionObject)`: Log exceptional error. Can pass an exception object, or other value\n```javascript\ntracker.logException(new Error('some exception').stack);\n\n// Request: POST /endpoint\n{\n  \"type\": \"exception\",\n  \"level\": \"error\",\n  \"exception\": \"Error: some exception at \u003canonymous\u003e:1:1\",\n  \"sessionId\": \"11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000\"\n}\n```\n\n`logMetric(metricKey, metricValue)`: Log a metric and its value\n```javascript\ntracker.logMetric('page_load_time', 254);\n\n// Request: POST /endpoint\n{\n  \"type\": \"metric\",\n  \"metric\": \"page_load_time\",\n  \"value\": 254,\n  \"sessionId\": \"11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000\"\n}\n```\n\nStart/stop a timer to record a metric  \n`startTimer(metricKey)`: Start a timer named by metricKey  \n`stopTimer(metricKey, metricValue)`: Stop timer named metricKey and log result in millis as metric value\n```javascript\ntracker.startTimer('page_load_time');\n// wait 1 second\ntracker.stopTimer('page_load_time');\n\n// Request: POST /endpoint\n{\n  \"type\": \"metric\",\n  \"metric\": \"page_load_time\",\n  \"value\": 1000,\n  \"sessionId\": \"11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000\"\n}\n```\n\n`push(dataObject)`: Push any data of your choice\n```javascript\ntracker.push({\n  message: 'my tracking string',\n  values: [1, 2, 3, 'a', 'b', 'c'],\n  userMap: {\n    codeniko: 1234,\n    chance: 8888\n  }\n});\n\n// Request: POST /endpoint\n{\n  \"message\": \"my tracking string\",\n  \"values\": [1, 2, 3, \"a\", \"b\", \"c\"],\n  \"userMap\": {\n    \"codeniko\": 1234,\n    \"chance\": 8888\n  },\n  \"sessionId\": \"11bf5b37-e0b8-42e0-8dcf-dc8c4aefc000\"\n}\n```\n\nExamples out in production\n-----\nYou can find Simple Tracker used on the following websites. For some fun, ensure your adblocker is enabled, open up devtool console, refresh/navigate the pages and observe network requests to `/ga` for google analytics pageviews and `/track` for log messages.  \n[https://jessicalchang.com](https://jessicalchang.com)  \n[https://nfeld.com](https://nfeld.com)\n\n\nBugs, feature requests, \u0026 contributing\n-----\nIf you found a bug or want to request a feature, [create a new issue](https://github.com/codeniko/simple-tracker/issues). Contributions via pull requests are more than welcome :)\n\nRunning unit tests and code coverage\n----------\n```sh\nnpm test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeniko%2Fsimple-tracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodeniko%2Fsimple-tracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeniko%2Fsimple-tracker/lists"}