> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unifygtm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage guide

> Learn how to send events using the Unify Intent Client.

> [!TIP]
>
> The Unify Intent Client can be used to log user activity across multiple subdomains of the
> same top-level domain. For example, if a user visits your marketing website at `www.yoursite.com`
> and then logs into your production web application at `app.yoursite.com`, the activity in both
> places will be attributed to the same person.

## Event types

### Page view events

Website page views are an indicator of buyer intent. You can log this information to the Unify platform for usage with the `page` method.

There are two ways to collect page data with the Unify intent client:

1. Automatic monitoring of the current page (see [here](#automatic-page-monitoring))
2. Manually via the client `page` method (see [here](#manual-page-logging))

Utilizing both of these methods when appropriate is recommended to take full advantage of intent data within Unify.

#### Automatic page monitoring

The Unify intent client is capable of automatically monitoring the user's current page to trigger page events. This will happen by default when the client is installed via the Unify JavaScript tag. If the client is installed via a package manager, you must pass the `autoPage` configuration option when instantiating the client. See [Configuration](#configuration) below for more details.

In either case, this behavior can be enabled or disabled programmatically via the `startAutoPage` and `stopAutoPage` methods on the client:

```TypeScript theme={null}
// Initialize the client and tell it to automatically monitor pages
const unify = new UnifyIntentClient(
  'YOUR_PUBLIC_WRITE_KEY',
  { autoPage: true },
);
unify.mount();

// Tell the client to stop monitoring pages
unify.stopAutoPage();

// Tell the client to start monitoring pages again
unify.startAutoPage();
```

#### Manual page logging

You can also manually trigger a page event with the `page` method on the client. This is useful when you do not want to trigger page events for *every* page.

```TypeScript theme={null}
const unify = new UnifyIntentClient('YOUR_PUBLIC_WRITE_KEY');
unify.mount();

// Trigger a page event for whatever page the user is currently on
unify.page();

// Trigger a page event for a custom page that the user is not necessarily on
unify.page({ pathname: '/some-custom-page' });
```

### Identify events

All intent data collected for users by Unify is anonymous by default. When intent events are logged, Unify will attempt to identify the company associated with a user’s IP address, but their personal identity will remain anonymous until an identify event is triggered for them.

There are two ways to collect identity data with the Unify intent client:

1. Automatic monitoring of email input elements (see [here](#automatic-input-monitoring))
2. Manually via the client `identify` method (see [here](#manual-identification))

Utilizing both of these methods when appropriate is recommended to take full advantage of intent data within Unify.

#### Automatic input monitoring

The Unify intent client is capable of automatically monitoring text and email input elements on the page to collect user identity. This will happen by default when the client is installed via the Unify JavaScript tag. If the client is installed via a package manager, you must pass the `autoIdentify` configuration option when instantiating the client. See [Configuration](#configuration) below for more details.

In either case, this behavior can be enabled or disabled programmatically via the `startAutoIdentify` and `stopAutoIdentify` methods on the client:

```TypeScript theme={null}
// Initialize the client and tell it to automatically monitor inputs
const unify = new UnifyIntentClient(
  'YOUR_PUBLIC_WRITE_KEY',
  { autoIdentify: true },
);
unify.mount();

// Tell the client to stop monitoring inputs for now
unify.stopAutoIdentify();

// Tell the client to start monitoring inputs again
unify.startAutoIdentify();
```

#### Manual identification

You can also manually trigger an identify event with the `identify` method on the client. This is useful when users log in with OAuth or SSO, for example, because they do not enter their email into an input on the page.

When using this method, you can also optionally specify a set of Person or Company attributes to upsert and associate with the identified user. This is done in the form of an optional second argument to `identify`.

```TypeScript theme={null}
const unify = new UnifyIntentClient('YOUR_PUBLIC_WRITE_KEY');
unify.mount();

// However you determine the currently logged-in user
const currentUser = getCurrentUser();

// Identify the current user
unify.identify(currentUser.emailAddress);

// OR identify the current user and upsert the associated Company/Person in Unify
unify.identify(
  currentUser.emailAddress,
  {
    person: {
      email: currentUser.emailAddress,
      first_name: currentUser.firstName,
      last_name: currentUser.lastName,
    },
    company: {
      domain: currentUser.organization.domain, // must match domain of email above
      name: currentUser.organization.name,
    }
  }
)
```

### Custom events

Certain user actions are valuable indicators of buying intent. You can use custom events to log these events along with custom properties for each event that you can then use within Unify to filter your visitors and act accordingly.

There are three ways to fire custom events with the Unify intent client:

1. Manually via the client `track` method (see [here](#manual-tracking))
2. Custom HTML data attributes (see [here](#html-data-attributes))
3. Automatically with CSS selectors (see [here](#automatic-tracking))

#### Manual tracking

You can also manually trigger a custom event with the `track` method on the client:

```TypeScript theme={null}
const unify = new UnifyIntentClient('YOUR_PUBLIC_WRITE_KEY');
unify.mount();

// Only the event name is required - we recommend spaces between capitalized words
unify.track('See More Button Clicked');

// You can also specify custom properties to include
unify.track('Modal Opened', { modalName: 'Contact Sales Modal' });
```

The `track` method accepts two arguments:

1. A string `name` (required) - this is used to identify the event downstream within Unify.
2. An object of keys and string values `properties` (optional) - this is used to specify custom properties associated with the event which can be used for filtering and identification downstream within Unify.

#### HTML data attributes

You can leverage various data attributes in the HTML of your site or application to automatically track click events for elements you care about:

##### `data-unify-click-event-name`

The presence of this attribute on an element indicates that the intent client should automatically fire an event when the element is clicked. The *value* of this attribute defines the **name** of the event which will be fired. For example, clicking the `button` in the following HTML will result in a custom event with the name `See More Button Clicked` to be fired:

```html theme={null}
<button data-unify-click-event-name="See More Button Clicked">See more</button>
```

By default, the intent client will make a best effort at identifying a **label** for the clicked element to include in the **properties** of the event which is fired. It will do so using the text content and ARIA attributes of the element. This can be used to differentiate between custom events with the *same name* fired for *different elements*. If the client is not able to determine a human-readable label, the `label` property will simply be omitted from the event properties. For example, clicking the `div` in the following HTML will result in a custom event with the name `Download Button Clicked` to be fired with `properties` containing a `label` with the value `Free sample`:

```html theme={null}
<div data-unify-click-event-name="Download Button Clicked">Free sample</div>
```

##### `data-unify-label`

This attribute can be used to override the label (or provide a label which is otherwise missing) for an element that is tracked by the client. For example, even though clicking the `button` in the following HTML would normally result in a custom event with the label `See more` to be fired, the presence of the `data-unify-label` attribute results in the event being fired with a `label` property of `Custom label`:

```html theme={null}
<button
  data-unify-click-event-name="See More Button Clicked"
  data-unify-label="Custom label"
>
  See more
</button>
```

##### `data-unify-event-prop-*`

By default, only the label of an element is included in the `properties` of auto tracked events. You can specify additional properties to include using the prefix `data-unify-event-prop-`. For example, clicking the `button` in the following HTML will result in an event being fired with `properties` including a property of `customValue` set to `100`:

```html theme={null}
<button
  data-unify-click-event-name="See More Button Clicked"
  data-unify-event-prop-custom-value="100"
>
  See more
</button>
```

#### Automatic tracking

The Unify intent client is capable of automatically monitoring elements that match a list of CSS selectors specified by you in the `UnifyIntentClientConfig`'s `autoTrackOptions.clickTrackingSelectors`. When an element matching one of these selectors is clicked by the user, the client will automatically fire an event for it.

`clickTrackingSelectors` can be a list of simple CSS string selectors, in which case the default event name `Element Clicked` will be used:

```typescript theme={null}
const options: AutoTrackOptions = {
  clickTrackingSelectors: ['.button', '.another-custom-selector'],
};

// Will fire `Element Clicked` events for clicked elements matching CSS selectors
const unify = new UnifyIntentClient('YOUR_PUBLIC_WRITE_KEY', {
  autoTrackOptions: options,
});
```

Alternatively, you can customize the event name fired for each selector by passing a list of objects for `clickTrackingSelectors`, where each object contains a `selector` string and optional `eventName` which will be used as the name of the auto tracked event:

```typescript theme={null}
const options: AutoTrackOptions = {
  clickTrackingSelectors: [
    { selector: '.button', eventName: 'Button Clicked' },
    {
      selector: '.another-custom-selector',
      eventName: 'Custom Element Clicked',
    },
  ],
};

// Will fire events with specified custom names for clicked elements matching CSS selectors
const unify = new UnifyIntentClient('YOUR_PUBLIC_WRITE_KEY', {
  autoTrackOptions: options,
});
```

You can use the `data-unify-label` to customize the element `label` in the event `properties` and the `data-unify-event-prop-` prefix to add custom `properties`. See [HTML data attributes](#html-data-attributes) for more info.

If you would like to exclude a specific element from tracking which matches your specified CSS selectors list, you can do so with the `data-unify-exclude` attribute.

This behavior can be enabled or disabled programmatically via the `startAutoTrack` and `stopAutoTrack` methods on the client:

```TypeScript theme={null}
// Initialize the client and tell it to automatically track clicks for all elements with class="button"
const unify = new UnifyIntentClient(
  'YOUR_PUBLIC_WRITE_KEY',
  { autoTrackOptions: { clickTrackingSelectors: ['.button'] } },
);
unify.mount();

// Tell the client to stop monitoring buttons for now
unify.stopAutoTrack();

// Tell the client to start monitoring buttons again
unify.startAutoTrack();

// OR tell the client to start monitoring something else
unify.startAutoTrack({ clickTrackingSelectors: ['.custom-button'] });
```

## Server side

It is possible to send requests to the Unify Intent API directly. You might do this on a web server, for example, to circumvent ad blockers. The Unify client exposes a method for each of its event types (`page`, `identify`, and `track` events) which can be used to generate the request payload for each event. This payload can then be sent to your web server which functions as a proxy to forward the request directly to the Unify Intent API.

The three methods on the client for generating event payloads are the following:

* `getPagePayload`
* `getIdentifyPayload`
* `getTrackPayload`

Below is an example of using the `getIdentifyPayload` method in a React app to generate the payload for an `identify` event, send it to a proxy web server, and forward it to the Unify Intent API.

```tsx client.tsx theme={null}
// However you make requests to your web server
const apiClient = useApiClient();

// However you get your current user object
const currentUser = useCurrentUser();

// Get the Unify client
const unify = useUnifyIntent();

useEffect(() => {
  if (currentUser.email) {
    const payload = unify.getIdentifyPayload(currentUser.email);

    // If the email is valid
    if (payload) {
      // Send event to server
      apiClient.post('/identify', payload);
    }
  }
}, [currentUser, unify, apiClient]);
```

```TypeScript server.ts theme={null}
const unifyClient = axios.create({
  // The Unify Intent API URL
  baseURL: 'https://api.unifyintent.com/analytics/v1',
  headers: {
    'Content-type': 'application/json; charset=UTF-8',
    // Your public write key which can be found at https://app.unifygtm.com/dashboard/settings/integrations/unify-intent-client
    'X-Write-Key': 'wk_5fTtsDLJ_7vx9DsjPcr79yk4FweES727w59pxS8EJ',
  },
});

router.post(
  '/identify',
  async (req: Request, res: Response) => {
    // Forward the event to the Unify Intent API
    const response = await unifyClient.post('/identify', req.body);

    return res.status(200).json({
      success: response.status === 200,
    });
  }
);
```

## Third-party tools

The intent client ships with out-of-the-box event tracking for some popular third-party tools such as [Default](https://www.default.com/) and [Navattic](https://www.navattic.com/). If these tools are embedded into a page where the intent client is running, the client will track relevant events automatically. This behavior can be disabled with the `UnifyIntentClientConfig`.

See [Configuration](#configuration) for more details on configuring the intent client.

### Default

[Default](https://www.default.com/) is a popular tool for automating inbound form submission workflows. If you use a Default form wherever the intent client is running, the client will automatically fire events for corresponding Default form events. The following Default form events are supported:

| Default event | Unify event name | Unify event properties | Description |
| - | - | - | - |
| `default.form_completed` | `Default Form Completed` | `form`, `formId` | When a user completes all steps in a form. |
| `default.form_page_submitted` | `Default Form Page Submitted` | `form`, `formId`, `pageNumber` | When a user completes one step in a form. |
| `default.meeting_booked` | `Default Meeting Booked` | `memberName`, `memberEmail`, `durationInMinutes`, `startDateTime` | When a user successfully books a meeting via the Default scheduler. |
| `default.scheduler_closed` | `Default Scheduler Closed` | | When a user closes the Default scheduler UI. |
| `default.scheduler_displayed` | `Default Scheduler Displayed` | `formId` | When the Default scheduler UI is displayed to the user. |

### Navattic

[Navattic](https://www.navattic.com/) is a popular tool for automating interactive product demos. If you use a Navattic demo wherever the intent client is running, the client will automatically fire events for corresponding Navattic demo events. The following Navattic demo events are supported:

| Navattic event | Unify event name | Unify event properties | Description |
| - | - | - | - |
| `START_FLOW` | `Navattic Demo Started` | `demo` | When a user starts a Navattic demo. |
| `VIEW_STEP` | `Navattic Demo Step Viewed` | `demo`, `step` | When a user views a new step of the demo. |
| `COMPLETE_FLOW` | `Navattic Demo Completed` | `demo` | When a user successfully completes the entire demo. |

## Configuration

**autoPage** `boolean` (default: false)

> [!NOTE]
>
> If installed via the [Unify Website tag](https://docs.unifygtm.com/developers/intent-client/website-tag.md) then the `autoPage` config will default to `true`.

Tells the client to automatically log page events whenever the current page changes.
Works for static websites and Single Page Apps. Also logs a page event for the initial page.

**autoIdentify** `boolean` (default: false)

> [!NOTE]
>
> If installed via the [Unify Website tag](https://docs.unifygtm.com/developers/intent-client/website-tag.md) then the `autoIdentify` config will default to `true`.

Tells the client to automatically monitor text and email input elements on the
page for changes. When the current user enters a valid email address into an input, the client
will log an identify event for that email address.

**autoTrackOptions** `AutoTrackOptions`

Options to customize automatic tracking of user actions such as click events.

**properties**

**clickTrackingSelectors** `string[] | \{ selector: string; eventName?: string \}[]`

Optional list of CSS selectors to customize which elements the client will automatically fire a custom event for when clicked.
Can be a list of string selectors, in which case the default event name `Element Clicked` will be used as the event name.
Can also be a list of objects containing a `selector` key and `eventName` key, in which case the value of `eventName` will be used as the event name.

**defaultForms** `DefaultFormAutoTrackOptions`

By default, the intent client will fire custom events for [Default](https://www.default.com/) form events.
This option can be used to customize which Default form events will result in Unify events being fired or disable this behavior entirely.

**navatticProductDemos** `NavatticDemoAutoTrackOptions`

By default, the intent client will fire custom events for [Navattic](https://www.navattic.com/) product demos.
This option can be used to customize which Navattic demo events will result in Unify events being fired or disable this behavior entirely.

**sessionDurationMinutes** `number` (default: 30)

Length in minutes that user sessions will persist when no activities are tracked. Activities include `page`, `identify,` and `track` activities.

## Cookies

> [!NOTE]
>
> This section only applies to intent client versions `1.4.0` and up. If you install the intent client with the website tag, you automatically get access to the latest client version. Versions older than this use obfuscated cookie names.

When the intent client mounts, it places two values in the user's cookies:

* `unify_visitor_id` - A randomly generated UUID which uniquely identifies the user. This persists across sessions.
* `unify_session_id` - A randomly generated UUID which uniquely identifies the user's current session. Sessions will persist as long as a new `page`, `identify`, or `track` event is fired at least once every 30 minutes. This duration be customized with the `sessionDurationMinutes` option on the `UnifyIntentClientConfig`.

These cookies are *first-party cookies* and associated with the top-level domain where the intent client is running.

**Example**

If the intent client is running on [https://www.unifygtm.com](https://www.unifygtm.com) then the cookies will be associated with `.unifygtm.com`. This means that they are accessible and reused across all subdomains of the top-level domain.

In this example, if the intent client were also running on [https://app.unifygtm.com](https://app.unifygtm.com) then a visitor ID stored while on the `www` subdomain would be reused on `app` subdomain.

These cookies are stored for the maximum permitted time by Google Chrome of 400 days and updated every time the visitor visits your site. In other words, as long as the same visitor visits your site at least once every 400 days and does not clear their browser cookies, their visitor ID will be reused across sessions. Note that some browsers have default limits lower than 400 days. In these cases, the maximum allowed limit by the browser will be used.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.