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.
https://github.com/brainnordic/samhub-js
https://brainnordic.github.io/samhub-js/
npm install samhub.js
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>
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>
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>
Then in your app code initialize the SDK and track events:
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
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
By default SDK uses first party UUID cookie to track users. The cookie is set to expire in 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"
}])
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;
If you are executing samhub api from inline script, you will need to nonce it in your CSP policy.
script-src 'nonce-<random-nonce-value-server-generated>';
<script nonce="<random-nonce-value-server-generated>">
window.samhubData=window.samhubData || [];
window.samhubData.push(["init", "data-container-id"])
window.samhubData.push(["track", "page_view"])
</script>
init(containerId: string, options?: TrackerOptions) - initialize the SDKtrack(eventName: string, eventData: EventData = {}) - track eventwindow.samhubData=window.samhubData || []; - initialize data layerwindow.samhubData.push(["init", containerId?: string, options?: TrackerOptions]) - initialize the SDKwindow.samhubData.push(["track", eventName: string, eventData: EventData = {}]) - track eventTrackerOptions = {
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;
};
}
Clone this repository:
git clone git@github.com:brainnordic/samhub-js.git
cd samhub-js
Install dependencies:
npm install
Build the SDK:
npm run build
We use ESLint to enforce code quality. To run the linting process:
npm run lint
To fix automatically fixable issues:
npm run lint:fix
Run tests with:
npm run test
Generate full documentation with:
npx typedoc
To publish the SDK to npm, ensure you have the correct permissions and run:
npm publish
git checkout -b feature-name).git commit -m 'Add feature').git push origin feature-name).Distributed under the MIT License. See LICENSE for more information.