Samhub JavaScript SDK

Overview

Samhub.js is a simple, lightweight JavaScript SDK designed to interact with the Samhub tracking API. This SDK supports both modern JavaScript module bundlers (like Webpack, Rollup) and traditional browser-based <script> tags.

Github Repository

https://github.com/brainnordic/samhub-js

Documentation

https://brainnordic.github.io/samhub-js/

Installation options

1. Install via NPM

npm install samhub.js

2. Include via CDN

You can directly use the SDK from a samhub CDN in a browser:

<script async src="https://cdn.samhub.io/npm/samhub.js@1/dist/samhub.js"></script>

3. Host sdk on your server

If your security requirements doesn't allow to load external resources, you may include compiled samhub.js copy from your server.

<script async src="dist/samhub.js"></script>

Usage

In Browser (Using IIFE format) - recommended for best compatibility

You can use the SDK directly in your HTML file. Just include the script tag and initialize it with your container ID:

<script async src="https://cdn.samhub.io/npm/samhub.js@1/dist/samhub.js"></script>
<script>
  window.samhubData=window.samhubData || [];
  window.samhubData.push(["init", "data-container-id"])
  window.samhubData.push(["track", "page_view"]) // track standard page view event

  window.samhubData.push(["track", "page_view", {
    url: 'http://example.com/page/about?utm_campaign=newsletter_summer',
    user_id: CRM.curent_user_id
  }]) // track page view with custom data

  window.samhubData.push(["track", "purchase", {
    user_id: "123abc456def",
    timestamp: 1742403361177,
    ced: {
      conversion_value: 150.0,
      conversion_currency: "USD",
      user_segment: "premium"
    }
  }]) // track custom event
</script>

In Modern JavaScript Bundlers (Using ESM format)

If you're using a module bundler like Webpack, Rollup, or just modern JavaScript with <script type="module">:

import { Samhub, VERSION } from 'samhub.js';

const sdk = new Samhub.Tracker("data-container-id");
tracker.track('page_view') // track standard page view event

tracker.track("purchase", {
  user_id: "123abc456def",
  timestamp: 1742403361177,
  ced: {
    conversion_value: 150.0,
    conversion_currency: "USD",
    user_segment: "premium"
  }
}) // track custom event

UserId cookie

By default SDK uses first party UUID cookie to track users. The cookie is set to expire in 365 days.

• cookie_name: samhub
• cookie_expires: 365 days

You may want to change cookie storage to localStorage instead. With constructor option:

  window.samhubData=window.samhubData || [];
  window.samhubData.push(["init", "data-container-id", {
    auto_track_user_id: 'localstorage'
  }])

You may also want to disable cookie storage completely and provide user id manually:

  window.samhubData=window.samhubData || [];
  window.samhubData.push(["init", "data-container-id", {
    auto_track_user_id: 'none'
  }])
  window.samhubData.push(["track", "page_view", {
    user_id: "123abc456def"
  }])

CSP - content security policy

Browser installation requires CSP to be configured. As SDK by default uses 1x1 pixel image as data protocol, you need to allow it in your CSP policy.

img-src https://*.track.samhub.io;

Notice: If you're using custom tracking domain, you need to allow it instead.

If you are loading samhub.js from CDN you will need also add CSP rule for script:

script-src https://cdn.samhub.io;

External dependencies

• uuid - used to generate user id (until disabled)
• qs - used to serialize pixel data
• js-cookie - used to store user id in cookie (until disabled)

SDK API Reference

Samhub.Tracker

Methods

• init(containerId: string, options?: TrackerOptions) - initialize the SDK
• track(eventName: string, eventData: EventData = {}) - track event

Methods (global window.samhubData interface)

• window.samhubData=window.samhubData || []; - initialize data layer
• window.samhubData.push(["init", containerId?: string, options?: TrackerOptions]) - initialize the SDK
• window.samhubData.push(["track", eventName: string, eventData: EventData = {}]) - track event

Types

TrackerOptions = {
  api_url?: string; // defaults to 'https://eu.track.samhub.io/v1/e.gif'
  auto_track_user_id?: 'cookie' | 'localstorage' | 'none'; // defaults to 'cookie' - if `none` is set, user id must be provided
  auto_track_referrer?: boolean; // defaults to true
  auto_track_session?: boolean; // defaults to true (use session storage to store session id)
  auto_track_url?: boolean;  // defaults to true (parses current browser url and extract domain, path, utm_source, utm_medium, utm_campaign)
  debug?: (...args: any) => void; // debug function, e.g. debug: console.log, disabled by default
}

EventData = {
  name: string; // event name
  url?: string; // used to extract domain, path, utm_source, utm_medium, utm_campaign, default to current browser url if auto_track_url is enabled
  path?: string; // event path - default to current browser path
  host?: string; // event domain - default to current browser domain
  zipcode?: string; // user zipcode - default to current browser zipcode resolved from ip
  ip?: string; // user ip - default to current browser ip
  utm_source?: string; // utm_source, default: utm_source  from current url
  utm_medium?: string; // utm_medium, default: utm_medium from current url
  utm_campaign?: string; // utm_campaign, default: utm_campaign from current url
  referrer?: string; // event referrer, default to current page referrer
  timestamp?: number; // event timestamp, default to current timestamp
  event_id?: string; // unique event id, default to uuid, only recent event with the same id will be tracked
  user_id?: string; // user id, default to uuid stored in samhub cookie
  session_id?: string; // session id, default to uuid stored in session storage
  ced?: { // custom event data, do not provide PII here
    [key: string]: string | number;
  };
}

Development

Setup

1. Clone this repository:

   git clone [email protected]:brainnordic/samhub-js.git
   cd samhub-js

2. Install dependencies:

   npm install

3. Build the SDK:

   npm run build

Linting

We use ESLint to enforce code quality. To run the linting process:

npm run lint

To fix automatically fixable issues:

npm run lint:fix

Testing

Run tests with:

npx jest

Documentation

Generate full documentation with:

npx typedoc

Publishing

To publish the SDK to npm, ensure you have the correct permissions and run:

npm publish

Contributing

1. Fork the repository.
2. Create a feature branch (git checkout -b feature-name).
3. Commit your changes (git commit -m 'Add feature').
4. Push to the branch (git push origin feature-name).
5. Open a Pull Request.

License

Distributed under the MIT License. See LICENSE for more information.