Page tree
Skip to end of metadata
Go to start of metadata


The build script (bin/build.sh) can be used to configure several aspects of the SDK including: 



Treasure Data recommends that you implement any new features or functionality at your site using the Treasure Data JavaScript SDK version 3 Beta. It manages cookies differently. Be aware when referring to most of these articles that you need to define the suggested event collectors and Treasure Data JavaScript SDK version 3 calls in your solutions.

For example, change //cdn.treasuredata.com/sdk/2.5/td.min.js to //cdn.treasuredata.com/sdk/3.0.0-beta/td.min.js.

GLOBAL

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()

FILENAME

The filename to be output, for full and minified code. This is convenient and defaults to td.

> bin/build.sh --FILENAME=foo
...
> ls dist/
foo.js      foo.min.js      loader.min.js

URL

The URL of the hosted file. This defaults to the URL for the Treasure Data CDN-hosted file.

> bin/build.sh --URL=//cdn.yourdomain.com/sdk/foo.min.js

Getting started

Get your write-only API key

Log in to Treasure Data and go to your profile. The API key should show up right next to your full-access key.

Initializing

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.

Sending your first event

// 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.

Tracking

td-js-sdk provides a way to track page impressions and events, as well as client information.

Client ID and Storage

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.

Page impressions

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.

Event tracking

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);
};

Tracked information

Every time a track function 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"}. td_ip values come from the X-Forwarded-For header.



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 is affected by whether or not the user is in Signed or Anonymous Mode.



Default values

Set default values on a table by using Treasure#set. Set default values on all tables bypassing the $global 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:

  1. $global properties are applied to record object

  2. Table properties are applied to record object, overwriting $global properties

  3. Record properties is passed to the addRecord function and is applied to the record object, overwriting table properties

Data Privacy

Treasure 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, areEventsBlocked

  • setSignedMode - 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: setSignedMode

  • setAnonymousMode - 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: setAnonymousMode

  • resetUUID - 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 bypassing inappropriate values. See documentation around this method: resetUUID

A new configuration property has also been added: config.startInSignedMode. This configuration option tells the SDK that, if no express decision has been made on whether the user wants to be in Signed or Anonymous modes, it should default into Signed Mode. The default behavior is to default the user into Anonymous Mode.

Examples

Suppose a user first accesses your site, and you need to know if they have agreed to track for marketing purposes. Your contract with a Consent Management Vendor to maintain this information and want to set appropriate values after 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.

For example, 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.


  • No labels