# Using the Javascript SDK Build Script

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

* [GLOBAL](#global)
* [FILENAME](#filename)
* [URL](#url)
* [Getting started](#getting-started)
* [Get your write-only API key](#get-your-write-only-api-key)
* [Initializing](#initializing)
* [Sending your first event](#sending-your-first-event)
* [Tracking](#tracking)
* [Client ID and Storage](#client-id-and-storage)
* [Page impressions](#page-impressions)
* [Event tracking](#event-tracking)
* [Tracked information](#tracked-information)
* [Default values](#default-values)
* [Data Privacy](#data-privacy)
* [Examples](#examples)


### GLOBAL

The global export that the SDK is exported on. This is kept consistent between the full source and the loader's stub.


```bash
    > 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.`


```bash
    > 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.


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

## Getting started

### Get your write-only API key

Log in to [Treasure Data](https://console.treasuredata.com/) and go to your [profile](https://console.treasuredata.com/users/current). 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:


```javascript
      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


```javascript
    // 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:


```javascript
    /* 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.


```javascript
    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:

* [Treasure Data JavaScript SDK Version 3.0 Default Log Parameters](/products/customer-data-platform/integration-hub/streaming/td-javascript-sdk/treasure-data-javascript-sdk-version-3-0-default-log-parameters)


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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/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.


```javascript
    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`:


```javascript
    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.