# Optimizing your email outreach
Source: https://docs.unifygtm.com/best-practices/deliverability
Best practices for writing email copy and optimizing deliverability.
## Sequence copy
1. **Keep an individual sequence to 4 email touches max -** Within a four-touch sequence, we recommend alternating the structure between 2 new threads and 2 follow-up replies. The copy of these follow-up replies can be short and limited to 1-2 sentences. Example: "Any thoughts on my previous note?"
2. **Alternate case studies and value props between new threads -** You should vary the copy and angle you're approaching to pitch your product in email steps 1 and 3. For example, you can highlight different customer case studies or statistics across both emails.
3. **Shorten subject line and use personalization -** Keep subject titles concise and add custom variables to increase variability. This approach will also help improve deliverability. Example: "Unify x (Your Company Name)"
4. **Include statistics and case studies for social proof -** Incorporating numbers-driven, concise impact statements can catch your prospect's attention. We recommend adding concise blurbs from customer case studies into your sequence copy.
5. **Add personalization with snippets -** You can use Unify's smart snippets to personalize copy based on relevant value prop, job title, work description, industry, and more. This will make your sequence copy more compelling with targeted pain points, use cases, or case studies. More variance in email copy will also help with deliverability.
6. **Keep it concise, focus on a single product or pain point -** Don't try to fit too many points into your email - you want to be decisive and mention the most relevant product or pain point to that individual to capture their attention! Keep the language simple and avoid business jargon. We recommend keeping each email between 50-200 words.
7. **End with a compelling call to action (CTA) -** Conclude each email with a clear, specific, and actionable request. This could include scheduling a call, booking a demo, or asking the prospect to reply with a specific piece of information relevant to their needs.
## Deliverability
1. **Limit the links -** Try not to overload your emails with multiple or duplicate links. Too many links can set off spam alarms - we recommend limiting the email touch to include 1-2 links maximum.
2. **Check link safety -** Ensure the links you include are secure and no warnings are displayed by the browser when visiting them.
3. **Mix up subject lines -** Don't stick with the same old subject lines, use template variables to keep them dynamic and interesting.
4. **No all caps -** Using all caps anywhere in your email can make it look like spam, so stick to normal capitalization.
5. **Easy on the exclamation -** Too many exclamation points can trigger spam filters, especially in the subject line. Use them sparingly!
6. **Send from multiple email addresses -** Sending emails from multiple mailboxes improves deliverability by distributing volume across different IP addresses and domains. This approach reduces the risk of being flagged as spam and increases overall sending capacity.
7. **Proofread for Typos**: Typos can make your email look unprofessional, especially when you're emailing multiple contacts at a company. Make sure to proofread and catch any errors.
# Booking meetings with Plays
Source: https://docs.unifygtm.com/best-practices/plays
Best practices for using Unify Plays to book meetings from intent signals.
## Best practices
Unify is a sales engagement platform designed to help you generate pipeline. To ensure that you see the best results, we recommend a few general principles:
* **Act Quickly:** Act on intent signals within 24-48 hours to catch prospects before they make their decision. Intent gets stale over time.
* **Engage with Every Lead:** Once you define your ICP in Unify, avoid selective outreach. Avoid introducing bias into how you prospect.
* **Multiple Touchpoints:** If you’ve found that a channel works best for your team, use Unify to lean into that. Unify excels at email - if that’s your preferred channel, great. If not, use email in combination with social or phone outreach. See section 4 below to see our recommendations for email and social outreach.
## Act on intent
There are two primary ways to act on intent data in Unify:
### Automatic Plays
* **When to use:** Both for low and high volume signals. Plays automate prospecting, qualifying, sequencing, and syncing leads to your CRM.
* **Benefits:** Reduce friction and improve intent to meeting booked conversion by immediately taking action on leads.
* Learn more about how to build Plays in [How to create a Play](/tutorials/how-to-create-a-play).
### Manual alerts
* **When to use:** Ideal for low volume, high value signals. It's important to ensure the sales team is accountable for acting on alerts to ensure hot leads don’t slip through the cracks.
* **Benefits:** Immediate and contextual information delivered to where your team is working.
* Most reps use Slack alerts to trigger manual workflows. Learn how to set these up in our [Slack integration guide](/reference/integrations/slack#slack-integration-guide)
## Intent-based Plays
Intent signals are indicators that there’s an opportunity to sell your product or book an intro meeting. Our customers have seen success with these intent-based Plays:
1. **Pricing Page Visits:** Checking out pricing pages indicates that prospects are considering a purchase decision.
2. **[Repeat Buyers](https://www.unifygtm.com/plays/champion-tracking---outbound-to-past-customers-who-have-moved-jobs):** When someone you’ve sold to before is back on the website demonstrating high intent. This works well for businesses that have more transactional sales.
3. **[Inbound Form Submissions](https://www.unifygtm.com/plays/outbound-to-website-form-submitters):** A form submission is one of the strongest signs of intent. Convert those leads immediately by automating outreach as soon as they submit.
4. **[New Hires](https://www.unifygtm.com/plays/outbound-to-people-who-have-started-jobs-at-a-new-company):** People are more likely to purchase new tools in their first few months on a job. Targeting ICP fits that have just changed jobs can convert better.
5. **[Support Docs](https://www.unifygtm.com/plays/outbound-to-contacts-viewing-your-technical-docs):** Interest in support docs (e.g., integration details), suggests prospects are trying to understand how your product works and if it would work for them.
6. **[Product Tour Visits](https://www.unifygtm.com/plays/outbound-to-people-who-view-your-product-demo):** Interest in demo videos or product tours indicates a desire to understand specific product offerings in more granularity.
7. **[Retarget Paid Traffic](https://www.unifygtm.com/plays/retarget-paid-traffic):** Get more out of your spend on paid traffic by retargeting people based on UTM filters.
8. **[Closed-Lost Opportunities](https://www.unifygtm.com/plays/retarget-closed-lost-opportunities-when-they-revisit-website):** A revisit to your site by a closed-lost opportunities signals the prospect might be interested in re-engaging.
## Nailing email or social outreach
Nailing email and social messages is key to booking the most possible meetings from Unify. A few guiding principles:
1. **Use Soft Messaging:** Use your judgement, but we typically recommend against direct mentions of website activity. Instead, tailor messages to address the pain points related to the product or service they showed interest in.
2. **Keep It Short:** Many senior leaders at your target accounts read emails on their phones, concise messages under 100 words are more likely to be read and understood. Remember that people are skimming emails.
3. **Persona-Specific Messaging:** Address specific pain points and perspectives of the different personas you sell to (e.g., sales and marketing for us). Avoid generic messages that try to cater to multiple personas, as they may resonate with none.
4. **Focus on One Product:** If you sell multiple products, pitch one per email. This approach minimizes the chances that your prospect gets confused about what you solve.
5. **Highlight Relevant Pain Points:** Rather than pitching your product, focus on speaking to a specific challenge or pain point that your prospect has. Educate the prospect on your product once you’re on the phone with them.
# Writing AI prompts
Source: https://docs.unifygtm.com/best-practices/prompting
Best practices for writing prompts for AI in Unify.
## General tips
Unify has multiple AI features that can be used to improve qualification and outreach outcomes. To set yourself up for success, we recommend a few general principles for prompting when using these features:
* **Clear Instructions:** Be explicit about what you want the AI to do. Providing a clear set of instructions will help the AI understand what you want to accomplish and what steps to follow to complete the tasks.
* **Length ≠ Quality:** Writing an overly detailed or essay length prompt does not mean that the AI will provide a better response. Excessive information can be detrimental unless it is well-structured and explained, as it can lead to confusion and misinterpretation of the prompt.
* **Provide Context:** Assume AI does not know your industry, company, or product as well as you do. Provide relevant context as you reference information about your company or your goals. For example, if you are referencing a niche keyword, provide a brief explanation of what it means, how it relates to your business, and the task you are giving the AI.
## AI agents
There are two primary ways that you can provide information and instruction to Unify's AI Agents.
### Questions
* **Questions:** Questions are the minimum required input to run an AI Agent. You can ask any question about a Company or Person and select the type of response you want the Agent to provide (e.g., True/False, Text, Multi-Select, Number).
* **What information to provide:** In the question, only include the research question you want the Agent to answer. Avoid adding clarifying information or instructions to keep it focused.
### Guidance
* **When to use:** Guidance is an optional field for AI Agents that enables you to provide additional context or instructions to the AI Agent. When asking more complex questions, when you have a set of instructions or requirements that you want the AI Agent to follow, or when you want to provide clarification on the research question, guidance is the best way to provide that information.
* **How To Structure Guidance:** Similar to Prompts, Guidance should be clear, concise, and specific. Use the guidance to provide specific directions about each question that you are asking, and additional context if there is a specific way that you want the AI Agent to conduct its research. For example, if you want the AI Agent to only use information from a specific source, you can include that information in the guidance. Or, if you want to provide more direction on when the AI Agent should select a specific answer for a multi select response type, that information should also be included in the guidance.
## Smart snippets
Smart Snippets are a powerful way to personalize messaging to your prospects.
* **Provide Context (Again!):** The model can only act on what you provide. This means you should specify the information you want to create copy from, select template variables to reference, or add Agent template variables to the Smart Snippet. Additionally, provide context around the template variable to create a coherent prompt. Think of template variables as placeholders for information and write sentences or blurbs surrounding those variables.
* **Adding References:** A common mistake is referencing information that you haven't provided to the model, which can lead to incorrect responses. To prevent this, ensure that if you're referencing data provided through a template variable or Agent output, you include that template variable in the Snippet.
### Agent outputs in Smart snippets
Using Agents to conduct research and then incorporating that research into a Smart Snippet is a great way to hyper-personalize your messaging. To make effective use of this feature:
* **Separation of Concerns:** Use the Agent to conduct research only, and use the Snippet to generate the copy. Each feature is optimized for its respective task.
* **Structure the Snippet prompt around the Agent variables:** When writing a Smart Snippet prompt with Agent output template variables, provide context and labels about what each Agent output contains so the Snippet can handle it accordingly. For example, if you have an Agent Question that asks for a True/False or Number answer, write your prompt using the Agent template variable as a placeholder in your sentences to provide context to the Snippet.
* For example, if your Agent question was "What is the most recent product launch from this company?" then your Snippet prompt should be something like: "Research indicates that this company just launched `{{Agent Question}}`. Write a sentence to congratulate them on the launch."
## AI research
AI Research is a powerful way to automate and customize research that you want to conduct about any company that you are engaging. AI Research is powered by Unify's Observation Model, which is the system that Unify uses to run completely customized research for your company on your prospects.
### Prompting AI research
Writing prompts for AI Research is slightly different from writing prompts for AI Agents. AI Research is designed to read as much relevant information as possible before generating a report for you. We recommend following the style of the Observation prompts we generated for you as a starting point. To prompt for AI Research, follow these guidelines:
* **Pick a General Signal:** The goal with an Observation prompt is to describe a specific piece of information to the system that you'd like to monitor for any given company. For example, if you know that a company using a specific technology has a high likelihood of becoming your customer, an Observation for that could be: "Company uses an outbound sequencer (Outreach, Salesloft, Apollo, etc.) and a data/intent source (ZoomInfo, 6sense, Bombora, Clearbit, Demandbase, G2 Intent)."
* **Test and Iterate:** Once you've written your prompt, take advantage of the settings page to generate examples and see what the resulting reports look like.
# Custom events
Source: https://docs.unifygtm.com/developers/api/analytics/custom
POST /track
Send a "track" event.
# Identify events
Source: https://docs.unifygtm.com/developers/api/analytics/identify
POST /identify
Send an "identify" event.
# Unify Analytics API
Source: https://docs.unifygtm.com/developers/api/analytics/overview
Send website and product analytics data into the Unify platform.
## Overview
The Analytics API allows you to send both client-side and server-side events
into Unify. There are three types of events you can send:
* [Page events](/developers/api/analytics/page) capture page visits on your website or web application
* [Custom events](/developers/api/analytics/custom) capture actions or other custom activities that you define
* [Identify events](/developers/api/analytics/identify) capture visitor identity information (e.g., their email address)
These event types form the building blocks to track visitor behavior and actions
on your marketing website, web application, or other custom software.
## Usage
### Request format
The base URL of all API requests to the Analytics API is:
```shell theme={null}
https://api.unifyintent.com/analytics/v1
```
Note that the base URL uses a different domain than other Unify APIs.
### Authentication
When sending requests to the Analytics API from client devices, you should use
your **write key** rather than an API key. Write keys are safe to expose
publicly whereas API keys are not.
To prevent exposure of sensitive API keys, if you send a request to
the Analytics API that contains an API key by accident, Unify will immediately
expire the key as a precautionary measure.
Write keys are used to authenticate requests to the Analytics API. You can find
your write key in Unify by navigating to [Settings → Unify Intent Client](https://app.unifygtm.com/dashboard/settings/integrations/unify-intent-client).
To authenticate a request, include the following header in your request:
```http theme={null}
X-Write-Key:
```
Replace `` with your Unify write key.
### Rate limits
The Analytics API is rate-limited by default to 100,000 requests per five minute
window. We are able to provide higher limits upon request if needed.
### OpenAPI specification
The OpenAPI specification can be found [here](https://api.unifyintent.com/analytics/v1/openapi.json).
# Page events
Source: https://docs.unifygtm.com/developers/api/analytics/page
POST /page
Send a "page" event.
# Connect product usage data to Unify
Source: https://docs.unifygtm.com/developers/guides/product-usage-data/introduction
Send web application and software usage data into Unify.
This guide is focused on web applications and software where the goal is to
track usage and interactions of identifiable users. If you are looking to send
events from marketing or other public-facing website, [Connect website traffic to Unify](/developers/guides/website-traffic/introduction)
may be more relevant.
## Overview
One of the most powerful strategies in Unify is to identify existing customers
and users to reach out to based on their product usage and behavior. By sending
product usage data into Unify, you can instantly launch Plays to start taking
action on these users.
Some examples of the ways this data can be used include:
* **Free plan conversions** — Identify free plan users who are actively using
key features and send them targeted upgrade campaigns.
* **Upsells and cross-sells** — Identify existing customers who are using
specific features and send them relevant upsell or cross-sell offers.
* **Enterprise expansion** — Identify individual users at companies, reach out
to other contacts at those companies, and target them with enterprise offers.
Unify provides a full suite of [analytics APIs](/developers/api/analytics/overview)
for tracking user interactions and identities. All event tracking capabilities
integrate natively with the rest of the Unify data layer. This makes it easy to
link product usage data to companies or people and access that data throughout
Unify.
## Setup
Unify provides an SDK called the [Unify Intent Client](/developers/intent-client/overview)
that can be installed in your web application to start sending events. This is
the easiest and recommended way to get started.
}
href="/developers/guides/product-usage-data/unify-intent-client"
>
Send events using the Unify's native JavaScript or React client.
If you're already collecting events using a third-party tool, you can also send
that data into Unify using either a supported integration or the general-purpose
[Analytics API](/developers/api/analytics/overview). You can find guides for
some popular tools below.
} href="/reference/integrations/segment">
Send Segment events into Unify.
}
href="/reference/integrations/posthog"
>
Send Posthog events into Unify.
Lastly, if you already collect product usage data in a database, data warehouse,
or data lake, you can connect those systems directly to Unify. For details, see
[Connect data systems to Unify](/developers/guides/data-systems/overview).
Analytics events (such as page, identify, and custom events) cannot currently
be sent into Unify via reverse ETL tools like [Hightouch](https://hightouch.com/)
or [Fivetran](https://www.fivetran.com/). This capability is coming soon.
In the meantime, the recommended solution is to send data to the [Analytics API](/developers/api/analytics/overview)
directly or via one of the supported integrations listed above. Alternatively,
you can create [custom objects](/developers/guides/data-systems/overview) to
represent these events and send them via reverse ETL.
## Examples
Once you've configured events to be sent into Unify, you can start using that
data to launch Plays based on user intent. See the following guides for
examples.
Identify users when they sign in to your application.
Track in‑app user activity with the Unify Intent client.
# Set up the Unify Intent client
Source: https://docs.unifygtm.com/developers/guides/product-usage-data/unify-intent-client
Send product usage and events directly into Unify with the native SDK.
## Installation
There are multiple ways to install the Unify Intent client depending on your
setup. When installing the client into the web application for your product,
using either the JavaScript client or the React client is recommended.
Install the client in your React web application for a more native
integration.
Install the client in your non-React frontend application, such as a Single
Page App (SPA).
You should only use one installation method per website or application. If the
client is installed twice on the same site, it may not work correctly.
## Usage
### Automatic events
By default, the React library will not automatically collect any events. You
can enable automatic event collection when initializing the client. See the
full [Usage guide](/developers/intent-client/usage-guide) for more details.
### Manual events
You can manually trigger events in specific places in your web application
by calling the client directly.
#### Page events
Page events record a page visit. Typically, the easiest strategy is to
enable automatic collection of page visits, but you can also call them
manually.
```javascript theme={null}
// Enable automatic "page" event collection
unify.startAutoPage();
// Send a "page" event
unify.page();
```
#### Custom events
Custom events record specific actions taken by a visitor, such as button
clicks or form fills. You can send custom events with arbitrary
properties anywhere in your React application.
```javascript theme={null}
// Send a basic custom event
unify.track("See More Button Clicked");
// Send a custom event with additional properties
unify.track("Modal Opened", {
modalName: "Contact Sales Modal"
});
```
#### Identify events
Identify events link a visitor to a specific company or person. You can send
identify events whenever you have information about a visitor, such as their
name or email address.
```javascript theme={null}
// Send a basic "identify" event
unify.identify("user@email.com");
// Send an "identify" event with additional company or person attributes
unify.identify("first.last@acme.com", {
person: {
email: "first.last@acme.com",
first_name: "First",
last_name: "Last",
},
company: {
domain: "acme.com",
name: "Acme Corp.",
}
});
```
### Automatic events
By default, the JavaScript library will not automatically collect any
events. You can enable automatic event collection when initializing the
client. See the full [Usage guide](/developers/intent-client/usage-guide)
for more details.
### Manual events
You can manually trigger events in specific places in your web application
by calling the client directly.
#### Page events
Page events record a page visit. Typically, the easiest strategy is to
enable automatic collection of page visits, but you can also call them
manually.
```javascript theme={null}
// Enable automatic "page" event collection
unify.startAutoPage();
// Send a "page" event
unify.page();
```
#### Custom events
Custom events record specific actions taken by a visitor, such as button
clicks or form fills. You can send custom events with arbitrary
properties anywhere in your web application.
```javascript theme={null}
// Send a basic custom event
unify.track("See More Button Clicked");
// Send a custom event with additional properties
unify.track("Modal Opened", {
modalName: "Contact Sales Modal"
});
```
#### Identify events
Identify events link a visitor to a specific company or person. You can send
identify events whenever you have information about a visitor, such as their
name or email address.
```javascript theme={null}
// Send a basic "identify" event
unify.identify("user@email.com");
// Send an "identify" event with additional company or person attributes
unify.identify("first.last@acme.com", {
person: {
email: "first.last@acme.com",
first_name: "First",
last_name: "Last",
},
company: {
domain: "acme.com",
name: "Acme Corp.",
}
});
```
For complete instructions, see the [Usage guide](/developers/intent-client/usage-guide).
# Capture user interactions
Source: https://docs.unifygtm.com/developers/guides/product-usage-data/user-interactions
Track in‑app user activity with the Unify Intent client.
## Overview
User interactions can be used to powerful Plays that drive activation, upgrades,
expansion, and more. By tracking key in‑app events, you can identify and engage
with users based on their actual product usage and behavior.
Some examples of interaction‑based Plays include:
* **Activation Plays** — Target users who clicked on or started using key
features but haven't yet completed the activation criteria.
* **Upsell Plays** — Reach out to users who encountered paywalls or usage limits
to offer assistance or upgrade options.
* **Expansion Plays** — Identify users who are actively using specific features
and target them with relevant cross-sell or upsell offers.
There is no limit to the number or types of interactions you can track. All the
activities you track can be linked to Company, Person, and other object records
in Unify. This gives a complete view of user behavior within the context of your
business.
## Prerequisites
* Ensure you've already installed the Unify Intent client in your application.
See [Set up the Unify Intent client](#setup) for instructions.
* Ensure your users are being identified when they log in. See
[Capture user logins](/developers/guides/product-usage-data/user-logins)
for a walkthrough.
## Examples
Custom events can be used to capture any type of user interaction within your
application. Below are some examples of common use cases and patterns for
recording user activity.
### Feature button clicked
When a user clicks a button to open or use a feature:
```ts theme={null}
unify.track('Created a Widget', {
feature: 'widget-builder',
type: 'gizmo',
number_created: 4,
});
```
### Paywall encountered
When a user hits a paywall or usage limit:
```ts theme={null}
unify.track('Widget Limit Reached', {
feature: 'widget-builder',
reason: 'plan_limit',
current_plan: 'Free Tier',
limit_reached: 10,
number_requested: 20,
});
```
If you present upgrade options, also track the click:
```ts theme={null}
unify.track('Upgrade CTA Clicked', {
destination: 'billing',
source: 'widget_paywall',
plan_selected: 'Pro',
});
```
### User added
When a user invites another user to their account:
```ts theme={null}
unify.track('User Invited', {
added_user_email: 'bob@acme.com',
role: 'Editor',
});
```
# Capture user logins
Source: https://docs.unifygtm.com/developers/guides/product-usage-data/user-logins
Identify users when they sign in to your application.
## Overview
All the activity you track in your application is associated with a *visitor*
who may or may not have a known identity. When a user signs in, you can send an
Identify event. This associate all their past and future activity with a known
Person (and optionally a Company) in Unify.
## Prerequisites
* Ensure you've already installed the Unify Intent client in your application.
See [Set up the Unify Intent client](#setup) for instructions.
## Walkthrough
### Identify on login
Call `identify` as soon as the user is authenticated. Include useful traits for
the person and (optionally) the company they belong to.
```ts theme={null}
// Determine the current user however you normally do so
const currentUser = getCurrentUser();
// Send an "Identify" event
unify.identify(currentUser.emailAddress, {
// Link this visitor to a Person
person: {
email: currentUser.emailAddress,
first_name: currentUser.firstName,
last_name: currentUser.lastName,
},
// If possible, link this visitor to a Company as well
company: currentUser.organization
? {
domain: currentUser.organization.domain,
name: currentUser.organization.name,
}
: undefined,
});
```
### Send custom event (optional)
You may also want to track that the user logged in. Identify events link
visitors to people or companies, but they don't record an activity that can be
seen or used in Unify. If you want to see when users login or filter Plays based
on login activity, you should also send a custom event.
```ts theme={null}
unify.track('User Logged In');
```
As with all custom events, you can also include additional properties to provide
more context about the login.
## Capture interactions
Now that visitors to your application are identified, you can start tracking key
in-app interactions to power Plays. For more information, see [Capture user interactions](/developers/guides/product-usage-data/user-interactions).
# Capture button clicks
Source: https://docs.unifygtm.com/developers/guides/website-traffic/button-clicks
Record button clicks and other interactions with the Unify Intent client.
## Overview
Website and product interactions are a strong indicator of a visitor's goal. For
example, a visitor to your marketing website who interacts with a pricing
calculator is much more likely to be an interested buyer than the average
visitor.
In Unify, you capture these types of interactions by sending a custom event when
buttons or website components are clicked. If a visitor is then identified
(e.g., from another form fill or based on company IP matches), their
interactions can be viewed in Unify and used to run Plays.
## Prerequisites
* Ensure you've already installed the Unify Intent client on your website.
See [Set up the Unify Intent client](#setup) for instructions.
## Example
Suppose you have a button that opens your pricing calculator. You can log this
interaction with a custom event that includes useful context as properties.
### Send a custom event
Call `track` when the button is clicked. Include properties that help with
attribution and routing later (e.g., `button_id`, page, placement, or variant).
```ts theme={null}
unify.track('Pricing Calculator Opened', {
button_id: 'pricing-calculator',
placement: 'pricing-page-hero',
});
```
### Send multiple custom events
There's no limit on the number of events you can send into Unify, and more data
is always better. You can fire off multiple custom events to capture
interactions at a more granular level.
For example, suppose your pricing calculator contains buttons to select which
pricing plan to view (e.g., "Basic," "Pro," "Enterprise"). You can send an event
each time this button is clicked:
```ts theme={null}
unify.track('Pricing Plan Selected', {
button_id: 'select-pro-plan',
plan: 'Pro',
});
```
Suppose that the pricing calculator also contains a slider to select the usage
quantity they expect to use. This information can be sent as well:
```ts theme={null}
unify.track('Pricing Quantity Selected', {
slider_id: 'usage-quantity',
credits_needed: '5000',
plan: 'Pro',
});
```
Now, you can run a Play that segments visitors based on what pricing tier they
are most likely to be interested in. Your reps will also know what usage tier
### Identifying the visitor
This example assumes the button click itself does not collect any information
about the visitor, such as name or email address. That's fine—if the visitor is
identified later (e.g., via form fill or IP match), Unify will link this event
to that person or company.
If you *do* have information about the visitor at click time, you should also
send an Identify event. This will immediately link the visitor to the person
or company you specify.
```ts theme={null}
// Send a basic "Identify" event
unify.identify('alice@acme.com');
// Send an "Identify" event with company and person information
unify.identify('alice@acme.com', {
person: {
email: 'alice@acme.com',
first_name: 'Alice',
last_name: 'Smith',
title: 'Product Manager',
},
company: {
name: 'Acme Inc.',
domain: 'acme.com',
},
});
```
You do not need to send an Identify event on every click. Send it wherever you
first learn the visitor's identity and then subsequent events will be linked
automatically.
## Launch a Play
With this custom event in place, you can create Plays in Unify that react to
high‑intent clicks like “Pricing Calculator Opened.” For example, a Play could:
1. Apply exclusions (competitors, open opportunities, current customers)
2. Launch an AI agent to research the company or person for ICP fit
3. Enroll the person in a follow‑up sequence
4. Prospect more contacts at the same company and enroll them in outreach
## FAQ
Include any information that may help you qualify and route interactions,
such as:
* Button or form identifier
* Values entered by the visitor
* Page or component context
* Variant (for A/B tests)
When in doubt, err on the side of including more properties.
# Capture form fills
Source: https://docs.unifygtm.com/developers/guides/website-traffic/form-fills
Record form submissions with the Unify Intent client.
## Overview
One of the most effective ways to capture leads on your website is through form
submissions. With Unify, you can capture these submissions and then run Plays on
them.
The Unify Intent client can be used to capture these form fills. This can be
achieved by firing two separate events:
* **Custom event** — This captures the submission and any data entered into the
form. Any Plays will be able to filter companies or people based on whether
they have a matching custom event.
* **Identify event** — This captures the identity of the visitor and links them
to a Company or Person in Unify. The Identify event is necessary to associate
the form submission with a specific Person or Company.
Typically, the simplest approach is to send both events at the same time when a
visitor completes and submits a form.
## Prerequisites
* Ensure you've already installed the Unify Intent client on your website.
See [Set up the Unify Intent client](#setup) for instructions.
## Example
Suppose you have a "demo sign-up" form that collects the following information:
* **First name** (e.g., `Alice`)
* **Last name** (e.g., `Smith`)
* **Email address** (e.g., `alice@acme.com`)
* **Company name** (e.g., `Acme Inc.`)
* **What are you most interested in seeing?** (e.g., `AI capabilities`)
To send this data into Unify, you should send two events.
### Send a custom event
First, send a custom event that records the form submission. The form fields can
be included as *properties* on the event. Properties are arbitrary key-value
pairs that can be viewed and used to filter events in Unify.
```ts theme={null}
unify.track('Demo Requested', {
form_id: 'demo-signup',
first_name: 'Alice',
last_name: 'Smith',
company: 'Acme Inc.',
interest: 'AI capabilities',
});
```
### Send an Identify event
Next, send an Identify event that associates the submission with a known person
(using their email address). You can also include additional traits about the
person and their company. These traits will appear on the Person and Company
records in Unify.
```ts theme={null}
unify.identify('alice@acme.com', {
person: {
email: 'alice@acme.com',
first_name: 'Alice',
last_name: 'Smith',
},
company: {
name: 'Acme Inc.',
},
});
```
## Launch a Play
With both events sent, you can now create Plays in Unify that run on the inbound
lead. Plays can be triggered based on the custom event (e.g., "Demo Requested")
and can use filters based on the properties you sent.
For example, a Play running on inbound form fills could:
1. Apply exclusions to ensure the inbound lead is not a competitor, open
opportunity, or existing customer
2. Launch an AI agent to research the company or person and qualify or
disqualify them based on ICP fit or other criteria
3. Enroll the person in an outbound sequence
4. Find a few more contacts at the same company that match your ideal buyer
persona and enroll them in another outbound sequence
## FAQ
If you don't have an email address to include in the Identify event, Unify
will not have a unique identifier to link this visitor to a person. However,
you have other options.
**Link to Company instead:**
If you have a company website, you can send an Identify event with the
visitor's company instead. This will not link the custom event to a specific
Person, but it will link it to a specific Company.
You can then run a Play on companies with matching custom events. That Play
can prospect for contacts at the company with ICP personas.
**Capture identity elsewhere:**
If the visitor does not provide an email address on the form, consider
capturing their identity elsewhere on your website. For example:
* If you have another sign-up form that collects email addresses, you can
send an Identify event when a visitor completes that form.
* If you link the custom event to a company, prospect for people at that
company, and then send sequence emails to them, you can track email link
clicks. When a person clicks a link in an email, their website activity
will be identified.
If the visitor is identified through other means, all of their past activity
will also be retroactively identified.
**Automatically identify Company:**
If you do not send an Identify event, Unify will still automatically attempt
to identify the visitor's Company using built-in matching providers based on
their IP address.
If you send an Identify event with a person's email address but no Company,
the default behavior is to extract the domain from the email address and
link the Person to a Company with that domain. This is not performed for
non-corpor
For example, if you identify a visitor as `alice@acme.com`, Unify will link
# Connect website traffic to Unify
Source: https://docs.unifygtm.com/developers/guides/website-traffic/introduction
Send website visitors, sessions, and events into Unify.
This guide is applicable to any website, but it is especially focused on
marketing websites. If you are looking to connect product usage or analytics
data from your web application, see [Connect product usage data to Unify](/developers/guides/product-usage-data/introduction)
for a more targeted guide.
## Overview
One of the most popular strategies in Unify is to identify the companies and
people who are visiting your website and accessing your content. By sending
website traffic data into Unify, you can instantly launch Plays to start taking
action on these visitors.
Unify can automatically identify companies visitors are associated with by using
a combination of built-in matching providers for high coverage and accuracy.
Unify also supports person-level identification through a combination of email
link click tracking, form fills, and [Identify events](/developers/api/analytics/identify).
All event tracking capabilities integrate natively with the rest of the Unify
data layer. This makes it easy to link website intent to companies or people and
access that data throughout Unify.
## Setup
Unify provides an SDK called the [Unify Intent Client](/developers/intent-client/overview)
that can be installed on your website to start sending visitor events. This is
the easiest and recommended way to get started.
}
href="/developers/guides/website-traffic/unify-intent-client"
>
Send events using the Unify's native JavaScript or React client.
If you're already collecting website traffic data using a third-party tool, you
can also send that data into Unify. This can be done using either a supported
integration or the general-purpose [Analytics API](/developers/api/analytics/overview).
You can find guides for popular tools below.
} href="/reference/integrations/segment">
Send Segment events into Unify.
}
href="/reference/integrations/posthog"
>
Send Posthog events into Unify.
## Examples
Once you've configured events to be sent into Unify, you can start using that
data to launch Plays based on visitor intent. See the following guides for
examples.
Record form submissions with the Unify Intent client.
Record button clicks and other interactions with the Unify Intent client.
# Set up the Unify Intent client
Source: https://docs.unifygtm.com/developers/guides/website-traffic/unify-intent-client
Send website events directly into Unify with the native SDK.
## Installation
There are multiple ways to install the Unify Intent client depending on your
setup. In most cases, the website tag is the best option to get started.
Paste a pre-configured JavaScript snippet in your website's HTML. This
method is the easiest way to get started and is suitable for most websites.
Install the client in your React web application for a more native
integration.
Install the client in your non-React frontend application, such as a Single
Page App (SPA).
You should only use one installation method per website or application. If the
client is installed twice on the same site, it may not work correctly.
## Usage
### Automatic events
Once the website tag is added, it will automatically start collecting
certain types of events:
* **Page events**: Every time a visitor loads a page on your website, a page
view event is sent to Unify. When that visitor is identified, all their
sessions will be linked to that identity.
* **Custom events**: Certain button clicks and interactions will be tracked
automatically. This does not cover all possible interactions, and you will
likely want to manually trigger events in specific places on your website
for more complete coverage.
* **Identify events**: When a visitor fills out a form with their email
address, they will be automatically identified and linked to that address.
Other information they fill out (such as first and last name) will not be
automatically recorded, so you may also want to manually send "identify"
events on form fills, logins, etc.
If desired, you can disable automatic event collection by setting specific
options when initializing the client. See the full [Usage guide](/developers/intent-client/usage-guide)
for more details.
### Manual events
You can manually trigger events in specific places on your website by
calling the client directly. When you include the tag in your HTML, you will
immediately be able to access the client at `window.unify` (or simply
`unify` since `window` is global).
#### Page events
Page events record a page visit. They are fired automatically by default
when using the website tag, but you can also call them manually.
```javascript theme={null}
// Send a "page" event
unify.page();
```
#### Custom events
Custom events record specific actions taken by a visitor, such as button
clicks or form fills. Some custom events are captured automatically when
using the website tag, but you can also send custom events manually.
```javascript theme={null}
// Send a basic custom event
unify.track("See More Button Clicked");
// Send a custom event with additional properties
unify.track("Modal Opened", {
modalName: "Contact Sales Modal"
});
```
#### Identify events
Identify events link a visitor to a specific company or person. Basic
identify events are sent automatically when a visitor fills out a form with
their email address, but you can also send more detailed identify events
when you have additional information.
```javascript theme={null}
// Send a basic "identify" event
unify.identify("user@email.com");
// Send an "identify" event with additional company or person attributes
unify.identify("first.last@acme.com", {
person: {
email: "first.last@acme.com",
first_name: "First",
last_name: "Last",
},
company: {
domain: "acme.com",
name: "Acme Corp.",
}
});
```
### Automatic events
By default, the React library will not automatically collect any events. You
can enable automatic event collection when initializing the client. See the
full [Usage guide](/developers/intent-client/usage-guide) for more details.
### Manual events
You can manually trigger events in specific places in your web application
by calling the client directly.
#### Page events
Page events record a page visit. Typically, the easiest strategy is to
enable automatic collection of page visits, but you can also call them
manually.
```javascript theme={null}
// Enable automatic "page" event collection
unify.startAutoPage();
// Send a "page" event
unify.page();
```
#### Custom events
Custom events record specific actions taken by a visitor, such as button
clicks or form fills. You can send custom events with arbitrary
properties anywhere in your React application.
```javascript theme={null}
// Send a basic custom event
unify.track("See More Button Clicked");
// Send a custom event with additional properties
unify.track("Modal Opened", {
modalName: "Contact Sales Modal"
});
```
#### Identify events
Identify events link a visitor to a specific company or person. You can send
identify events whenever you have information about a visitor, such as their
name or email address.
```javascript theme={null}
// Send a basic "identify" event
unify.identify("user@email.com");
// Send an "identify" event with additional company or person attributes
unify.identify("first.last@acme.com", {
person: {
email: "first.last@acme.com",
first_name: "First",
last_name: "Last",
},
company: {
domain: "acme.com",
name: "Acme Corp.",
}
});
```
### Automatic events
By default, the JavaScript library will not automatically collect any
events. You can enable automatic event collection when initializing the
client. See the full [Usage guide](/developers/intent-client/usage-guide)
for more details.
### Manual events
You can manually trigger events in specific places in your web application
by calling the client directly.
#### Page events
Page events record a page visit. Typically, the easiest strategy is to
enable automatic collection of page visits, but you can also call them
manually.
```javascript theme={null}
// Enable automatic "page" event collection
unify.startAutoPage();
// Send a "page" event
unify.page();
```
#### Custom events
Custom events record specific actions taken by a visitor, such as button
clicks or form fills. You can send custom events with arbitrary
properties anywhere in your web application.
```javascript theme={null}
// Send a basic custom event
unify.track("See More Button Clicked");
// Send a custom event with additional properties
unify.track("Modal Opened", {
modalName: "Contact Sales Modal"
});
```
#### Identify events
Identify events link a visitor to a specific company or person. You can send
identify events whenever you have information about a visitor, such as their
name or email address.
```javascript theme={null}
// Send a basic "identify" event
unify.identify("user@email.com");
// Send an "identify" event with additional company or person attributes
unify.identify("first.last@acme.com", {
person: {
email: "first.last@acme.com",
first_name: "First",
last_name: "Last",
},
company: {
domain: "acme.com",
name: "Acme Corp.",
}
});
```
For complete instructions, see the [Usage guide](/developers/intent-client/usage-guide).
# Install JavaScript package
Source: https://docs.unifygtm.com/developers/intent-client/js-client
Install the Unify Intent client in a frontend web application framework.
## Installation
You can install the Unify Intent JS Client with your preferred package manager:
```shell npm theme={null}
npm install @unifygtm/intent-client
```
```shell yarn theme={null}
yarn add @unifygtm/intent-client
```
```shell pnpm theme={null}
pnpm add @unifygtm/intent-client
```
```shell bun theme={null}
bun add @unifygtm/intent-client
```
## Usage
After installing the client, you must initialize it in your application code:
```ts index.ts theme={null}
import { UnifyIntentClient, UnifyIntentClientConfig } from '@unifygtm/intent-client';
const writeKey = 'YOUR_PUBLIC_WRITE_KEY';
const config: UnifyIntentClientConfig = {
autoPage: true,
autoIdentify: false,
};
const unify = new UnifyIntentClient(writeKey, config);
// Do not call mount during server side rendering. Only call it in a browser context.
unify.mount();
```
Be sure to only initialize the client one time in your application.
For details on how to use the client to send events, see the full [Usage guide](/developers/intent-client/usage-guide).
## Cleanup
When you are done using the client, if you wish to clean up the side effects
generated by it, you can do so with the `unmount` method:
```ts cleanup.ts theme={null}
import { UnifyIntentClient, UnifyIntentClientConfig } from '@unifygtm/intent-client';
const writeKey = 'YOUR_PUBLIC_API_KEY';
const unify = new UnifyIntentClient(writeKey);
unify.mount();
// Use the client for some time, then later...
unify.unmount();
```
# Unify Intent Client
Source: https://docs.unifygtm.com/developers/intent-client/overview
Learn how to start collecting website intent data in Unify.
Buyer intent data is at the core of what makes Unify tick. The easiest way to
start collecting this data is by installing the Unify Intent client on your
marketing website or web app.
## How it works
The Unify Intent client is a JavaScript library that allows you to collect
events from your website and send them to Unify. It supports page, identify, and
custom events.
e.g. a user visits the pricing page of your marketing website
e.g. a user clicks a button to open a pricing calculator modal
e.g. a user logs into your web application with their email address
When you install the Unify Intent client on your website, it can automatically
collect these events and send them to Unify. You can also customize its behavior
by sending events manually.
The Unify Intent client is fully open source and available on [GitHub](https://github.com/unifygtm/intent-js-client).
## Installation
There are multiple ways to install the Unify Intent client depending on your
setup. In most cases, the website tag is the best option to get started.
Paste a pre-configured JavaScript snippet in your website's HTML. This
method is the easiest way to get started and is suitable for most websites.
Install the client in your React web application for a more native
integration.
Install the client in your non-React frontend application, such as a Single
Page App (SPA).
You should only use one installation method per website or application. If the
client is installed twice on the same site, it may not work correctly.
## Usage
If you install the client using the website tag method, it will start collecting
page visits automatically. Often, no further setup is required unless you wish
to track visitor interactions manually.
For other installation methods, or to learn how to manually send other types of
events, see the complete [Usage guide](/developers/intent-client/usage-guide).
# Install React package
Source: https://docs.unifygtm.com/developers/intent-client/react
Install the Unify Intent client in a React app.
## Installation
You can install the Unify Intent React library with your preferred package manager:
```shell npm theme={null}
npm install @unifygtm/intent-react
```
```shell yarn theme={null}
yarn add @unifygtm/intent-react
```
```shell pnpm theme={null}
pnpm add @unifygtm/intent-react
```
```shell bun theme={null}
bun add @unifygtm/intent-react
```
## Usage
First, wrap your React app in a `UnifyIntentProvider`:
```tsx index.tsx theme={null}
import {
UnifyIntentClient,
UnifyIntentClientConfig,
UnifyIntentProvider,
} from '@unifygtm/intent-react';
const writeKey = 'YOUR_PUBLIC_WRITE_KEY';
const config: UnifyIntentClientConfig = {
autoPage: true,
autoIdentify: false,
};
const intentClient = new UnifyIntentClient(writeKey, config);
const root = ReactDOM.createRoot(
document.getElementById('root') as HTMLElement,
);
root.render(
);
```
The `UnifyIntentProvider` automatically takes care of mounting and unmounting the client
for you whenever the component mounts and unmounts. Any components rendered in your app
can access and use the intent client using the `useUnifyIntent` hook:
```tsx Example.tsx theme={null}
import { useUnifyIntent } from '@unifygtm/intent-react';
const Example = () => {
// Get the Unify Intent Client
const unify = useUnifyIntent();
// However you access the current user...
const currentUser = useCurrentUser();
useEffect(() => {
if (currentUser?.emailAddress) {
// Log an identify event for the current user
unify.identify(currentUser.emailAddress, {
firstName: currentUser.firstName,
lastName: currentUser.lastName,
company: {
name: currentUser.companyName,
domain: currentUser.companyDomain
},
});
}
}, [currentUser, unify]);
...
};
export default Example;
```
For details on how to use the client to send events, see the full [Usage guide](/developers/intent-client/usage-guide).
# Usage guide
Source: https://docs.unifygtm.com/developers/intent-client/usage-guide
Learn how to send events using the Unify Intent Client.
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 automatically de-anonymize the IP address of a user to associate them with a specific company, 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}
```
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}
Free sample
```
##### `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}
```
##### `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}
```
#### 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 a single step of a mult-step 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
If installed via the [Unify Website tag](./website-tag) 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.
If installed via the [Unify Website tag](./website-tag) 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.
Options to customize the auto-tracking of user actions such as click events.
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.
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.
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.
Length in minutes that user sessions will persist when no activities are tracked. Activities include `page`, `identify,` and `track` activities.
## Cookies
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.
# Website tag
Source: https://docs.unifygtm.com/developers/intent-client/website-tag
Set up the Unify Intent client on a marketing website.
## Installation
You can automatically load and install the client by placing a `