# JS Tag

This library allows mediarithmics customers to track user events on web sites and applications.

It loads a Javascript object in the page that can be used to send the proper events to the mediarithmics platform. 

Please refer to the [Web apps real time user tracking](https://developer.mediarithmics.io/data-streams/data-ingestion/real-time-user-tracking/web-events) guide for details on how to use it.

{% hint style="info" %}
When added to the page, the tag does 3 things :

* Adding the mediarithmics cookie
* If set up, start cookie-matching with partners
* Register events
  {% endhint %}

{% hint style="danger" %}
Cookies used by the tag are considered ad-serving cookies. **You must get the user consent before using it.**
{% endhint %}

## mics.init(token)

Init the script with your token. This call is mandatory and must be used before any mics.push() or mics.pushDefault().

#### **Arguments**

| name  | type   | description                             |
| ----- | ------ | --------------------------------------- |
| token | string | Your site token given by Mediarithmics. |

**Returns** : nothing.**Throws** : an error if the token is invalid.

```javascript
mics.init("MY_TOKEN");
```

## mics.init({mode, site\_token, domain\_name})

Advanced way of initializing the TAG. Init the script with the mode of interaction, your site token and optionaly the custom domain name. 

This call is mandatory and must be used before any mics.push() or mics.pushDefault().

**Arguments**

| name         | type   | description                                                                                                                                                    |
| ------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| mode         | string | The mode of interaction (in most cases it's a "VISIT"). In case of any doubt, please contact your mediarithmics account manager.                               |
| site\_token  | string | Your site token given by mediarithmics.                                                                                                                        |
| domain\_name | object | (optional) The custom domain\_name used to store the cookie on your domain, you should only use it when you use a custom DMP domain Ex: analytics.mydomain.com |

**Returns** : nothing.**Throws** : an error if the token is invalid.

```javascript
mics.init({
    mode: "VISIT", 
    site_token: "SITE TOKEN", 
    domain_name: "analytics.mydomain.com"
    });
```

## mics.pushDefault()

Push the default event $page\_view to mediarithmics..

**Arguments** : none.\
**Returns** : nothing.\
**Throws** : an error if mics.init has not been called.

```javascript
mics.init("SITE TOKEN");
mics.pushDefault();
```

## mics.push(event, properties)

Push a custom event with custom properties.

**Arguments**

| name       | type   | description                                                                                           |
| ---------- | ------ | ----------------------------------------------------------------------------------------------------- |
| event      | string | the name of the event.                                                                                |
| properties | object | the object containing the custom properties to push. Only string/boolean/number values are supported. |

**Returns** : nothing.\
**Throws** : an error if mics.init has not been called.

```javascript
mics.init("<SITE_TOKEN>");
mics.push("my_event", {
  my_prop1 : "value1",
  my_prop2 : 42
});
```

## mics.addProperty(name, value)

Add a single property to be used for each mics push or pushDefault. You can call this method multiple times, the effects are cumulative.

See mics.addProperties(properties) to send multiple properties at once.

**Arguments**

| name  | type   | description                       |
| ----- | ------ | --------------------------------- |
| name  | string | the name of the property to add.  |
| value | object | the value of the property to add. |

**Returns** : nothing.\
**Throws** : nothing.

```javascript
mics.addProperty("$user_account_id", <your unique user account id> );
```

## mics.addProperties(properties)

Add properties to be used for each mics.push or mics.pushDefault. You can call this method multiple times, the effects are cumulative.

See mics.addProperty(name, value) to send only one property at once.

**Arguments**

| name       | type   | description                                                                                           |
| ---------- | ------ | ----------------------------------------------------------------------------------------------------- |
| properties | object | the object containing the custom properties to push. Only string/boolean/number values are supported. |

**Returns** : nothing\
**Throws** : nothing

```javascript
mics.addProperties({
  prop1 : "val1",
  prop2 : "val2"
});
```

It can be used to declare global properties to push :

```javascript
mics.addProperties({
  prop1 : "val1",
  prop2 : "val2"
});

// will push prop1, prop2 and prop3
mics.push("my_event", {
  prop3 : "val3"
});

// will push prop1, prop2 and prop4
mics.push("my_event", {
  prop4 : "val4"
});
```

## mics.addIdentifier(type,identifier)

Add an identifier to be used for each mics.push or mics.pushDefault. You can call this method multiple times with different identifier to add multiple identifiers. The effect of this method is idempotent: you can call it multiple times with the same input, the identifier will be registered only once.

**Arguments**

<table><thead><tr><th width="124.33333333333331">name</th><th width="91">type</th><th>description</th></tr></thead><tbody><tr><td>type</td><td>string</td><td>The type of identifier. Accepted values: "USER_ACCOUNT", "USER_EMAIL", and "USER_AGENT"</td></tr><tr><td>identifier</td><td>object</td><td>The object containing the identifier.<br>Accepted values : <br>- if type is "USER_ACCOUNT", identifier must be { $user_account_id: "account id"} or { $user_account_id: "account id", $compartment_token: "token" }<br>- if type is "USER_EMAIL", identifier must be { $email_hash: "hash" } or { $email_hash: "hash", $email: "email" }<br>- if type is "USER_AGENT", identifier must be { $user_agent_id: "user_agent_id" }. See <a href="https://developer.mediarithmics.io/user-points/user-identifiers/device-identifiers#user_agent_id">UserAgentId</a>. Agent type accepted are mobile advertising id, mobile vendor id, tv advertising id, and custom id.</td></tr></tbody></table>

{% hint style="warning" %}
The registry id is not supported when adding a USER\_AGENT identifier, you must specify the registry token

:white\_check\_mark:  `mics.addIdentifier('USER_AGENT',{$user_agent_id:'dev:<registry_token>:abcd'})`

:x:  `mics.addIdentifier('USER_AGENT',{$user_agent_id:'dev:<registry_id>:abcd'})`
{% endhint %}

{% hint style="info" %}
You can pass an optional `$expiration_ts` property (Unix Epoch Time in **milliseconds**) with the identifier to specify an expiration
{% endhint %}

{% hint style="info" %}
You should not add network device id here as they are managed from the UI. If the desired network device id is not available please contact support.
{% endhint %}

**Returns** : nothing (if arguments are invalid, call to this method will have no effect)

```
mics.addIdentifier(
    "USER_ACCOUNT", 
    { $user_account_id: "account id", $compartment_token: "token" }
);
mics.addIdentifier(
    "USER_ACCOUNT", 
    { $user_account_id: "account id", $compartment_token: "token", $expiration_ts: 1743580225000 }
);
mics.addIdentifier(
    "USER_EMAIL",
    { $email_hash: "hash", $email: "email" }
);
mics.addIdentifier(
    "USER_AGENT",
    { $user_agent_id: "dev:my-custom-registry:1234", $expiration_ts: 1743580225000 }
);
```

## mics.onFinish(callback, timeout)

Register **ONE** callback to fire when the tag has finished sending events. Only the last registered callback will be fired.

**Arguments**

| name     | type     | description                                                                                     |
| -------- | -------- | ----------------------------------------------------------------------------------------------- |
| callback | function | function taking a boolean. True if everything was OK.                                           |
| timeout  | int      | The timeout in milliseconds to start triggering events. Will call callback after event replies. |

**Returns** : nothing.

```javascript
mics.init("<SITE_TOKEN>");
mics.push("my_event", {
  my_prop1 : "value1",
  my_prop2 : 42
});
var start = new Date().getTime();
mics.onFinish(function(success) {
  var end = new Date().getTime();
  // end - start will be > 1000, but close to.
  console.log("done with success : ", success, " in ", end - start, "ms");
},1000);
```

## mics.onStart(callback)

Register **ONE** callback to be fired when the tag starts executing (ie the JavaScript is loaded and starts working). Only the last registered callback will be fired.

**Arguments**

| name     | type     | description                              |
| -------- | -------- | ---------------------------------------- |
| callback | function | function called when tag start executing |

**Returns** : nothing

```javascript
mics.init("<SITE_TOKEN>");
mics.push("my_event", {
  my_prop1 : "value1",
  my_prop2 : 42
});
var start = new Date().getTime();
mics.onStart(function() {
  var end = new Date().getTime();
  console.log("started in ", end - start, "ms");
});
```

## mics.call(methodName, args)

Helper function to call a method without a snippet declaring it. Acts like a proxy function.

**Arguments**

| name       | type      | description                                             |
| ---------- | --------- | ------------------------------------------------------- |
| methodName | string    | the name of the method : (init, push, pushDefault, ...) |
| arguments  | object... | the parameters of the method                            |

**Returns** : underlying method result

```javascript
mics.call("init", "<SITE_TOKEN>");
mics.call("push", "<EVENT_NAME>", {
  my_prop1 : "value1",
  my_prop2 : 42
});
```

## mics.call("syncFeeds")

The syncFeeds method should be called after mics.init() to enable client-side feeds. It allows the tag to query mediarithmics servers to know if the user is in a segment synchronized with a client-side feed.

**Arguments**

| name       | type      | description |
| ---------- | --------- | ----------- |
| methodName | string    | syncFeeds   |
| arguments  | object... | none        |

**Returns** : Client-side feeds are now enabled

## Session storage

For caching and integration purposes, the tag stores identifiers it retrieves in the browser session storage under the key `mcssids`.

The value is a stringified object with keys corresponding to the site token and the value an array of identifiers like the following :

```json
{
  "<site_token>": [
    {
      "$type":"USER_ACCOUNT",
      "$compartment_token":"<compartment_token>"
      "$user_account_id":"account_1234"
      "$expiration_ts": 1234567890000 //ms
    },
    {
      "$type":"USER_EMAIL",
      "$email_hash":"oqlsdfhjiezkqdrufhiesqhfgr",
      "$expiration_ts": 1234567890000 //ms
    },
    {
      "$type":"USER_AGENT",
      "$user_agent_id":"<user_agent_id-non_authenticated_format>"
      "$expiration_ts": 1234567890000 //ms
    }
}
```

{% hint style="info" %}
See [#user\_agent\_id](https://developer.mediarithmics.io/user-points/user-identifiers/userdevicetechnicalid#user_agent_id "mention") for more details on `$user_agent_id` format
{% endhint %}

The session storage is specific to each browser tab and is erased when the tab is closed, making this storage temporary.