The build script (bin/build.sh) can be used to configure several aspects of the SDK:
The global export that the SDK is exported on. This is kept consistent between the full source and the loader's stub.
> bin/build.sh --GLOBAL=AlternateSDK
var sdk = new AlternateSDK()
The filename to be output, in both full and minified code. This is largely a convenience, and defaults to td
> bin/build.sh --FILENAME=foo
...
> ls dist/
foo.js foo.min.js loader.min.js
The URL of the hosted file. This will be defaulted to the URL for the Treasure Data CDN-hosted file.
> bin/build.sh --URL=//cdn.yourdomain.com/sdk/foo.min.js
Install td-js-sdk on your page by copying the appropriate JavaScript snippet below and pasting it into your page's <head> tag:
<script type="text/javascript">
!function(t,e){if(void 0===e[t]){e[t]=function(){e[t].clients.push(this),this._init=[Array.prototype.slice.call(arguments)]},e[t].clients=[];for(var r=function(t){return function(){return this["_"+t]=this["_"+t]||[],this["_"+t].push(Array.prototype.slice.call(arguments)),this}},s=["addRecord","fetchGlobalID","set","trackEvent","trackPageview","trackClicks","ready"],a=0;a<s.length;a++){var c=s[a];e[t].prototype[c]=r(c)}var n=document.createElement("script");n.type="text/javascript",n.async=!0,n.src=("https:"===document.location.protocol?"https:":"http:")+"//cdn.treasuredata.com/sdk/2.0/td.min.js";var i=document.getElementsByTagName("script")[0];i.parentNode.insertBefore(n,i)}}("Treasure",this);
</script>
Does not work with NodeJS. Browser only.
npm install --save td-js-sdk
Exports Treasure class using CommonJS. The entry point is lib/treasure.js. Usable with a build tool such as Browserify or Webpack.
var Treasure = require('td-js-sdk')
Log in to Treasure Data and go to your profile. The API key should show up right next to your full-access key.
Our library works by creating an instance per database, and sending data into tables.
First install the library using any of the ways provided above.
After installing, initializing it is as simple as:
var foo = new Treasure({
database: 'foo',
writeKey: 'your_write_only_key'
});
If you're an administrator, databases will automatically be created for you. Otherwise you'll need to ask an administrator to create the database and grant you import only or full access on it, otherwise you will be unable to send events.
// Configure an instance for your database
var company = new Treasure({...});
// Create a data object with the properties you want to send
var sale = {
itemId: 101,
saleId: 10,
userId: 1
};
// Send it to the 'sales' table
company.addRecord('sales', sale);
Send as many events as you like. Each event will fire off asynchronously.
td-js-sdk provides a way to track page impressions and events, as well as client information.
Each client requires a uuid. It may be set explicitly by setting clientId on the configuration object. Otherwise we search the cookies for a previously set uuid. If unable to find one, a uuid will be generated.
A cookie is set in order to track the client across sessions.
Tracking page impressions is as easy as:
/* insert javascript snippet */
var td = new Treasure({...});
td.trackPageview('pageviews');
This will send all the tracked information to the pageviews table.
In addition to tracking pageviews, you can track events. The syntax is similar to addRecord, with the difference being that trackEvent will include all the tracked information.
var td = new Treasure({});
var buttonEvent1 = function () {
td.trackEvent('button', {
number: 1
});
// doButtonEvent(1);
};
var buttonEvent2 = function () {
td.trackEvent('button', {
number: 2
});
// doButtonEvent(2);
};
Every time a track functions is called, the following information is sent:
Certain values cannot be obtained from the browser. For these values, we send matching keys and values, and the server replaces the values upon receipt. For examples: {"td_ip": "td_ip"} is sent by the browser, and the server will update it to something like {"td_ip": "1.2.3.4"}
All server values except td_ip are found by parsing the user-agent string. This is done server-side to ensure that it can be kept up to date.
* This is a personally identifiable column, and will be affected by whether or not the user is in Signed or Anonymous Mode.
Set default values on a table by using Treasure#set. Set default values on all tables by passing $global as the table name.
Using Treasure#get you can view all global properties by passing the table name $global.
When a record is sent, an empty record object is created and properties are applied to it in the following order:
$global properties are applied to record objectrecord object, overwriting $global propertiesaddRecord function are applied to record object, overwriting table propertiesTreasure Data's SDK enables compliance with many common requirements of the EU's GDPR laws. Several methods have been enabled to help you comply with newer and more stringent data privacy policies:
blockEvents / unblockEvents - non-argument methods to shut down or re-enable all sending of events to Treasure Data. No messages will be sent, no calls will be cached. Default is for events to be unblocked. See documentation around these methods: blockEvents, unblockEvents, areEventsBlockedsetSignedMode - non-argument method to enter "Signed Mode", where some PII may be collected automatically by the SDK. The data sent to Treasure Data will include td_ip, td_client_id, and td_global_id, if specified. See documentation around this method: setSignedModesetAnonymousMode - non-argument method to enter "Anonymous Mode", where PII will not be collected automatically by the SDK. These data will specifically omit td_ip, td_client_id, and td_global_id, if specified. This is the default behavior. See documentation around this method: setAnonymousModeresetUUID - method to reset the td_client_id value. This will overwrite the original value stored on the user's cookie, and will likely appear in your data as a brand-new user. It's possible to specify a client ID while resetting, as well as custom expiration times by passing in appropriate values. See documentation around this method: resetUUIDSuppose a user first accesses your site, and you need to know if they have agreed to tracking for marketing purposes. You contract with a Consent Management Vendor to maintain this information, and want to set appropriate values once you know their consent information.
var foo = new Treasure({
database: 'foo',
writeKey: 'your_write_only_key'
});
td.trackClicks()
var successConsentCallback = function (consented) {
if (consented) {
td.setSignedMode()
} else {
td.setAnonymousMode()
}
}
var failureConsentCallback = function () {
// error occurred, consent unknown
td.setAnonymousMode()
}
ConsentManagementVendor.getConsent(userId, successConsentCallback, failureConsentCallback)
In this scenario, the Consent Management Vendor returns a true or false value in the callback based on whether or not the user associated with the userId has consented to their PII being used for marketing purposes. Non-PII data may still be collected.
Now suppose your Consent Management Vendor provides strings based on the consent level: MARKETING, NON-MARKETING, REFUSED, for "Consented to PII being used for marketing purposes", "Consented to data being collected for non-marketing purposes", and "Refused all data collection". There's only a minor change to make in the successConsentCallback:
var successConsentCallback = function (consented) {
if (consented === 'MARKETING') {
td.unblockEvents()
td.setSignedMode()
} else if (consented === 'NON-MARKETING') {
td.unblockEvents()
td.setAnonymousMode()
} else if (consented === 'REFUSED') {
td.blockEvents()
}
}
This way, when emerging from Signed or Anonymous mode, you can be sure you'll actually be collecting data in Treasure Data. If the customer has refused all tracking, their events are blocked, and this status will be persisted across page refreshes.
Creates a new Treasure logger instance. If the database does not exist and you have permissions, it will be created for you.
Parameters:
Core parameters:
/js/v3/eventsin.treasuredata.comfalsetrue_td_globalTrack/Storage parameters:
none it will disable cookie storage_td63072000 (2 years)document.location.hostnamePersonalization parameters
Returns:
Example:
var foo = new Treasure({
database: 'foo',
writeKey: 'your_write_only_key'
});
Sends an event to Treasure Data. If the table does not exist it will be created for you.
Records will have additional properties applied to them if $global or table-specific attributes are configured using Treasure#set.
Parameters:
Example:
var company = new Treasure({...});
var sale = {
itemId: 100,
saleId: 10,
userId: 1
};
var successCallback = function () {
// celebrate();
};
var errorCallback = function () {
// cry();
}
company.addRecord('sales', sale, successCallback, errorCallback);
Parameters:
Example:
var td = new Treasure({...})
var successCallback = function (globalId) {
// celebrate();
};
var errorCallback = function (error) {
// cry();
}
td.fetchGlobalID(successCallback, errorCallback)
Parameters:
Example:
var td = new Treasure({...})
var successCallback = function (values) {
/* values format => [... {
key: {
[key]:value
},
values: ["1234"],
attributes: {
age: 30
},
} ... ]*/
// celebrate();
};
var errorCallback = function (error) {
// cry();
};
var token = 'lorem-ipsum-dolor-sit-amet'
td.fetchUserSegments(token, successCallback, errorCallback)
N.B. This feature is not enabled on accounts by default, please contact support for more information.
Parameters:
Example:
var td = new Treasure({...})
var successCallback = function (key, segments) {
// celebrate();
};
var errorCallback = function (error) {
// cry();
};
var token = 'lorem-ipsum-dolor-sit-amet'
td.fetchUserSegments({
audienceToken: ['token1', 'token2'],
keys: {
someKey: 'someValue',
someOtherKey: 'someOtherValue',
}
}, successCallback, errorCallback)
N.B. This feature is not enabled on accounts by default, please contact support for more information.
Block all events from being sent to Treasure Data.
Example:
var td = new Treasure({...})
td.trackEvent('customevent')
td.blockEvents()
td.trackEvent('willnotbetracked')
Unblock all events; events will be sent to Treasure Data.
Example:
var td = new Treasure({...})
td.blockEvents()
td.trackEvent('willnotbetracked')
td.unblockEvents()
td.trackEvent('willbetracked')
Informational method, expressing whether events are blocked or not.
Example:
var td = new Treasure({...})
td.areEventsBlocked() // false, default
td.blockEvents()
td.areEventsBlocked() // true
Permit sending of Personally Identifying Information over the wire: td_ip, td_client_id, and td_global_id
Example:
var td = new Treasure({...})
td.setSignedMode()
td.trackEvent('willbetracked') // will send td_ip and td_client_id; td_global_id will also be sent if set.
Prohibit sending of Personally Identifying Information over the wire: td_ip, td_client_id, and td_global_id
Example:
var td = new Treasure({...})
td.setAnonymousMode()
td.trackEvent('willbetracked') // will NOT send td_ip and td_client_id; td_global_id will also NOT be sent if set.
Informational method, indicating whether trackEvents method will automatically collect td_ip, td_client_id, and td_global_id if set.
Example:
var td = new Treasure({...})
td.inSignedMode() // false, default
td.trackEvent('willbetracked') // will NOT send td_ip and td_client_id; td_global_id will also NOT be sent if set.
td.setSignedMode()
td.inSignedMode() // true
td.trackEvent('willbetracked') // will send td_ip and td_client_id; td_global_id will also be sent if set.
Reset the client's UUID, set to Treasure Data as td_client_id.
Example:
var td = new Treasure({...})
td.resetUUID() // set td_client_id as random uuid
Setup an event listener to automatically log clicks.
Example:
var td = new Treasure({...})
td.trackClicks({ tableName: 'custom_table_name' })
Helper function that calls trackEvent with an empty record.
Parameters:
Example:
var td = new Treasure({...});
td.trackPageview('pageviews');
Creates an empty object, applies all tracked information values, and applies record values. Then it calls addRecord with the newly created object.
Parameters:
Example:
var td = new Treasure({...});
td.trackEvent('events');
/* Sends:
{
"td_ip": "192.168.0.1",
...
}
*/
td.trackEvent('events', {td_ip: '0.0.0.0'});
/* Sends:
{
"td_ip": "0.0.0.0",
...
}
*/
Default value setter for tables. Set default values for all tables by using $global as the setter's table name.
Useful when you want to set a single value.
Parameters:
Example:
var td = new Treasure({...})
td.set('table', 'foo', 'bar');
td.addRecord('table', {baz: 'qux'});
/* Sends:
{
"foo": "bar",
"baz": "qux"
}
*/
Useful when you want to set multiple values.
Parameters:
Example:
var td = new Treasure({...})
td.set('table', {foo: 'foo', bar: 'bar'});
td.addRecord('table', {baz: 'baz'});
/* Sends:
{
"foo": "foo",
"bar": "bar",
"baz": "baz"
}
*/
Takes a table name and returns an object with its default values.
NOTE: This is only available once the library has loaded. Wrap any getter with a Treasure#ready callback to ensure the library is loaded.
Parameters:
Example:
javascript
var td = new Treasure({..});
td.set('table', 'foo', 'bar');
td.get('table');
// {foo: 'bar'}
### Treasure#ready(fn)
Takes a callback which gets called one the library and DOM have both finished loading.
**Parameters:**
* **fn** : Function (required) - callback function
```javascript
/* javascript snippet here */
var td = new Treasure({...})
td.set('table', 'foo', 'bar');
td.ready(function(){
td.get('table');
// {foo: 'bar'}
});
Need a hand with something? Shoot us an email at support@treasuredata.com
The async script snippet will create a fake Treasure object on the window and inject the async script tag with the td-js-sdk url. This fake Treasure object includes a fake of all the public methods exposed by the real version. As you call different methods, they will be buffered in memory until the real td-js-sdk has loaded. Upon td-js-sdk loading, it will look for existing clients and process their buffered actions.
The unminified script loader can be seen in src/loader.js. The code to load existing clients and their buffered actions once td-js-sdk has been loaded can be seen in lib/loadClients.js.
domready is kept at 0.3.0 for IE6 and above supportFirst you'll need to install BrowserStackTunnel. You can download the binary from the BrowserStack website. If you're on Mac OS you can install it through homebrew: brew install caskroom/cask/browserstacklocal.
Next, you'll need to set the appropriate environment variables:
BROWSER_STACK_BINARY_BASE_PATH: This should be the directory you put the BrowserStackTunnel binary in. If you installed with homebrew you can run which browserstacklocal to find the directory.BROWSER_STACK_USERNAME: You can find this under the Automate section of
the BrowserStack account settings pageBROWSER_STACK_ACCESS_KEY: You can find this under the Automate section of
the BrowserStack account settings pageNow, you can run the command npm run test-full.
2.0.0 (2018-05-17)
FAQs
Browser JS library for sending events to your Treasure Data account
The npm package td-js-sdk receives a total of 1,334 weekly downloads. As such, td-js-sdk popularity was classified as popular.
We found that td-js-sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 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
The ongoing npm phishing campaign escalates as attackers hijack the popular 'is' package, embedding malware in multiple versions.
Security News
A critical flaw in the popular npm form-data package could allow HTTP parameter pollution, affecting millions of projects until patched versions are adopted.
Security News
Bun 1.2.19 introduces isolated installs for smoother monorepo workflows, along with performance boosts, new tooling, and key compatibility fixes.