{"id":22994412,"url":"https://github.com/groupby/gb-tracker-client","last_synced_at":"2025-08-13T22:31:40.288Z","repository":{"id":10416809,"uuid":"65671664","full_name":"groupby/gb-tracker-client","owner":"groupby","description":"JavaScript tracker client used to beacon events to GroupBy servers. Uses first-party cookies to anonymously track shoppers.","archived":false,"fork":false,"pushed_at":"2024-12-05T17:44:06.000Z","size":1459,"stargazers_count":1,"open_issues_count":24,"forks_count":2,"subscribers_count":32,"default_branch":"develop","last_synced_at":"2025-08-09T06:44:56.722Z","etag":null,"topics":["analytics-tracking","ecommerce","javascript","typescript"],"latest_commit_sha":null,"homepage":"https://groupbyinc.com/","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/groupby.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":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-08-14T14:59:20.000Z","updated_at":"2023-07-18T09:07:29.000Z","dependencies_parsed_at":"2023-02-19T04:30:39.500Z","dependency_job_id":"421108f0-6dcf-4152-882b-3d1002072ce1","html_url":"https://github.com/groupby/gb-tracker-client","commit_stats":{"total_commits":261,"total_committers":18,"mean_commits":14.5,"dds":0.5938697318007663,"last_synced_commit":"47b412bf70bda7777336acd5c9973b6704f97844"},"previous_names":[],"tags_count":68,"template":false,"template_full_name":null,"purl":"pkg:github/groupby/gb-tracker-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/groupby%2Fgb-tracker-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/groupby%2Fgb-tracker-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/groupby%2Fgb-tracker-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/groupby%2Fgb-tracker-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/groupby","download_url":"https://codeload.github.com/groupby/gb-tracker-client/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/groupby%2Fgb-tracker-client/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269712672,"owners_count":24463209,"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","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["analytics-tracking","ecommerce","javascript","typescript"],"created_at":"2024-12-15T05:18:49.180Z","updated_at":"2025-08-13T22:31:39.931Z","avatar_url":"https://github.com/groupby.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GroupBy Tracker Client\n\n![Node.js CI badge](https://github.com/groupby/gb-tracker-client/actions/workflows/node.js.yml/badge.svg)\n![CodeQL static code analytics badge](https://github.com/groupby/gb-tracker-client/actions/workflows/codeql-analysis.yml/badge.svg)\n\nThis is the JavaScript SDK used to send beacons to GroupBy. It can only run in the browser. A bundled UMD build is available from our CDN (see GroupBy docs for CDN link) and a CommonJS build is available for linking into NPM build processes with a bundler. E.g. React, Angular.\n\n## Usage from CDN\n\nAdd the CDN `\u003cscript\u003e` to each page, above where the tracker is instantiated and used:\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml lang=\"en\"\u003e\n\u003chead\u003e\n    \u003cmeta charset=\"UTF-8\"\u003e\n    \u003cmeta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\"\u003e\n    \u003cmeta http-equiv=\"X-UA-Compatible\" content=\"ie=edge\"\u003e\n    \u003ctitle\u003eDocument\u003c/title\u003e\n    \u003cscript src=\"http://cdn.groupbycloud.com/gb-tracker-client-\u003cmajor_version\u003e.min.js\"\u003e\u003c/script\u003e\n    \u003cscript\u003e\n        var tracker = new GbTracker('customer_id', 'area');\n        tracker.autoSetVisitor();\n\n        tracker.sendAddToCartEvent({ ... });\n    \u003c/script\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n## Usage with NPM\n\nTo import and use the tracker:\n\n```javascript\nimport GbTracker from 'gb-tracker-client';\n\nconst tracker = new GbTracker('customer_id', 'area');\ntracker.autoSetVisitor();\n\ntracker.sendAddToCartEvent({ ... });\n```\n\nIf you're using TypeScript, you can also use the types for each event type. Each\nfunction has a corresponding TypeScript type that can be imported:\n\n```typescript\nimport GbTracker from 'gb-tracker-client';\nimport { AddToCartEvent } from 'gb-tracker-client/models';\n\nconst tracker = new GbTracker('customer_id', 'area');\ntracker.autoSetVisitor();\n\nconst a: AddToCartEvent = { ... };\ntracker.sendAddToCartEvent(a);\n```\n\n## Options\n\nThe constructor for the tracker client has a third, optional parameter for providing options:\n\n```typescript\nconst tracker = new GbTracker('customer_id', 'area', {\n    overrideUrl: '\u003csome_url\u003e' // Optional, overrides the URL the beacon is sent to. Useful for testing.\n});\n```\n\n## Supported event types\nList of supported event types with code examples available in [event-types.md](docs/event-types.md) file\n\n## SiteFilter support since version 5.1.1\nThis new functionality allows you to indicate which specific site or banner the tracker is running in.\n\n```typescript\nconst tracker = new GbTracker('customer_id', 'area');\ntracker.setSite('siteName');\n```\n\nThe `setSite` function will apply the given site to all beacons fired after that point.\nWhenever a `Search`, `Home page view`, `View product`, `Add to cart`, `Order`, or `Impression` beacon is fired, the site value, if it exists, will be added as part of the metadata in the request.\n\n## Shopper tracking\n\nThe first party cookie `gbi_visitorId` is set with an empiry time of 1 year that is extended each time the shopper visits again. This is used to anonymously track the shopper.\n\n### 5.0.0 changes\n\n**IMPORTANT**\n\nAs of version 5.0.0, the way shopper tracking works has changed and includes cross-domain support. Shoppers will be tracked across your domains if cross-domain rules are met (see next section). Tracking on domains whose apex domain has a two-level suffix is supported from version 5.1.2. Examples:\n\n- `.com` -  You can use version **5.0.0** or higher.\n- `.co.uk` - You can use version **5.1.2** or higher.\n\n### Cross-domain rules\n\nFor shoppers to be tracked across your domains, the domains must share the same apex domain. Examples:\n  \n- `a.example.com` and `b.example.com`\n- `a.example.com` and `example.com`\n- `example.com` and `a.example.com`\n\nStarting with version 5.1.2, many two-level domain suffixes such as `.co.uk` are also supported.\nIf your domain has a multi-level suffix that is not in the [list of supported domain suffixes](src/slds.ts), please contact support@groupbyinc.com for assistance.\n\n### Upgrading from versions 3 or 4 and visitor ID re-use\n\nIf you upgrade from 3 or 4 to 5, the visitor ID values generated by version 3 or 4 of the tracker client will be re-used. Whichever domain the shopper visits next once you start using version 5, the visitor ID generated for that domain will be re-used as the visitor ID for the apex domain, thereafter shared between each of your domains.\n\nFor example, if a shopper performed the following events, the visitor ID `abc` would be re-used:\n\n- Visits `www.example.com`, at which point version 3 or 4 sets the visitor ID to `abc`.\n- Performs a search.\n- Views a product and adds it to their cart (where they're brought to `checkout.example.com`), at which point version 3 or 4 sets the visitor ID to `bcd`.\n- Decides not to follow through with purchasing the product.\n- Waits a while, but less than a year, during which time you upgrade to version 5.\n- Visits the site again, clicks their cart (at which point version 5 replaces the visitor ID `bcd` with `abc`), and completes the purchase.\n\n## More Usage Details\n\nSee the docs for more detailed information about implementing beacons:\n\nhttps://docs.groupbycloud.com/gb-docs/gb-implementation/beacons/overview\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroupby%2Fgb-tracker-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgroupby%2Fgb-tracker-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroupby%2Fgb-tracker-client/lists"}