Typedefs
- config :
object
Treasure(config) ⇒ td_instance
Creates a new Treasure logger instance. If the database does not exist and you have permissions, it will be created for you.
Returns: td_instance
-
Treasure logger instance object
See: config
Param | Type | Description |
---|---|---|
config | Treasure.config |
Treasure Data instance configuration parameters |
Example
var foo = new Treasure({
database: 'foo',
writeKey: 'your_write_only_key'
});
resetUUID([suggestedStorage], [suggestedClientId])
Reset the client's UUID, set to Treasure Data as [TD_CLIENT_ID](TD_CLIENT_ID) td_client_id
.
You can specify custom storage and custom client id.
See Track/Storage parameters section for more information on storage's configuration
Param | Type | Description |
---|---|---|
[suggestedStorage] | object |
custom storage configuration |
[suggestedClientId] | string |
custom client id |
Example
var td = new Treasure({...})
td.resetUUID() // set td_client_id as random uuid
Example
var td = new Treasure({...})
td.resetUUID(
{
name: '_td', // cookie name
expires: 63072000,
domain: 'domain',
customDomain: true/false
path: '/'
},
'xxx-xxx-xxxx' // client id
)
trackEvent(table, [record], [success], [failure])
Creates an empty object, applies all tracked information values, and applies record values. Then it calls addRecord with the newly created object.
Param | Type | Description |
---|---|---|
table | string |
table name, must be between 3 and 255 characters and must consist only of lower case letters, numbers, and _ |
[record] | string |
Additional key-value pairs that get sent with the tracked values. These values overwrite default tracking values |
[success] | function |
Callback for when sending the event is successful |
[failure] | function |
Callback for when sending the event is unsuccessful |
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",
// ...
// }
trackPageview(table, [success], [error])
Helper function that calls trackEvent with an empty record. Track impressions on your website Will include location, page, and title
Usage: Treasure#trackPageview() - Sets table to default track pageviews Treasure#trackPageview(table, success, failure)
Param | Type | Description |
---|---|---|
table | string |
table name, must be between 3 and 255 characters and must consist only of lower case letters, numbers, and _ |
[success] | function |
Callback for when sending the event is successful |
[error] | function |
Callback for when sending the event is unsuccessful |
Example
var td = new Treasure({...});
td.trackPageview('pageviews');
blockEvents()
Treasure.blockevents: Block all events from being sent to Treasure Data.
Example
var td = new Treasure({...})
td.trackEvent('customevent')
td.blockEvents()
td.trackEvent('willnotbetracked')
unblockEvents()
Treasure.unblockevents: 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')
areEventsBlocked()
Treasure.areeventsblocked: Informational method, expressing whether events are blocked or not.
Example
var td = new Treasure({...})
td.areEventsBlocked() // false, default
td.blockEvents()
td.areEventsBlocked() // true
setSignedMode()
Treasure.setsignedmode: Sets the user to Signed Mode.
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.
setAnonymousMode(keepIdentifier)
Treasure.setanonymousmode: Sets the user to anonymous mode. Prohibit sending of Personally Identifying Information over the wire: td_ip, td_client_id, and td_global_id
Param | Type | Description |
---|---|---|
keepIdentifier | boolean |
Keep the cookies. By default setAnonymousMode will remove all cookies that are set by Treasure Data JavaScript SDK, you can set keepIdentifier parameter to true to not remove the cookies. |
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.
inSignedMode()
Treasure.insignedmode: Tells whether or not the user is in Signed Mode.
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.
addRecord(table, record, [success], [error])
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.
Param | Type | Description |
---|---|---|
table | string |
table name, must consist only of lower case letters, numbers, and _, must be longer than or equal to 3 chars, the total length of database and table must be shorter than 129 chars. |
record | object |
Object that will be serialized to JSON and sent to the server |
[success] | boolean |
Callback for when sending the event is successful |
[error] | boolean |
Callback for when sending the event is unsuccessful |
set(table, properties)
Useful when you want to set multiple values. Table value setter When you set mutliple attributes, the object is iterated and values are set on the table Attributes are not recursively set on the table
Param | Type | Description |
---|---|---|
table | string |
table name |
properties | object |
Object with keys and values that you wish applies on the table each time a record is sent |
Example
var td = new Treasure({...})
td.set('table', {foo: 'foo', bar: 'bar'});
td.addRecord('table', {baz: 'baz'});
// Sends:
// {
// "foo": "foo",
// "bar": "bar",
// "baz": "baz"
// }
get(table, [key])
Takes a table name and returns an object with its default values. If the table does not exist, its object gets created
NOTE: This is only available once the library has loaded. Wrap any getter with a Treasure#ready callback to ensure the library is loaded.
Param | Type | Description |
---|---|---|
table | string |
table name |
[key] | string |
Optional key to get from the table |
Example (Getting all rows in a table)
var td = new Treasure({..});
td.set('table', 'foo', 'bar');
td.get('table');
// {foo: 'bar'}
Example (Getting a single attribute)
var td = new Treasure({..});
td.get('table', 'foo')
// > 'bar'
trackClicks(trackClickOptions)
Setup an event listener to automatically log clicks. The event will be hooked only follows
role=button
orrole=link
<a>
<button>
<input>)
. exclude for<input type='password'>
Param | Type | Description |
---|---|---|
trackClickOptions | object |
object containing configuration information |
Properties
Name | Type | Description |
---|---|---|
element | string |
Default is window.document. Default setting will observe all elements above. You can set an element if you want to focus on a particular element. |
extendClickData | function |
Default is function to set element attributes. You can set function adding special tracking data by extending function(e: event, elementData: ElementObject). |
ignoreAttribute | string |
Default is "td-ignore" You can set attribute name to ignore element. (e.g. ) |
tableName | string |
Default tableName is "clicks". Click tracking event will be stored into tableName in TreasureData |
Example
var td = new Treasure({...})
td.trackClicks({
element : '...'
extendClickData : '...'
ignoreAttribute : '...'
tableName : '...'
})
fetchGlobalID([success], [error], [forceFetch], [options])
Param | Type | Description |
---|---|---|
[success] | function |
Callback for when sending the event is successful |
[error] | function |
Callback for when sending the event is unsuccessful |
[forceFetch] | boolean |
Forces a refetch of global id and ignores cached version (default false) |
[options] | object |
Cookie options Note: If you set the sameSite value to None, the Secure property of the cookie will be set to true (it overwrites the secure option). More details on SameSite cookies. |
Properties
Name | Type | Description |
---|---|---|
[options.path] | string |
'/', |
[options.domain] | string |
'mycompany.com', |
[options.secure] | boolean |
true |
[options.maxAge] | number | string | date |
Number |
[options.sameSite] | string |
'None |
Example (Cookie options: Note - If you set the sameSite value to None, the Secure property of the cookie will be set to true (it overwrites the secure option). More details on SameSite cookies.)
{
path: '/',
domain: 'abc.com',
secure: true|false,
maxAge: Number | String | Date,
sameSite: 'None | Lax | Strict'
}
Example
var td = new Treasure({...})
var successCallback = function (globalId) {
// celebrate();
};
var errorCallback = function (error) {
// cry();
}
td.fetchGlobalID(successCallback, errorCallback)
// with cookie options
td.fetchGlobalID(successCallback, errorCallback, true, {
path: '/',
secure: true,
maxAge: 5 * 60 // 5 minutes,
sameSite: 'None'
})
fetchUserSegments(options, [success], [error])
Param | Type | Description |
---|---|---|
options | object |
User Segment object |
options.audienceToken | string | array |
Audience Token(s) for the userId |
[success] | function |
Callback for receiving the user key and segments |
[error] | function |
Callback for when sending the event is unsuccessful |
Properties
Name | Type | Description |
---|---|---|
options.keys | object |
Key Value to be sent for this segment |
Example (N.B. This feature is not enabled on accounts by default, please contact support for more information.)
var td = new Treasure({...})
var successCallback = function (values) {
//values format => [... {
// key: {
// [key]:value
// },
// values: ["1234"],
// attributes: {
// age: 30
// },
//} ... ]
// celebrate();
};
var errorCallback = function (error) {
// cry();
};
td.fetchUserSegments({
audienceToken: ['token1', 'token2'],
keys: {
someKey: 'someValue',
someOtherKey: 'someOtherValue',
}
}, successCallback, errorCallback)
fetchServerCookie([success], [error], [forceFetch])
This functionality complies with ITP 1.2 tracking. Contact customer support for enabling this feature.
Param | Type | Description |
---|---|---|
[success] | function |
Callback for when sending the event is successful |
[error] | function |
Callback for when sending the event is unsuccessful |
[forceFetch] | boolean |
Forces a refetch of server side id and ignores cached version (default false) |
Example
var td = new Treasure({...})
var successCallback = function (serverSideId) {
// celebrate();
};
var errorCallback = function (error) {
// cry();
}
td.fetchServerCookie(successCallback, errorCallback)
saveContexts([success],[error])
Save the contexts to the local storage and to the Treasure Data platform([success], [error])
Param | Type | Description |
---|---|---|
[success] | function |
Callback for when saving the contexts successfully |
[error] | function |
Callback for when saving the contexts unsuccessfully |
Example
function success () {
// yay()
}
function error (err) {
// err: { success: false, message: 'Timeout' }
}
sdk.saveContexts(success, error)
saveConsents([success],[error])
Save the consents to the local storage and to the Treasure Data platform. If you don’t specify the callbacks, the callbacks that are configured in the Configurations section above will be called.([success], [error])
Param | Type | Description |
---|---|---|
[success] | function |
Callback for when saving the consents successfully |
[error] | function |
Callback for when saving the consents unsuccessfully |
Example
function success () {
// yay()
}
function error (err) {
// err: { success: false, message: 'Timeout' }
}
sdk.saveConsents(success, error)
addContext(context)
Adding context for consents, the context will be included when we send data to TD platform (event-collector). Users can specify their own context id otherwise a new context id will be generated. Returns {uuid} context id(context)
Param |
---|
context |
Properties
Name | Type | Description |
---|---|---|
context.brand | string |
brand name |
context.domain_name | string |
domain name |
context.collection_type | string |
consent collection type |
context.collection_point_id | string |
consent collection point id |
[context.context_id] | string |
Context Id |
Example
sdk.addContext({
brand: 'A Brand',
domain_name: 'abrand.com',
collection_type: 'shopping_cart',
collection_point_id: 'shopping_trnx_id'
context_id: 'uuid'
})
addConsents(consents)
Adding consents. For the consents that don’t have context ID, they will be added to a default context(consents)
Param | Type |
---|---|
consents | object |
Properties
Name | Type | Description |
---|---|---|
consents.consent | object |
Specific consent |
consents.consent.key | string |
purpose of consent |
consents.consent.values | object |
consent information |
consents.consent.values.description | string |
Consent’s description |
consents.consent.values.datatype | string |
data type |
consents.consent.values.status | string |
Consent’s status (given |
consents.consent.values.expiry_date | string | Number | Date |
expiry date |
consents.consent.values.context_id | string |
Context Id |
Example
sdk.addConsents({
'marketing': { // <--- purpose
description: 'description of consent',
datatype: 'Attibutes',
status: 'given|refused',
expiry_date: 'YYYY-MM-DD',
context_id: 'context_id'
},
'storing': { // <--- purpose
description: 'description',
datatype: 'datatype',
status: 'given|refused',
expiry_date: 'YYYY-MM-DD',
context_id: 'context_id'
},
'recommendations': { // <--- purpose
description: 'description',
datatype: 'datatype',
status: 'given|refused',
expiry_date: 'YYYY-MM-DD',
context_id: 'context_id'
}
)
updateConsent(contextId,consentObject)
Update a specific consent. When you update a consent, only the updated consent is sent to the successConsentCallback
after calling saveConsents
.(contextId, consentObject)
Param | Type | Description |
---|---|---|
contextId | string |
Context Id |
consentObject | object |
Consent that you want to update |
Example
sdk.updateConsent('xxxxxx-context-id', {
'recommendations': {
status: 'refused'
}
})
updateContext(contextId,values)
Update a specific context(contextId, values)
Param | Type | Description |
---|---|---|
contextId | string |
Context Id |
values | object |
Values of context that you want to update |
Example
sdk.updateContext('xxxxxx-context-id', {
brand: 'Other brand',
domain_name: 'otherdomain.com'
})
getConsents()()
Return list of consents
getContexts()
Return list of contexts()
getExpiredConsents()
Returns expired consents()
config : object
Properties
Name | Type | Description |
---|---|---|
config.database | string |
database name, must consist only of lower case letters, numbers, and |
config.writeKey | string |
write-only key, get it from your user profile |
[config.pathname] | string |
path to append after host. Default: |
[config.host] | string |
host to which events get sent. Default: |
[config.development] | boolean |
triggers development mode which causes requests to be logged and not get sent. Default: |
[config.logging] | boolean |
enable or disable logging. Default: |
[config.globalIdCookie] | string |
cookie tdglobalid name. Default: |
[config.startInSignedMode] | boolean |
Tell the SDK to default to Signed Mode if no choice is already made. Default: |
[config.jsonpTimeout] | number |
JSONP timeout (in milliseconds) Default: |
[config.storeConsentByLocalStorage] | boolean |
Tell the SDK to use localStorage to store user consent. Default: |
[config.clientId] | string |
uuid for this client. When undefined it will attempt fetching the value from a cookie if storage is enabled, if none is found it will generate a v4 uuid |
[config.storage] | object | string |
storage configuration object. When |
[config.storage.name] | string |
cookie name. Default: |
[config.storage.expires] | integer |
cookie expiration in seconds. When 0 it will expire with the session. Default: |
[config.storage.domain] | string |
cookie domain. Default: result of |
[config.useServerSideCookie] | boolean |
enables/disable using ServerSide Cookie. Default: |
[config.sscDomain] | string |
Domain against which the Server Side Cookie is set. Default: |
[config.sscServer] | string |
hostname to request server side cookie from. Default: |
[config.cdpHost] | string |
The host to use for the Personalization API. Default: 'cdp.in.treasuredata.com' |
[config.consentManager] | object |
Consent Manager configuration, setup along with the TD JavaScript SDK initialization.Every time when a page is loaded, TD JS Consent Extension will check the consent expiry date and if there’s any expired consent, then the expiredConsentCallback is triggered. It also updates status of the expired consent to expired |
[config.consentManager.storageKey] | string |
Name of the local storage. Default: |
[config.consentManager.consentTable] | string |
Name of the consent table. Default: |
[config.consentManager.contextTable] | string |
Name of the context table. Default: |
[config.consentManager.issuer] | string |
Name of the consent management platform. Default: |
[config.consentManager.dateFormat] | string |
Date format string. Default: |
[config.consentManager.successConsentCallback] | function |
Successful saving consent callback |
[config.consentManager.failureConsentCallback] | function |
Failed to save consent callback |
[config.consentManager.expiredConsentsCallback] | function |
Expired consent callback |