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;
};
}
Samhub.js includes a powerful Identity Graph (IdGraph) system with three levels of browser fingerprinting modules for device identification and user tracking.
const idGraph = new Samhub.IdGraph('my-container', {
modules: ['fingerprint_basic']
});
const idGraph = new Samhub.IdGraph('my-container', {
modules: ['fingerprint_advanced']
});
const idGraph = new Samhub.IdGraph('my-container', {
modules: ['fingerprint_complex'],
sampling: 0.1 // Only run for 10% of users
});
The IdGraph system supports various identification modules:
1stparty_cookie - First-party cookie tracking3rdparty_cookie - Third-party cookie trackingauth_session - Authentication session detectionbrowser_info - Browser and device information (37 signals)network_info - Network characteristicsutm_params - UTM parameter trackingad_tech_ids - NEW Ad tech platform detection and ID extraction (Prebid, GPT, universal IDs, bidder IDs)fingerprint_basic - Basic browser fingerprintingfingerprint_advanced - Advanced fingerprinting with FingerprintJSfingerprint_complex - Complex experimental fingerprintingconst idGraph = new Samhub.IdGraph('my-app', {
api_url: 'https://analytics.example.com/pixel.gif',
modules: [
'1stparty_cookie',
'browser_info',
'fingerprint_advanced'
],
sampling: 1.0, // Track 100% of users
debug: true
});
// Add custom signals
idGraph.addCustomSignal({
name: 'user_segment',
value: 'premium',
hashed: false
});
// Signals are automatically flushed to API
// Or manually flush: idGraph.flushSignals();
For detailed information about modules, see:
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.