@contactlab/sdk-browser
Advanced tools
Changelog
Readme
Browser SDK for the Contacthub API.
The easiest way to send pageviews, events and customer information from your website to the Contacthub API.
Insert this snippet in your website (preferably in the <HEAD> section):
<script>
window.ch=function(){(ch.q=ch.q||[]).push(arguments)};
ch('config', {/* see below */});
ch('customer', {/* see below */});
ch('event', {/* see below */});
</script>
<script async src='https://assets.contactlab.it/contacthub/sdk-browser/latest/contacthub.min.js'></script>
Compressed and uncompressed copies of Contacthub Analytics JS files are available. The uncompressed file is best used during development or debugging; the compressed file saves bandwidth and improves performance in production. Use CDNs can offer a performance benefit by hosting Contacthub Analytics JS on servers spread across the globe. This also offers an advantage that if the visitor to your webpage has already downloaded a copy of Contacthub Analytics JS from the same CDN, it won't have to be re-downloaded.
To load a hosted library, copy and paste the HTML snippet for that library (shown below) in your web page.
<script async src="https://assets.contactlab.it/contacthub/sdk-browser/latest/contacthub.min.js"></script>
<script async src="https://assets.contactlab.it/contacthub/sdk-browser/latest/contacthub.js"></script>
<script async src="https://assets.contactlab.it/contacthub/sdk-browser/{version}/contacthub.min.js"></script>
<script async src="https://assets.contactlab.it/contacthub/sdk-browser/{version}/contacthub.js"></script>
We recommend that you load libraries from the CDN via HTTPS, even if your own website only uses HTTP
ch('config', {
workspaceId: 'w_id', // required, found in the ContactHub admin area
nodeId: 'node_id', // required, found in the ContactHub admin area
token: 'UYTF546FUTF636JH', // required, found in the ContactHub admin area
context: 'CTX' // optional, defaults to 'WEB'
});
Include this call only if you have details about the current user (e.g. the user is logged in).
ch('customer', {
externalId: '456', // optional
base: {
firstName: 'Mario',
lastName: 'Rossi',
contacts: {
email: 'mario.rossi@example.com'
}
},
extended: {}, // optional
extra: '', // optional
tags: { //optional
auto: [],
manual: []
}
});
If you have defined a matching policy in the ContactHub web interface, and the data you're providing matches the data of an existing customer, the existing customer will be updated instead.
It's safe to call this function multiple times with the same data (e.g. in the HEAD section of all of your pages) as an encrypted hash of this data is stored in a cookie and won't be resent to the API if no value has changed.
You can also call this function the moment a user succesfully logs in, if the login action doesn't involve a page refresh.
If a user adds some personal information to his/her profile, you don't need to send his full profile again, as the new data you send will be automatically merged with the data that is already available on the ContactHub database.
// Add the mobile phone to the existing customer data
ch('customer', {
base: {
contacts: {
mobilePhone: '+393331234567'
}
}
});
If a user logs out, you might want to stop linking events to his/her session.
You can call ch('customer') without the second parameter and a new ContactHub
session id will be generated. All the events from this point will be associated
to the new session id and will not be linked to the previous user.
ch('event', {
type: '<eventType>', // a valid event type, e.g. 'viewedPage'
properties: {} // optional Properties object (eventType dependent)
});
Please note we will infer some standard properties automically (url, title,
referrer, path). If you want, you can override those in your custom properties
object.
This script will register a global variable in your window object called ch.
This is similar for example to the ga global variable used by Google
Analytics. If for any reason you already have a global variable called ch in
your website, you can ask ContactHub to use a different name. Simply add this
line before the standard ContactHub snippet:
window.ContactHubObject = 'chub';
You also have to replace all occurrences of ch in the snippet:
<script>
window.chub=function(){(chub.q=chub.q||[]).push(arguments)};
chub('config', { ... });
chub('customer', { ... });
chub('event', { ... });
</script>
<script async src='https://www.contactlab.com/contacthub.js'></script>
In the same way, you can set a custom name for the ContactHub cookie using:
window.ContactHubCookie = '__chub';
For testing or debugging purposes, you might want to use a different API server:
window.ContactHubAPI = 'https://test-api/hub/v2';
npm run build will generate dist/contactlab.js and dist/contactlab.min.js.
npm test will run all tests once using PhantomJS
npm test-watch will automatically re-run tests using PhantomJS on every change
BROWSERSTACK_USER=<user> BROWSERSTACK_KEY=<key> npm test-bs will run tests
on real browsers using BrowserStack. The list of browsers is statically defined
in package.json and karma.conf.js
npm run example will start a local HTTP server and open the example page in
your local browser. Replace the placeholders in the query string with your
authorization token and ids. Remember also to add http://127.0.0.1.xip.io to
the allowed URLs for your Source in the ContactHub web interface (under
Settings, Sources, {source name}, Settings).
FAQs
Contactlab Browser SDK
The npm package @contactlab/sdk-browser receives a total of 379 weekly downloads. As such, @contactlab/sdk-browser popularity was classified as not popular.
We found that @contactlab/sdk-browser demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket CEO Feross Aboukhadijeh joins a16z partners to discuss how modern, sophisticated supply chain attacks require AI-driven defenses and explore the challenges and solutions in leveraging AI for threat detection early in the development life cycle.
Security News
NIST's new AI Risk Management Framework aims to enhance the security and reliability of generative AI systems and address the unique challenges of malicious AI exploits.
Security News
This episode of the Risky Biz podcast discusses how the rise of small open source packages and the shift towards individual maintainers makes the ecosystem more vulnerable to supply chain attacks.