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

Copy
Copied
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

Copy
Copied
var td = new Treasure({...})
td.resetUUID() // set td_client_id as random uuid

Example

Copy
Copied
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

Copy
Copied
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

Copy
Copied
var td = new Treasure({...});
td.trackPageview('pageviews');

blockEvents()

Treasure.blockevents: Block all events from being sent to Treasure Data.
Example

Copy
Copied
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

Copy
Copied
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

Copy
Copied
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: tdip, tdclientid, and tdglobal_id
Example

Copy
Copied
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: tdip, tdclientid, and tdglobal_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

Copy
Copied
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 tdip, tdclientid, and tdglobal_id if set.
Example

Copy
Copied
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

Copy
Copied
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)

Copy
Copied
var td = new Treasure({..});
td.set('table', 'foo', 'bar');
td.get('table');
// {foo: 'bar'}

Example (Getting a single attribute)

Copy
Copied
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 or role=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

Copy
Copied
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.)

Copy
Copied
{
  path: '/',
  domain: 'abc.com',
  secure: true|false,
  maxAge: Number | String | Date,
  sameSite: 'None | Lax | Strict'
}

Example

Copy
Copied
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, false, {
  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.)

Copy
Copied
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

Copy
Copied
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

Copy
Copied
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

Copy
Copied
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.collectionpointid string

consent collection point id

[context.context_id] string

Context Id

Example

Copy
Copied
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

Copy
Copied
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

Copy
Copied
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

Copy
Copied
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 _, must be longer than or equal to 3 chars, and the total length of database and table must be shorter than 129 chars.

config.writeKey string

write-only key, get it from your user profile

[config.pathname] string

path to append after host. Default: /js/v3/events

[config.host] string

host to which events get sent. Default: in.treasuredata.com

[config.development] boolean

triggers development mode which causes requests to be logged and not get sent. Default: false

[config.logging] boolean

enable or disable logging. Default: true

[config.globalIdCookie] string

cookie tdglobalid name. Default: td_global

[config.startInSignedMode] boolean

Tell the SDK to default to Signed Mode if no choice is already made. Default: false

[config.jsonpTimeout] number

JSONP timeout (in milliseconds) Default: 10000

[config.storeConsentByLocalStorage] boolean

Tell the SDK to use localStorage to store user consent. Default: false

[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 none it will disable cookie storage

[config.storage.name] string

cookie name. Default: _td

[config.storage.expires] integer

cookie expiration in seconds. When 0 it will expire with the session. Default: 63072000 (2 years)

[config.storage.domain] string

cookie domain. Default: result of document.location.hostname

[config.useServerSideCookie] boolean

enables/disable using ServerSide Cookie. Default: false

[config.sscDomain] string

Domain against which the Server Side Cookie is set. Default: window.location.hostname

[config.sscServer] string

hostname to request server side cookie from. Default: ssc.${sscDomain}

[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: tdconsentpreferences

[config.consentManager.consentTable] string

Name of the consent table. Default: tdcmconsent

[config.consentManager.contextTable] string

Name of the context table. Default: tdcmcontext

[config.consentManager.issuer] string

Name of the consent management platform. Default: treasuredata

[config.consentManager.dateFormat] string

Date format string. Default: YYYY-MM-DD

[config.consentManager.successConsentCallback] function

Successful saving consent callback

[config.consentManager.failureConsentCallback] function

Failed to save consent callback

[config.consentManager.expiredConsentsCallback] function

Expired consent callback


Support
Copyright © 2021 Treasure Data, Inc. (or its affiliates). All rights reserved.