Neverending Pile of Messages

    TypeScript icon, indicating that this package has built-in type declarations

    5.0.0 • Public • Published

    GroupBy Tracker Client

    example workflow

    This 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.

    Usage from CDN

    Add the CDN <script> to each page, above where the tracker is instantiated and used:

    <!DOCTYPE html>
    <html lang="en">
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <meta http-equiv="X-UA-Compatible" content="ie=edge">
        <script src="<major_version>.min.js"></script>
            var tracker = new GbTracker('customer_id', 'area');
            tracker.sendAddToCartEvent({ ... });

    Usage with NPM

    To import and use the tracker:

    import { GbTracker } from 'gb-tracker-client';
    const tracker = new GbTracker('customer_id', 'area');
    tracker.sendAddToCartEvent({ ... });

    If you're using TypeScript, you can also use the types for each event type. Each function has a corresponding TypeScript type that can be imported:

    import { GbTracker } from 'gb-tracker-client';
    import { AddToCartEvent } from 'gb-tracker-client/models';
    const tracker = new GbTracker('customer_id', 'area');
    const a: AddToCartEvent = { ... };


    The constructor for the tracker client has a third, optional parameter for providing options:

    const tracker = new GbTracker('customer_id', 'area', {
        overrideUrl: '<some_url>' // Optional, overrides the URL the beacon is sent to. Useful for testing.

    Shopper tracking

    The 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.

    5.0.0 changes


    As of version 5.0.0, the way shopper tracking works has changed. It includes cross-domain support, but tracking only works on domains whose apex domain's TLD is not a second-level domain. Examples:

    • .com - You can use version 5.0.0. Shoppers will be tracked. If the cross-domain rules are met (see below), they will be tracked across your domains.
    • - You cannot use version 5.0.0. If you do, shoppers will not be tracked at all because the cookie-setting code will fail silently. You must wait for a version to be published after 5.0.0. The new version will include instructions for re-enabling shopper tracking.

    Cross-domain rules

    For shoppers to be tracked across your domains, in additional to the rule that the TLD must not be a second-level domain (see above), the domains must share the same apex domain. Examples:

    • and
    • and
    • and

    Upgrading from versions 3 or 4 and visitor ID re-use

    You should not upgrade from 3 or 4 to 5 if your apex domain's TLD is a second-level domain (see above).

    If 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.

    For example, if a shopper performed the following events, the visitor ID abc would be re-used:

    • Visits, at which point version 3 or 4 sets the visitor ID to abc.
    • Performs a search.
    • Views a product and adds it to their cart (where they're brought to, at which point version 3 or 4 sets the visitor ID to bcd.
    • Decides not to follow through with purchasing the product.
    • Waits a while, but less than a year, during which time you upgrade to version 5.
    • Visits the site again, clicks their cart (at which point version 5 replaces the visitor ID bcd with abc), and completes the purchase.

    More Usage Details

    See the docs for more detailed information about implementing beacons:


    npm i gb-tracker-client

    DownloadsWeekly Downloads






    Unpacked Size

    353 kB

    Total Files


    Last publish


    • daniil_shmtv
    • alionabutkevich
    • kv4sha
    • vladdrobovich-gb
    • kseniya.kondrashevich
    • yanishgbi
    • peterpandelidis-gbi
    • itwalton
    • ivan_siliconmint
    • soodsagar-gbi
    • welkie
    • satheesb
    • jasonwelsh
    • groupby-ops
    • groupby-ci
    • groupbyops
    • daniel-moniz-gbi
    • chantaldesrochersgroupbyinc
    • rcooper102
    • johanntutorgbi
    • dmytro-kyiashko
    • groupbyinc_dmitry
    • roman.lis
    • ant-siliconmint
    • dark_elena