{"id":20365984,"url":"https://github.com/altcha-org/tracker","last_synced_at":"2026-01-20T09:33:33.660Z","repository":{"id":257821777,"uuid":"863971568","full_name":"altcha-org/tracker","owner":"altcha-org","description":"JavaScript client for ALTCHA Analytics.","archived":false,"fork":false,"pushed_at":"2024-10-14T02:19:10.000Z","size":68,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-12T07:16:28.039Z","etag":null,"topics":["altcha","analytics"],"latest_commit_sha":null,"homepage":"https://altcha.org/","language":"TypeScript","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/altcha-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-09-27T08:54:19.000Z","updated_at":"2025-04-04T02:11:34.000Z","dependencies_parsed_at":null,"dependency_job_id":"a1f8f821-8306-4104-8320-0cf459aaa6f3","html_url":"https://github.com/altcha-org/tracker","commit_stats":null,"previous_names":["altcha-org/tracker"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/altcha-org/tracker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altcha-org%2Ftracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altcha-org%2Ftracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altcha-org%2Ftracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altcha-org%2Ftracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/altcha-org","download_url":"https://codeload.github.com/altcha-org/tracker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/altcha-org%2Ftracker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28600621,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T08:51:33.170Z","status":"ssl_error","status_checked_at":"2026-01-20T08:51:10.855Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["altcha","analytics"],"created_at":"2024-11-15T00:21:35.573Z","updated_at":"2026-01-20T09:33:33.654Z","avatar_url":"https://github.com/altcha-org.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ALTCHA Analytics Tracker\n\nThis repository contains the front-end library for collecting analytics data with ALTCHA Analytics.\n\n## Why ALTCHA Analytics?\n\nALTCHA Analytics provides a privacy-first, GDPR-compliant alternative to traditional analytics platforms like Google Analytics. Unlike most other services, it operates without cookies or fingerprinting, ensuring that all data is anonymized by default.\n\n**Key Features**:\n- Compliant with GDPR, CCPA, and PECR regulations\n- No cookies or fingerprinting required\n- Flexible: Use for web, app, or API analytics\n- Customizable event tracking and properties\n- Lightweight (~4kB gzipped)\n\n## Installation \u0026 Usage\n\nYou can integrate ALTCHA Analytics in two ways:\n\n1. **Module** (Recommended for modern frameworks such as React, Vue, Angular)\n2. **Script Tag** (Simple HTML inclusion)\n\n### 1. Module Installation (Preferred for Frameworks)\n\nInstall via npm:\n\n```bash\nnpm install @altcha/tracker\n```\n\nInitialize the tracker in your app:\n\n```javascript\nimport { Tracker } from '@altcha/tracker';\n\nconst tracker = new Tracker({\n  projectId: 'pro_...',\n});\n```\n\n### 2. Script Tag Integration\n\nSimply add the following snippet to your HTML:\n\n```html\n\u003cscript\n  defer\n  data-project-id=\"pro_...\"\n  src=\"https://eu.altcha.org/js/script.js\"\n\u003e\u003c/script\u003e\n```\n\nMake sure to replace `\"pro_...\"` with your unique `projectId`.\n\n## Configuration\n\nThe `Tracker` class constructor accepts the following configuration options:\n\n- **`allowSearchParams?: string[]`** – By default, the script removes all query parameters (those after `?` in the URL). Use this option to whitelist specific parameters that should be tracked.\n- **`apiUrl?: string`** – Override the default API URL for reporting events.\n- **`appVersion?: string`** – Track the version of your application (max 12 characters).\n- **`click?: IBaseExtensionOptions | boolean`** – Disable or configure the `click` extension (see below for details).\n- **`cookie?: ICookieExtensionOptions | boolean`** – Disable or configure the `cookie` extension.\n- **`debug?: boolean`** – Enable debug mode for logging.\n- **`globalName?: string | null | false`** – Override the default global variable name for the Tracker instance. Set to `null` to skip global registration.\n- **`hash?: IBaseExtensionOptions | boolean`** – Disable or configure the `hash` extension.\n- **`keyboard?: IBaseExtensionOptions | boolean`** – Disable or configure the `keyboard` extension.\n- **`mouse?: IBaseExtensionOptions | boolean`** – Disable or configure the `mouse` extension.\n- **`projectId: string`** – Required ALTCHA project ID (format: `pro_{unique_id}`).\n- **`pushstate?: IBaseExtensionOptions | boolean`** – Disable or configure the `pushstate` extension.\n- **`respectDnt?: boolean`** – When `true`, the tracker will not report any events if the user's browser is configured with `Do Not Track` or `globalPrivacyControl`.\n- **`uniqueId?: string`** – Provide the user's unique ID, if applicable, to track returning visitors.\n- **`visibility?: IVisibilityExtensionOptions | boolean`** – Disable or configure the `visibility` extension.\n\nThese options can also be provided as attributes in the `\u003cscript\u003e` tag, for example: `data-project-id=\"pro_...\"`.\n\n### Example Configuration:\n\n```javascript\nnew Tracker({\n  projectId: 'pro_...',\n  appVersion: 'v1.0.1',\n  debug: true,\n  respectDnt: true,\n  allowSearchParams: ['page_id'],\n});\n```\n\n### HTML Example Configuration:\n\n```html\n\u003cscript\n  defer\n  data-project-id=\"pro_...\"\n  data-app-version=\"v1.0.1\"\n  data-debug=\"true\"\n  data-respect-dnt=\"true\"\n  src=\"https://eu.altcha.org/js/script.js\"\n\u003e\u003c/script\u003e\n```\n\n## Extensions\n\nTracking features are provided through \"extensions,\" which can be individually enabled or disabled depending on your needs and privacy concerns.\n\n### Click\n\nEnabled by default.  \n\nTracks user mouse/pointer interactions, detecting exit events and outbound links.\n\n### Cookie\n\nDisabled by default.  \n\nThe `cookie` extension tracks returning visitors by setting a small cookie (`_altcha_visited=1`) that expires in 30 days.\n\nYou can configure this extension with the following options:\n\n```js\nnew Tracker({\n  projectId: '...',\n  cookie: {\n    // Cookie expiration in days\n    cookieExpireDays: 30,\n    // Cookie name\n    cookieName: '_altcha_visited',\n    // Cookie path (defaults to '/')\n    cookiePath: '/',\n  }\n})\n```\n\nNote: Enabling this extension may require user consent under GDPR.\n\n### Filter\n\nEnabled by default.\n\nEvent filtering allows you to exclude events based on the user-agent, hostname, or a custom filter function. This helps you ensure only relevant events are tracked.\n\nBy default, the filtering extension ignores:\n\n- Bots and crawlers.\n- Private hostnames such as `localhost`, `127.0.0.1`, and `*.local`.\n\nYou can also manually prevent your own events from being tracked by setting `localStorage.altcha_ignore=true` in the browser.\n\n```js\nnew Tracker({\n  projectId: '...',\n  filter: {\n    // Set to true to allow reporting of events made by bots and crawlers (default: false).\n    allowBots: true,\n    \n    // A custom function for additional event filtering. \n    // Return `false` to ignore the event, or `undefined` to continue with the built-in checks.\n    checkFn: (event) =\u003e {\n      return false;  // Example: Ignore all events.\n    },\n    \n    // An array of hostnames to ignore from tracking.\n    // Override the default list of private hostnames.\n    hostnames: ['localhost'],\n  }\n});\n```\n\n### Hash\n\nDisabled by default.  \n\nTracks the `#hash` part of the URL when using hash-based routing in your application.\n\n### Keyboard\n\nEnabled by default.  \n\nDetects exit events triggered by keyboard shortcuts (e.g., closing the tab).\n\n### Mouse\n\nEnabled by default.  \n\nDetects exit events triggered by pointer (e.g., closing the tab using the mouse).\n\n### PushState\n\nEnabled by default.  \n\nAutomatically detects pageviews when `history.pushState()` is called. If disabled, use `.trackPageview()` or `.trackEvent()` to manually report events.\n\n### Visibility\n\nEnabled by default.  \n\nTracks exit events when the tab/window is hidden during page unload.\n\n## Implementation Details\n\nThis script reports collected events in bulk when the page unloads, using the [`sendBeacon()`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/sendBeacon) function. You can configure the API endpoint via the `apiUrl` option.\n\n### Exit Events\n\nExit events are reported when the user leaves the website (e.g., by closing the tab or navigating elsewhere).  \nTo track these events accurately, ensure the following extensions are enabled: `click`, `keyboard`, `mouse`, `visibility`. Disabling these will reduce the accuracy of visit duration data.\n\n### Respect for Privacy (Do Not Track)\n\nIf you respect users' privacy preferences and want to disable tracking when `Do Not Track` is enabled in the browser, you can set the `respectDnt` option to `true`.\n\n```javascript\nnew Tracker({\n  projectId: '...',\n  respectDnt: true, // disable tracking for users with Do Not Track enabled\n});\n```\n\n### Debug Mode\n\nEnabling `debug` mode logs additional information to the browser console, which is helpful for development purposes.\n\n```javascript\nnew Tracker({\n  projectId: '...',\n  debug: true, // enable debug logging\n});\n```\n\n## API Reference\n\nThe following is a quick overview of the main methods available in the ALTCHA Analytics tracker:\n\n- `trackPageview(event: IEvent, unload: boolean = false)`: Track page views.\n- `trackEvent(event: IEvent, unload: boolean = false)`: Track custom events.\n- `destroy()`: Destroys the tracker instance.\n\n### Types\n\nFor TypeScript types and interfaces, see [/src/types.ts](/src/types.ts).\n\n\n## License\n\nALTCHA Analytics is licensed under the MIT License. See the `LICENSE` file for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faltcha-org%2Ftracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faltcha-org%2Ftracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faltcha-org%2Ftracker/lists"}