,
hash: string,
}
```
**Syntax**
```
parseUrl(url);
```
**Example**
```
const parseUrl = require('parseUrl');const urlObject = parseUrl('https://abc:xyz@example.com:8080/foo?param=val%2Cue#bar');
```
**Parameters**
| Parameter | Type | Description |
| --------- | -------- | --------------------------------- |
| **`url`** | *string* | The full url that will be parsed. |
## `sha256`
Calculates the SHA-256 digest of the input and invokes a callback with the digest encoded in base64, unless the `options` object specifies a different output encoding.
This API signature and behavior matches the [`sha256`](https://developers.google.com/tag-platform/tag-manager/templates/api#sha256) API for web containers; however, Custom Templates in server containers should use the [`sha256Sync`](https://developers.google.com/tag-platform/tag-manager/server-side/api#sha256sync) API for simpler code.
**Syntax**
```
sha256(input, onSuccess, options = undefined);
```
**Example**
```
const encodeUriComponent = require('encodeUriComponent');const sendHttpGet = require('sendHttpGet');const sha256 = require('sha256');sha256('inputString', (digest) => { sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digest));});sha256('inputString', (digest) => { sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digest));}, {outputEncoding: 'hex'});
```
**Parameters**
| Parameter | Type | Description |
| --------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`input`** | *string* | The string to hash. |
| **`onSuccess`** | *function* | Called with the resulting digest, encoded in base64, unless the `options` object specifies a different output encoding. |
| **`options`** | *object* | *Optional* options object to specify the output encoding. If specified, the object should contain the key `outputEncoding` with value as one of `base64` or `hex`. |
## `sha256Sync`
Calculates and returns the SHA-256 digest of the input, encoded in base64, unless the `options` object specifies a different output encoding.
**Syntax**
```
sha256Sync(input, options = undefined);
```
**Example**
```
const encodeUriComponent = require('encodeUriComponent');const sendHttpGet = require('sendHttpGet');const sha256Sync = require('sha256Sync');const digestBase64 = sha256Sync('inputString');const digestHex = sha256Sync('inputString', {outputEncoding: 'hex'});sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digestBase64));sendHttpGet('https://example.com/collect?id=' + encodeUriComponent(digestHex));
```
**Parameters**
| Parameter | Type | Description |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`input`** | *string* | The string to hash. |
| **`options`** | *object* | *Optional* options object to specify the output encoding. If specified, the object should contain the key `outputEncoding` with value as one of `base64` or `hex`. |
## `signHmac`
Generates an HMAC signature for the given payload, using `sha256` and `base64` encoding by default, unless the `options` object specifies otherwise. Objects passed as payload are automatically `JSON.stringify`'d. Returns a **string**.
**Syntax**
```javascript
signHmac(payload, secret, options = undefined);
```
**Example**
```javascript
const signHmac = require('signHmac');
// Sign a string with default options (sha256 + base64)
const signature = signHmac('my payload', 'mySecretKey');
// Sign with custom algorithm and encoding
const signatureHex = signHmac('my payload', 'mySecretKey', { alg: 'sha1', outputEncoding: 'hex' });
// Sign an object (automatically JSON.stringify'd)
const objectSignature = signHmac({ key: 'value' }, 'mySecretKey');
```
**Parameters**
| Parameter | Type | Description |
| ------------- | ---------------- | ---------------------------------------------------------------------------------------------------- |
| **`payload`** | *string\|object* | The data to sign. Objects are automatically converted to JSON strings. |
| **`secret`** | *string* | The secret key used for HMAC generation. |
| **`options`** | *object* | *Optional* options object to customize the algorithm and output encoding. See options details below. |
**Options**
| Property | Type | Default | Description |
| -------------------- | -------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **`alg`** | *string* | `'sha256'` | The hash algorithm. Supported values: `'sha256'`, `'sha1'`, `'sha512'`, `'sha384'`, `'md5'` and other OpenSSL digest algorithms. |
| **`outputEncoding`** | *string* | `'base64'` | The output encoding. Supported values: `'base64'`, `'base64url'`, `'hex'`, `'binary'` (`latin1`). |
## `toBase64`
Encodes a string as base64.
**Syntax**
```
toBase64(input);
```
**Example**
```
const toBase64 = require('toBase64');const base64Hello = toBase64('hello');
```
**Parameters**
| Parameter | Type | Description |
| ----------- | -------- | ----------------- |
| **`input`** | *string* | String to encode. |
## `JSON`
Returns an object that provides JSON functions.
The `parse()` function parses a JSON string to construct the value or object described by the string. If the value cannot be parsed (malformed JSON), the function will return `undefined`. If the input value is not a string, the input will be coerced to a string.
The `stringify()` function converts the input into a JSON string. If the value cannot be parsed (ex. the object has a cycle), the method will return `undefined`.
**Syntax**
```
JSON.parse(yourString);
JSON.stringify(yourObject);
```
**Example**
```
const JSON = require('JSON');
// The JSON input string is converted to an object.
const object = JSON.parse('{"foo":"bar"}');
// The input object is converted to a JSON string.
const str = JSON.stringify({foo: 'bar'});
```
***
## `Math`
An object providing `Math` functions.
**Syntax**
```
const Math = require('Math');
// Retrieve the absolute value.
const absolute = Math.abs(-5);
// Round the input down to the nearest integer.
const roundedDown = Math.floor(4.6);
// Round the input up to the nearest integer.
const roundedUp = Math.ceil(2.1);
// Round the input to the nearest integer.
const rounded = Math.round(4.2);
// Return the largest argument.
const biggest = Math.max(1, 4);
// Return the smallest argument.
const smallest = Math.min(4, 5);
// Return the first argument raised to the power of the second argument.
const powerful = Math.pow(4, 2);
// Return the square root of the argument.
const unsquared = Math.sqrt(81);
```
**Parameters**
Math function parameters are converted to numbers.
## `sendHttpGet`
Makes an HTTP GET request to the specified URL, and invokes a callback with the response once the request completes or times out.
**Syntax**
```javascript
sendHttpGet(url[, callback[, options]]);
```
**Example**
```javascript
const sendHttpGet = require('sendHttpGet');
// Sends a GET request and nominates response// based on the response from the GET
sendHttpGet('https://example.com/collect', function(statusCode, headers, body) {
if (statusCode != 200) {yourCallbackFunction();}
}, {
headers: {key: 'value'},
timeout: 500
});
```
**Parameters**
| Parameter | Type | Description |
| -------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`url`** | *string* | The request URL. |
| **`callback`** | *function* | An optional callback to invoke upon request completion, error, or timeout.
It is invoked with the response status code, the response headers, and the response body (or undefined if there was no response body).
If the request failed (e.g. invalid URL, no route to host, SSL negotiation failure, etc.), the callback will be invoked with a response status code of zero, no headers, and an undefined body.
If the 'timeout' option was set and the request timed out, the callback will be invoked with a response status code of -1, no headers, and an undefined body.
|
| **`options`** | *object* | Optional request options. The supported options are **headers**, **timeout**. Advanced options can be added in **extraOptions** |
#### **Options**
* **headers**: Additional request headers represented as an object.
* **timeout**: The timeout, in milliseconds, before the request is aborted.
* **extraOptions**: Advanced options (ex: {strictSSL:true})
## `sendHttpRequest`
Makes an HTTP request to the specified URL, and invokes a callback with the response once the request completes or times out.
**Syntax**
```
sendHttpRequest(url[, callback[, options[, body]]]);
```
**Example**
```javascript
const sendHttpRequest = require('sendHttpRequest');
const body = {
user_type:'vip',
account:'123'
};
// Sends a POST request
sendHttpRequest('https://example.com/collect', function(statusCode, headers, body) {
//your callback code...
}, {
headers: {
token: '123456789'
},
method: 'POST',
timeout: 1000
}, JSON.stringify(body));
```
**Parameters**
| Parameter | Type | Description |
| -------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`url`** | *string* | The request URL. |
| **`callback`** | *function* | An optional callback to invoke upon request completion, error, or timeout.
It is invoked with the response status code, the response headers, and the response body (or undefined if there was no response body).
If the request failed (e.g. invalid URL, no route to host, SSL negotiation failure, etc.), the callback will be invoked with a response status code of zero, no headers, and an undefined body.
If the 'timeout' option was set and the request timed out, the callback will be invoked with a response status code of -1, no headers, and an undefined body.
|
| **`options`** | *object* | Optional request options. The supported options are: **headers**, **method**, and **timeout**. Unknown option keys are ignored. Advanced options can be added in **extraOptions.** |
| **`body`** | *string* | Optional request body. |
**Options**
* **headers**: Additional request headers.
* **method**: The request method, defaults to 'GET'.
* **timeout**: The timeout, in milliseconds, before the request is aborted.
* **extraOptions**: Advanced options (ex: {strictSSL:true})
## `md5Sync`
Calculates and returns the `md5` digest of the input.
**Syntax**
```
md5Sync(input);
```
**Example**
```javascript
const md5Sync= require('md5Sync');
const email = {};
email.md5 = md5Sync(user.user_email);
sendHttpGet('https://example.com/collect?e5=' + email.md5);
```
## `templateDataStorage`
The `templateDataStorage` helper allows temporary storage and retrieval of data, such as API tokens, during script execution. It is particularly useful for caching reusable data to reduce redundant API calls. Data stored in `templateDataStorage` persists on the server running the template. Since templates execute on multiple servers, and each server may have multiple instances, stored data is not guaranteed to be accessible for all subsequent template execution.
**Syntax**
```javascript
templateDataStorage.setItemCopy(key, value);
templateDataStorage.getItemCopy(key);
templateDataStorage.removeItemCopy(key);
```
**Example: Managing API Tokens**
```javascript
const sendHttpRequest = require('sendHttpRequest');
const templateDataStorage = require('templateDataStorage');
const tokenKey = 'apiToken';
function fetchNewToken(callback) {
sendHttpRequest('https://example.com/api/token', function (status, _, body) {
if (status === 200) {
const { accessToken, expiresIn } = JSON.parse(body);
const tokenData = { token: accessToken, expiry: Date.now() + expiresIn * 1000 };
templateDataStorage.setItemCopy(tokenKey, tokenData);
callback(accessToken);
} else {
callback(null);
}
}, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ clientId: 'id', clientSecret: 'secret' }) });
}
function sendEvent(eventData) {
const cachedToken = templateDataStorage.getItemCopy(tokenKey);
const token = cachedToken && cachedToken.expiry > Date.now() ? cachedToken.token : null;
sendHttpRequest('https://example.com/api/events', function (status) {
if (status === 401) {
fetchNewToken(function (newToken) {
if (newToken) {
sendHttpRequest('https://example.com/api/events', () => {}, { method: 'POST', headers: { Authorization: `Bearer ${newToken}` }, body: JSON.stringify(eventData) });
}
});
}
}, { method: 'POST', headers: { Authorization: `Bearer ${token}` }, body: JSON.stringify(eventData) });
}
sendEvent({ eventName: 'purchase', value: 100 });
```
| Method | Description |
| ----------------------------- | ----------------------------------------------------------------------------------------------------- |
| **`setItemCopy(key, value)`** | Stores a value under the specified key. Overwrites the value if the key already exists. |
| **`getItemCopy(key)`** | Retrieves the value associated with the specified key. Returns `undefined` if the key does not exist. |
| **`removeItemCopy(key)`** | Deletes the value associated with the specified key. |
| Parameter | Type | Description |
| ----------- | -------- | ---------------------------------------------------------- |
| **`key`** | *string* | The unique identifier for the data to be stored/retrieved. |
| **`value`** | *any* | The data to be stored (for `setItemCopy`). |