
## What's Highlight?

Highlight is a tool that helps teams reproduce end-to-end user sessions to better understand their application.

With Highlight, **engineering teams** can replay errors with high precision, which includes a complete session replay, outgoing network requests, dense stack traces and insight into the app's state management system (redux, apollo's cache, etc.). At the same time, **product teams** can analyze user activity, collaborate with engineering teams and find the reason for user drop offs to gain insight into UX.

```welcomevideo

```



# How to contribute

## Application Architecture

First, you'll want to understand how Highlight is built to make changes. The best way to get a sense of this is to try and make simple dummy changes to different parts of the stack and see how the changes propagate.

-   SDKs `sdk/`

    -   Firstload

    -   Client

    -   highlight-node / other SDKs

-   Public Graph `backend/public-graph/graph/schema.resolvers.go`

-   Private Graph `backend/private-graph/graph/schema.resolvers.go`

-   Workers `backend/worker.go`

    -   Public graph worker `processPublicWorkerMessage`

    -   Async worker `Start`
    

## Best first issues to take on

It's best to start with issues marked as ["good first issue"](https://github.com/highlight/highlight/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22). We mark these issues based on how well-defined and testable they are. If you're interested in a larger project, adding support for new programming languages via a new SDK would always greatly appreciated. If there is a feature you're missing in Highlight, reach out on our [discussions](https://github.com/highlight/highlight/discussions) or on our [discord](https://highlight.io/community) to get a conversation started about the best implementation.

## How do I get started?

You'll want to spin up Highlight locally to get to developing. The best way to do this is by using docker. Check out [the self-hosting instructions](../../2_company/open-source/self-host-hobby.md) for more info.

# Code Style

While we don't fret about whether you prefer tabs or spaces, we want our code to be easy to read and add to. Style preferences are codified and automated as part of CI and automated development workflows (such as `husky` and gomod configurations). If you have ideas on how to improve our style linting, open a PR and let us know!

# License

Highlight is [Apache 2](https://github.com/highlight/highlight/blob/main/LICENSE) licensed.

By contributing to Highlight, you agree that your contributions will be licensed under its Apache 2 license.



## Our Enterprise Self-hosted Deployment

Interested in deploying Highlight to your own VPC at a larger scale than the [hobby deployment](../open-source/self-host-enterprise.md)? Please contact us in our [discord community](https://community.highlight.io) to get in touch.

## Pricing

Pricing for our self-hosted deployment starts at $3k / month. Contact us at sales@highlight.io, or message us [on discord](https://community.highlight.io) to get in touch.



# Running Highlight

## Docker Compose

```shell
cd docker
docker compose up -d --build
```

After a brief frontend load time, the app should be accessible at https://localhost:3000

For deploying on Linux with Docker, we recommend having at least 16 CPU cores, 32GB RAM, 256GB disk.
Reach out to our [community](https://community.highlight.io/) with any questions!

# Limitations

We don't recommend hosting Highlight yourself if you have more than 10k monthly sessions or 50k monthly errors. The infrastructure configuration in the docker compose is not meant to scale beyond a small number of sessions, and isn't resilient to an outage or version upgrades. 

That being said, if the benefits of self hosting Highlight are signficant enough, you may want to consider an enterprise deployment (see [our Enterprise Self Hosted Docs](./self-host-enterprise.md)).

If you have any questions, don't hesitate to [reach out](https://community.highlight.io)!



# Our Mission
Our mission is to give you the tools you need to **uncover, resolve, and prevent** issues in your web app.

# Our Values
## We build in public.
We strive to build in public in every way we can. This means sharing our roadmap, product specs, and company strategy. We see this as giving you all the more reason to consider joining us in [building highlight](https://careers.highlight.run).

## We build with cohesion.
People may think that we're building multiple products (session replay, error monitoring, etc..). But we see it as one. Before we build anything new, we prioritize making it operate seemlessly with everything else.

## We build for today's developer.
What are the needs of today's developers? E.g. if you're building software, why should you care about grafana or loki or the elk stack? Highlight is built for developers that want to **develop**. Leave the monitoring stuff to us 👍.


Let's get you up and running with Highlight. You should be done and able to see a recorded session **within 2 minutes!**
## For your client / frontend:

A session in Highlight starts in the client. 

Highlight supports any framework that uses the [dom](https://www.w3schools.com/js/js_htmldom.asp) under the hood, and we support all modern browsers to date. Beyond that, to make integration even easier, we have official support for the following frameworks:

-   [React.js](./client-sdk/reactjs.md)

-   [Next.js](./client-sdk/nextjs.md)

-   [Vue.js](./client-sdk/vuejs.md)

-   [Gatsby.js](./client-sdk/gatsbyjs.md)

-   [HTML](./client-sdk/html.md)

-   [SvelteKit](./client-sdk/sveltekit.md)

-   [Angular](./client-sdk/angular.md)

-   If you don't see your framework above, see our docs for [other frameworks](./client-sdk/other.md).

For in-depth instructions, follow the [Client SDK](./client-sdk/1_client-sdk-overview.md) guide.

## For your backend / server:

Highlight also supports reporting errors from your backend and mapping these to corresponding sessions. This gives you and your team a full picture of your application. Support frameworks / tech below:


-   [Firebase](./backend-sdk/firebase.md)

-   [Express](./backend-sdk/express.md)

-   [Go](./backend-sdk/go.md)

-   [Next.js](./backend-sdk/nextjs.md)

-   [Node.js](./backend-sdk/nodejs.md)

-   For requesting other backend frameworks, shoot us a message at [support@highlight.io](mailto:support@highlight.io) or share in our [community](https://discord.gg/yxaXEAqgwN)

For in-depth instructions, follow the [Backend SDK](./backend-sdk/backend-sdk-overview.md) guide.



## What's this?

In order to make the most out of Highlight's full-stack integration, we suggest instrumenting your frontend so that you can attribute frontend requests with backend errors. Below, we detail the requirements to get this working as well how to troubleshoot.

## How can I start using this?

Required Highlight `highlight.run` version: `>=2.8.1`

### Turn on `tracingOrigins`

Set the `tracingOrigins` option to an array of patterns matching the location of your backend. You may also simply specify `true`, which will default `tracingOrigins` to all subdomains/domains of the url for your frontend app.

```javascript
H.init("<YOUR_PROJECT_ID>", {
	tracingOrigins: ['localhost', 'example.myapp.com/backend'],
    ...
});
```

### Turn on `networkRecording`

```javascript
H.init("<YOUR_PROJECT_ID>", {
	networkRecording: {
		enabled: true,
		recordHeadersAndBody: true,
	},
	...
});
```

## Backend Changes

Backend changes are dependent on the underlying language/framework used on the server-side codebase. All you need to add is a middleware and code to capture errors.

Below are solutions for what we support today. If you'd like us to support a new framework, feel free to shoot us a message at [support@highlight.io](mailto:support@highlight.io) or drop us a note in our [discord](https://discord.gg/yxaXEAqgwN).

- [Go Backend Integration](./backend-sdk/go.md)

- [Next.js Backend Integration](./backend-sdk/nodejs.md)

- [Node.js Backend Integration](./backend-sdk/nodejs.md)

- [Express Backend Integration](./backend-sdk/express.md)

## Troubleshooting

1.  Ensure `tracingOrigins` and `networkRecording` are properly set.

2.  Ensure your backend has `CORS` configured for your frontend hostname, explicitely allowing header `x-highlight-request`.

3.  For debugging the backend sdk of your choice, in order to debug, we suggest enabling verbose logging. For example, in go, add `highlight.SetDebugMode(myLogger)`

4. If all else fails, please send us an email at support@highlight.io or join the #support channel on our [discord](https://discord.gg/yxaXEAqgwN).



Highlight ships `@highlight-run/node` with a plugin `ApolloServerHighlightPlugin` specifically for the apollo server.
The plugin will trace graphql resolver errors and report them to Highlight.

## Usage

The usage of the Apollo plugin requires the [Node.js integration](../../../sdk/nodejs.md) to be configured.
Ensure that `@highlight-run/node` updated to version 2.2.0 or greater. Then, add `ApolloServerHighlightPlugin` to
your `ApolloServer` plugins definition.

```typescript
import {ApolloServerHighlightPlugin} from '@highlight-run/node';

// ...

const server = new ApolloServer({
    typeDefs,
    resolvers,
    plugins: [ApolloServerHighlightPlugin({projectID: 'YOUR_PROJECT_ID'})]
});
```

### Verify

To validate your Highlight backend setup, you can have a graphql resolver throw an error and check that the
error is visible on [app.highlight.io](http://app.highlight.io/errors).



## What's this?

Highlight's Full-stack integration allows you to get visibility into errors and issues across your whole stack, not just your frontend. These errors are paired with outgoing requests on your frontend so that you can understand:

- Exactly what happened when a user reports a bug

- Where specific errors are initiated and what caused them

- What backend issues could have caused corresponding frontend bugs.

## What does it look like?

Below is an example of a backend error (thrown in `go` ) ,mapped to an actual network request on a user's frontend.

![](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/BCFnjSPEUco_QFvl8bs4S_image.png)

## Quick Start

### Enable proper flags in your client-side snippet:

As a first step, you must enable the correct options in your client-side code snippet detailed in our [full stack mapping reference](../2_frontend-backend-mapping.md). 

### Make the appropriate backend changes:

Backend changes are dependent on the underlying language/framework used on the server-side codebase. All you need to add is a middleware and code to capture errors.

Below are solutions for what we support today. If you'd like us to support a new framework, feel free to shoot us a message at [support@highlight.io](mailto:support@highlight.io) or shoot us a note in our [discord](https://discord.gg/yxaXEAqgwN).

- [Go Backend Integration](./go.md)

- [Next.js Backend Integration](./nextjs.md)

- [Node.js Backend Integration](./nodejs.md)

- [Express Backend Integration](./express.md)



Highlight ships `@highlight-run/node` which can be installed alongside highlight.run for capturing backend errors in applications with Express backends.

## Usage

The usage of this Backend SDK requires one of our [Client SDK](../client-sdk/1_client-sdk-overview.md)s to be installed, so please follow the instructions there if you have not done so.

### The `@highlight-run/node` Package

First, import the package

```typescript
yarn add @highlight-run/node
```

### Adding Highlight to Express

Pass configurations into the errorHandler and Highlight is ready to go!


```hint
Where you place the `app.use(highlightErrorHandler)` definition is important. It must be set
after route handler definitions (`app.get(...)`, etc) and before other error middleware. 
```


```typescript
import * as Highlight from '@highlight-run/node'
// or like this with commonjs
// const Highlight = require('@highlight-run/node')

const app = express()

// define any configurations needed
// <https://docs.highlight.run/api/hinit#w0-highlightoptions>
const highlightOptions = {}
// initialize the handler
const highlightErrorHandler = Highlight.Handlers.errorHandler(highlightOptions)

app.get('/', (req, res) => {
    if (Math.random() < 0.1) {
        throw new Error(`random error ${Math.random()}`)
    }
    res.send(`Hello World! ${Math.random()}`)
})

// This should be before any other error middleware and after all controllers (route definitions)
app.use(highlightErrorHandler)
app.listen(port, () => {
    console.log(`Example app listening on port ${port}`)
})
```

### Verify

To validate your Highlight backend setup, you'll need to setup up a testing route handler that throws an error. See the block above for an example. Add some code to your frontend to make an HTTP request
to `/error`. You should be able to view your
frontend session making the request and find the error
traceback in the errors page.

To view and resolve the recorded error, log into [app.highlight.io](http://app.highlight.io/) and open your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved.



Highlight's `@highlight-run/node` package includes wrappers for Firebase Cloud Functions, which will automatically report backend errors to Highlight and link them to the frontend sessions that caused them.

## Getting Started

This backend SDK requires one of our [Client SDK](../client-sdk/1_client-sdk-overview.md)s to be installed, so please follow the instructions there if you have not done so.

For server-side linking to Highlight sessions, your client-side call to `H.init` should include the `tracingOrigins` setting. See [H.init()](../../../sdk/nodejs.md#Hinit) for more details.

```typescript
H.init('<YOUR_PROJECT_ID>', {
    ...
    tracingOrigins: true,
    ...
});
```

## Adding Highlight to your Backend

Import the `@highlight-run/node` package

```shell
# with npm
npm install @highlight-run/node

# with yarn
yarn add @highlight-run/node
```

### Wrap your Cloud Functions

```javascript
const highlightNode = require('@highlight-run/node')

// Callable function wrapper
exports.exampleCallable = functions.https.onCall(
	highlightNode.Handlers.firebaseCallableFunctionHandler((data, context) => {
		// ... your handler code here
		return { result: 'useful result!' }
	}),
)
```

```javascript
const highlightNode = require('@highlight-run/node')

// Http function wrapper
exports.exampleHttp = functions.https.onRequest(
	highlightNode.Handlers.firebaseHttpFunctionHandler((req, res) => {
		// ... your handler code here
		res.json({ result: 'useful result!' })
	}),
)
```

### Verify

To view and resolve the recorded error, log into [app.highlight.io/errors](https://app.highlight.io/errors) and open your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved. You can also view frontend sessions where the error was thrown, and see the individual request which caused the error.



Highlight supports several server frameworks written in Go.

`go-chi/chi`
`gin-gonic/gin`

# Usage

First, install and import the go package in your entrypoint.

```shell
go get -u github.com/highlight/highlight/sdk/highlight-go
```

Add the following lines to your application's main (`func main`) function:

```go
import (
	"github.com/highlight/highlight/sdk/highlight-go"
)

func main() {
	//...application logic...
	highlight.Start()
	defer highlight.Stop()
	highlight.SetProjectID("YOUR_PROJECT_ID")
	//...application logic...
}

```

This configures highlight to transmit any relevant events or errors as they may happen. You can also customize highlight by using the public highlight methods before calling `Start()`. However, we still need to associate your users' sessions with potential backend errors. We provide middleware packages that help set this up:

### Middleware

Add the following middleware to your router:

```go
// with chi
import (
	highlightChi "github.com/highlight/highlight/sdk/highlight-go/middleware/chi"
)

func main() {
	//...
	r := chi.NewRouter()
	r.Use(highlightChi.Middleware)
	//...
}

// with gin
import (
	highlightGin "github.com/highlight/highlight/sdk/highlight-go/middleware/gin"
)

func main() {
	//...
	r := gin.Default()
	r.Use(highlightGin.Middleware())
	//...
}

```

## Instrumenting Handlers

Great! Now we've configured the highlight client and can track sessions from the frontend to the backend. All we need to do now is instrument our backend code to transmit events or errors where relevant.

```go

package main

// with chi
import (
	"errors"
	"github.com/go-chi/cors"
	"github.com/highlight/highlight/sdk/highlight-go"
	"net/http"

	"github.com/go-chi/chi/v5"
	"github.com/go-chi/chi/v5/middleware"
	highlightChi "github.com/highlight/highlight/sdk/highlight-go/middleware/chi"
)

func main() {
	highlight.Start()
	defer highlight.Stop()
	highlight.SetProjectID("YOUR_PROJECT_ID")

	r := chi.NewRouter()
	r.Use(middleware.Logger)
	r.Use(highlightChi.Middleware)
	// setup cors if necessary for your frontend
	r.Use(cors.Handler(cors.Options{
		AllowedOrigins: []string{"http://localhost:3001"},
		AllowedHeaders: []string{"X-Highlight-Request"},
	}))

	r.Get("/ping", PingHandler)
	http.ListenAndServe("0.0.0.0:8080", r)
}

var appHealthy = false

func PingHandler(w http.ResponseWriter, r *http.Request) {
	// we can instrument our handlers directly to record events or error
	if !appHealthy {
		highlight.ConsumeError(r.Context(), errors.New("a health check failure occured!"))
	}
	w.Write([]byte("welcome"))
}

// with gin
import (
	"errors"
	"github.com/gin-contrib/cors"
	"github.com/gin-gonic/gin"
	"github.com/highlight/highlight/sdk/highlight-go"
	highlightGin "github.com/highlight/highlight/sdk/highlight-go/middleware/gin"
)

func main() {
	highlight.Start()
	defer highlight.Stop()
	highlight.SetProjectID("YOUR_PROJECT_ID")

	r := gin.Default()
	r.Use(highlightGin.Middleware())
	// setup cors if necessary for your frontend
	r.Use(cors.New(cors.Config{
		AllowOrigins: []string{"http://localhost:3001"},
		AllowHeaders: []string{"X-Highlight-Request"},
	}))

	r.GET("/ping", PingHandler)
	r.Run("0.0.0.0:8080") // listen and serve on 0.0.0.0:8080 (for windows "localhost:8080")
}

var appHealthy = false

func PingHandler(c *gin.Context) {
	// we can instrument our handlers directly to record events or error
	if !appHealthy {
		highlight.ConsumeError(c, errors.New("a health check failure occured!"))
	}
	c.JSON(200, gin.H{
		"message": "Hello, World!",
	})
}
```



See [Next.js SDK](../fullstack-frameworks/next-js/1_overview.md) for the complete Highlight Next.js SDK setup



Highlight ships `@highlight-run/node` which can be installed alongside highlight.run for capturing backend errors and reporting metrics in applications with Node.js backends. This SDK is compatible with many other backend frameworks built on top of Node.js.

## Getting Started

This backend SDK requires one of our [Client SDK](../client-sdk/1_client-sdk-overview.md)s to be installed, so please follow the instructions there if you have not done so.

For server-side linking to Highlight sessions, your client-side call to `H.init` should include the `tracingOrigins` setting. See [H.init()](../../../sdk/client.md#Hinit) for more details.

```typescript
H.init('<YOUR_PROJECT_ID>', {
    ...
    tracingOrigins: true,
    ...
});
```

## Adding Highlight to your Backend

First, import the package

```shell
# with npm
npm install @highlight-run/node

# with yarn
yarn add @highlight-run/node
```

### Initialize the Highlight backend

Somewhere in your app, typically during startup or when handling errors, initialize the Highlight backend with any necessary options. See [H.init()](../../../sdk/client.md#Hinit) for a full list of options.

```typescript
import { H } from '@highlight-run/node'

const highlightOptions = {}
if (!H.isInitialized()) {
	H.init(highlightOptions)
}
```

### Handle errors

When your app throws a backend error, you can log that error to Highlight by calling [H.consumeError()](../../../sdk/nodejs.md#Hconsume-error) using the `secureSessionId` and `requestId` parameters from the request's header. Your error handling code will depend on the backend framework you use, but will likely look something like this:

```typescript
import { H } from '@highlight-run/node'

const onError = (request, error) => {
	const parsed = H.parseHeaders(request.headers)
	if (parsed !== undefined) {
		H.consumeError(error, parsed.secureSessionId, parsed.requestId)
	}
}
```

### Verify

To view and resolve the recorded error, log into [app.highlight.io/errors](https://app.highlight.io/errors) and open your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved. You can also view frontend sessions where the error was thrown, and see the individual request which caused the error.



Highlight ships the [highlight_io](https://pypi.org/project/highlight-io/) pypi module for capturing backend errors in applications with Python backends.

## Usage

The usage of this Backend SDK requires one of our [Client SDK](../client-sdk/1_client-sdk-overview.md)s to be installed, so please follow the instructions there if you have not done so.

### The `highlight_io` Python Module

If you'd like to follow an example, check out our repo for one of a [Flask app](https://github.com/highlight/highlight/blob/main/sdk/highlight-py/examples/app.py) and one of a [backend script](https://github.com/highlight/highlight/blob/main/sdk/highlight-py/examples/script.py).

First, import the package

```bash
poetry add highlight-io
# or with pip
pip install highlight-io
```

If you are uswing a Flask app, you'll need the Flask integration.

```bash
poetry add highlight-io[Flask]
# or with pip
pip install highlight-io[Flask]
```

### Adding Highlight to Flask

Import the Flask integration and setup Highlight with Flask!

```python
from flask import Flask

import highlight_io
from highlight_io.integrations.flask import FlaskIntegration

app = Flask(__name__)
H = highlight_io.H(
    "YOUR-PROJECT-ID", integrations=[FlaskIntegration()], record_logs=True
)
```

### Verify

To validate your Highlight backend setup, you can setup up a testing route handler that throws an error. For example:

```python
import logging
import random
import time

from flask import Flask

import highlight_io
from highlight_io.integrations.flask import FlaskIntegration

app = Flask(__name__)
H = highlight_io.H(
    "YOUR_PROJECT_ID", integrations=[FlaskIntegration()], record_logs=True
)


@app.route("/error")
def hello():
    for idx in range(1000):
        logging.info(f"hello {idx}")
        time.sleep(0.001)
        if random.randint(0, 100) == 1:
            raise Exception(f"random error! {idx}")
    logging.warning("made it outside the loop!")
    return "<h1>Hello, World!</h1>"


if __name__ == "__main__":
    app.run()
```

creates a `/error` route that will randomly throw an error.

To view and resolve the recorded error, log into [app.highlight.io/errors](http://app.highlight.io/errors). Clicking on the error's title will open a page where you can see detailed information and mark it as resolved. Check out the [error monitoring](../../5_error-monitoring/error-sharing.md) docs for more info!



Highlight's `@highlight-run/node` package includes a tRPC compatible error handler, which will automatically report backend errors to Highlight and link them to the frontend sessions that caused them.

## Getting Started

In order to use the backend sdk, we recommend using one of our Client SDKs (with `H.init()`) so that errors are properly matched from your sessions to your backend errors. In your javascript environment, it would look like something like this:

```typescript
H.init('<YOUR_PROJECT_ID>', {
    ...
    tracingOrigins: true,
	networkRecording: {
		enabled: true,
		recordHeadersAndBody: true,
	},
    ...
});
```


The full guide for initializing Highlight in your client can be found [here](../client-sdk/1_client-sdk-overview.md) and more information about setting up frontend/backend mapping for any stack can be found [here](../2_frontend-backend-mapping.md).

Lastly, see [H.init()](../../../sdk/client.md#Hinit) for a full sdk reference.


## Adding Highlight to your Backend

Import the `@highlight-run/node` package

```shell
# with npm
npm install @highlight-run/node

# with yarn
yarn add @highlight-run/node
```

### Handle errors

When you're exporting an API handler, use `Handlers.trpcOnError` as your `onError` function. Here's an example with tRPC + Next.js:

```typescript
// pages/api/trpc/[trpc].ts

import { createNextApiHandler } from '@trpc/server/adapters/next'
import { Handlers } from '@highlight-run/node'

export default createNextApiHandler({
	// ... your config
	onError: Handlers.trpcOnError,
})
```

If you're already doing your own error handling logic in a custom `onError` function, you can call this handler with the `error` and `req` arguments.

```typescript
// pages/api/trpc/[trpc].ts

import { createNextApiHandler } from '@trpc/server/adapters/next'
import { Handlers } from '@highlight-run/node'

export default createNextApiHandler({
	// ... your config
	onError: ({ error, req }) => {
		// ... your own error handling logic here
		Handlers.trpcOnError({ error, req })
	},
})
```

### Verify

To view and resolve the recorded error, log into [app.highlight.io/errors](https://app.highlight.io/errors) and open your project. Clicking on the error's title will open a page where you can see detailed information and mark it as resolved. You can also view frontend sessions where the error was thrown, and see the individual request which caused the error.



```hint
For a more comprehensive tour of our client sdk, visit our [client reference page](../../../sdk/client.md).
```

## Frameworks

Get started with one of these guides if you're using a listed framework:

-   [React.js](./reactjs.md)

-   [Next.js](./nextjs.md)

-   [Vue.js](./vuejs.md)

-   [Gatsby.js](./gatsbyjs.md)

-   [HTML](./html.md)

-   [SvelteKit](./sveltekit.md)

-   [Angular](./angular.md)

## Installing the SDK

Install `highlight.run` using your package manager.

```shell
# with npm
npm install highlight.run

# with yarn
yarn add highlight.run
```

## Initialize

Initialize Highlight where your application starts.

```typescript
import { H } from 'highlight.run'

H.init(
	'<YOUR_PROJECT_ID>', // Get this from https://app.highlight.run/setup
)
```

### Example

```typescript
import React from 'react'
import { H } from 'highlight.run'

H.init('<YOUR_ORGANZATION_ID>') // Get this from https://app.hgihlight.run/setup

ReactDOM.render(
	<React.StrictMode>
		<App />
	</React.StrictMode>,
	document.getElementById('root'),
)
```

## Verify

Start your app, go to it in the browser, then click around. Highlight will be recording your session and it will show up on <https://app.highlight.io/sessions> a few seconds after recording has started.

## Next Steps

After installing Highlight for your frontend application, there are a few other things you should check out about our Session Replay product, namely:

- [Privacy Controls](../../4_session-replay/privacy.md)

- [Network Request Recording](../../4_session-replay/recording-network-requests-and-responses.md)

- [Backend Setup Guides](../backend-sdk/backend-sdk-overview.md)



```hint
Reference our [client-side sdk docs](../../../sdk/client.md) for advanced functionality and our [fullstack mapping guide](../2_frontend-backend-mapping.md) on pairing backend errors with your replay.
```
## Installing the SDK

Install `highlight.run` using your package manager.

```shell
# with npm
npm install highlight.run

# with yarn
yarn add highlight.run
```

## Initialize

Initialize Highlight where your application starts, likely in the Angular `main.ts` file.

```typescript
import { H } from 'highlight.run';

H.init(
    "<YOUR_PROJECT_ID>", // Get your project ID from https://app.highlight.io/setup
    networkRecording: {
        enabled: true,
        recordHeadersAndBody: true,
    },
    tracingOrigins: true // Optional configuration of Highlight features
);
```

Check out [H.init()](../../../sdk/client.md#Hinit) docs for more details about the options to configure.

If you prefer a full-fledged example, you can also reference our sample [Angular Repo with Highlight Configured](https://github.com/highlight/example-angular).

## Verify

Start your app, go to it in the browser, then click around. Highlight will be recording your session and it will show up on <https://app.highlight.io/sessions> a few seconds after recording has started.

## Configuration

Integration with [Angular ErrorHandler](https://angular.io/api/core/ErrorHandler) coming soon!

## Next Steps

After installing Highlight for your frontend application, there are a few other things you should check out about our Session Replay product, namely:

- [Privacy Controls](../../4_session-replay/privacy.md)

- [Network Request Recording](../../4_session-replay/recording-network-requests-and-responses.md)

- [Backend Setup Guides](../backend-sdk/backend-sdk-overview.md)



```hint
Reference our [client-side sdk docs](../../../sdk/client.md) for advanced functionality and our [fullstack mapping guide](../2_frontend-backend-mapping.md) on pairing backend errors with your replay.
```
## Installing the SDK

Install `@highlight-run/gatsby-plugin-highlight` using your package manager.

```shell
# with npm
npm install @highlight-run/gatsby-plugin-highlight

# with yarn
yarn add @highlight-run/gatsby-plugin-highlight
```

## Register Highlight as a Gatsby Plugin

You will need to register the Highlight Gatsby Plugin.

```javascript
module.exports = {
	plugins: [
		{
			resolve: '@highlight-run/gatsby-plugin-highlight',
			options: {
				orgID: '<YOUR_PROJECT_ID>', // Get your project ID from https://app.highlight.io/setup
			},
		},
	],
}
```

## Verify

Start your app, go to it in the browser, then click around. Highlight will be recording your session and it will show up on <https://app.highlight.io/sessions> a few seconds after recording has started.

## Next Steps

After installing Highlight for your frontend application, there are a few other things you should check out about our Session Replay product, namely:

- [Privacy Controls](../../4_session-replay/privacy.md)

- [Network Request Recording](../../4_session-replay/recording-network-requests-and-responses.md)

- [Backend Setup Guides](../backend-sdk/backend-sdk-overview.md)


```hint
Reference our [client-side sdk docs](../../../sdk/client.md) for advanced functionality and our [fullstack mapping guide](../2_frontend-backend-mapping.md) on pairing backend errors with your replay.
```
## Adding the Snippet

Add the snippet to your `index.html`.

```html
<html>
	<head>
		<script src="https://cdn.jsdelivr.net/npm/highlight.run@latest"></script>
		<script>
			window.H.init('<YOUR_PROJECT_ID>') // Get your project ID from https://app.highlight.io/setup
		</script>
	</head>
	<body>
		
	</body>
</html>
```

## Verify

Start your app, go to it in the browser, then click around. Highlight will be recording your session and it will show up on <https://app.highlight.io/sessions> a few seconds after recording has started.

## Next Steps

After installing Highlight for your frontend application, there are a few other things you should check out about our Session Replay product, namely:

- [Privacy Controls](../../4_session-replay/privacy.md)

- [Network Request Recording](../../4_session-replay/recording-network-requests-and-responses.md)

- [Backend Setup Guides](../backend-sdk/backend-sdk-overview.md)


```hint
Reference our [client-side sdk docs](../../../sdk/client.md) for advanced functionality and our [fullstack mapping guide](../2_frontend-backend-mapping.md) on pairing backend errors with your replay.
```
## Installing the SDK

Install `highlight.run` and `@highlight-run/react` using your package manager.

```shell
# with npm
npm install highlight.run @highlight-run/react

# with yarn
yarn add highlight.run @highlight-run/react
```

## Initialize

Initialize Highlight where your application starts.

```typescript
import { H } from 'highlight.run'

H.init(
	'<YOUR_PROJECT_ID>', // Get your project ID from https://app.highlight.io/setup
)
```

### Example

```typescript
import type { AppProps } from 'next/app'
import { H } from 'highlight.run'
import { ErrorBoundary } from '@highlight-run/react'

H.init('<YOUR_PROJECT_ID>') // Get your project ID from https://app.highlight.io/setup

function MyApp({ Component, pageProps }: AppProps) {
	return (
		<ErrorBoundary>
			<Component {...pageProps} />
		</ErrorBoundary>
	)
}
export default MyApp
```

## Verify

Start your app, go to it in the browser, then click around. Highlight will be recording your session and it will show up on <https://app.highlight.io/sessions> a few seconds after recording has started.

## Next Steps

After installing Highlight for your frontend application, there are a few other things you should check out about our Session Replay product, namely:

- [Privacy Controls](../../4_session-replay/privacy.md)

- [Network Request Recording](../../4_session-replay/recording-network-requests-and-responses.md)

- [Backend Setup Guides](../backend-sdk/backend-sdk-overview.md)


```hint
Reference our [client-side sdk docs](../../../sdk/client.md) for advanced functionality and our [fullstack mapping guide](../2_frontend-backend-mapping.md) on pairing backend errors with your replay.
```
## Adding the Snippet

Add the snippet to your `index.html`.

```html
<html>
	<head>
		<script src="https://unpkg.com/highlight.run"></script>
		<script>
			window.H.init('<YOUR_PROJECT_ID>') // Get your project ID from https://app.highlight.io/setup
		</script>
	</head>
	<body>
		
	</body>
</html>
```

## Verify

Start your app, go to it in the browser, then click around. Highlight will be recording your session and it will show up on <https://app.highlight.io/sessions> a few seconds after recording has started.

## Next Steps

After installing Highlight for your frontend application, there are a few other things you should check out about our Session Replay product, namely:

- [Privacy Controls](../../4_session-replay/privacy.md)

- [Network Request Recording](../../4_session-replay/recording-network-requests-and-responses.md)

- [Backend Setup Guides](../backend-sdk/backend-sdk-overview.md)


```hint
Reference our [client-side sdk docs](../../../sdk/client.md) for advanced functionality and our [fullstack mapping guide](../2_frontend-backend-mapping.md) on pairing backend errors with your replay.
```
## Installing the SDK

Install `highlight.run` and `@highlight-run/react` using your package manager.

```shell
# with npm
npm install highlight.run @highlight-run/react

# with yarn
yarn add highlight.run @highlight-run/react
```

## Initialize

Initialize Highlight where your application starts.

```typescript
import { H } from 'highlight.run'

H.init(
	'<YOUR_PROJECT_ID>', // Get your project ID from https://app.highlight.io/setup
)
```

### Example

```typescript
import React from 'react'
import { H } from 'highlight.run'
import { ErrorBoundary } from '@highlight-run/react'

H.init('<YOUR_PROJECT_ID>') // Get your project ID from https://app.highlight.io/setup

ReactDOM.render(
	<React.StrictMode>
		<ErrorBoundary>
			<App />
		</ErrorBoundary>
	</React.StrictMode>,
	document.getElementById('root'),
)
```

## Verify

Start your app, go to it in the browser, then click around. Highlight will be recording your session and it will show up on <https://app.highlight.io/sessions> a few seconds after recording has started.

## Next Steps

After installing Highlight for your frontend application, there are a few other things you should check out about our Session Replay product, namely:

- [Privacy Controls](../../4_session-replay/privacy.md)

- [Network Request Recording](../../4_session-replay/recording-network-requests-and-responses.md)

- [Backend Setup Guides](../backend-sdk/backend-sdk-overview.md)


```hint
Reference our [client-side sdk docs](../../../sdk/client.md) for advanced functionality and our [fullstack mapping guide](../2_frontend-backend-mapping.md) on pairing backend errors with your replay.
```

## Initialize and Start Highlight

You will need to initialize and start Highlight in your SvelteKit application. You can do so by making the following change in `index.html`.

```html
... %svelte.head%

<script src="https://cdn.jsdelivr.net/npm/highlight.run@latest"></script>
<script>
	window.H.init('<YOUR_PROJECT_ID>')
</script>

...
```

## Verify

Start your app, go to it in the browser, then click around. Highlight will be recording your session and it will show up on <https://app.highlight.io/sessions> a few seconds after recording has started.

## Next Steps

After installing Highlight for your frontend application, there are a few other things you should check out about our Session Replay product, namely:

- [Privacy Controls](../../4_session-replay/privacy.md)

- [Network Request Recording](../../4_session-replay/recording-network-requests-and-responses.md)

- [Backend Setup Guides](../backend-sdk/backend-sdk-overview.md)


```hint
Reference our [client-side sdk docs](../../../sdk/client.md) for advanced functionality and our [fullstack mapping guide](../2_frontend-backend-mapping.md) on pairing backend errors with your replay.
```
## Installing the SDK


Install `highlight.run` using your package manager.

```shell
# with npm
npm install highlight.run

# with yarn
yarn add highlight.run
```

## Initialize

Initialize Highlight where your application starts.

```typescript
import { H } from 'highlight.run'

H.init(
	'<YOUR_PROJECT_ID>', // Get your project ID from https://app.highlight.io/setup
)
```

### Example

```typescript
import { H } from 'highlight.run'
import { createApp } from 'vue'
import App from './App.vue'

H.init('9me23yd2') // Get your project ID from https://app.highlight.io/setup

createApp(App).mount('#app')
```

## Verify Installation

Start your app, go to it in the browser, then click around. Highlight will be recording your session and it will show up on <https://app.highlight.io/sessions> a few seconds after recording has started.

## Next Steps

After installing Highlight for your frontend application, there are a few other things you should check out about our Session Replay product, namely:

- [Privacy Controls](../../4_session-replay/privacy.md)

- [Network Request Recording](../../4_session-replay/recording-network-requests-and-responses.md)

- [Backend Setup Guides](../backend-sdk/backend-sdk-overview.md)



```hint
Reference our [client-side sdk docs](../../../sdk/client.md) for advanced functionality and our [fullstack mapping guide](../2_frontend-backend-mapping.md) on pairing backend errors with your replay.
```
## Adding the Snippet

Add the snippet to your `index.html`.

```html
<html>
	<head>
		<script src="https://unpkg.com/highlight.run"></script>
		<script>
			window.H.init('<YOUR_PROJECT_ID>') // Get your project ID from https://app.highlight.io/setup
		</script>
	</head>
	<body>
		
	</body>
</html>
```

## Verify

Start your app, go to it in the browser, then click around. Highlight will be recording your session and it will show up on <https://app.highlight.io/sessions> a few seconds after recording has started.


The Highlight Next.js SDK adds additional features to Highlight, including:

-   server-side error monitoring and linking to Highlight sessions: [Highlight()](../../../../sdk/nextjs.md#Highlight)

-   automatic configuration of source map uploads: [withHighlightConfig()](../../../../sdk/nextjs.md#withHighlightConfig)

-   automatic proxying for Highlight requests using Next.js rewrites: [withHighlightConfig()](../../../../sdk/nextjs.md#withHighlightConfig)

## Getting Started

The features in this SDK require the Highlight client SDK to be installed, so please follow the [Next.js](../../client-sdk/nextjs.md) instructions if you have not yet done so.

For server-side linking to Highlight sessions, your call to `H.init` should include the `tracingOrigins` setting. If you're going to use `withHighlightConfig` and proxy your Highlight requests with a rewrite, you should set `backendUrl`. See [H.init()](../../../../sdk/client.md#Hinit) for more details.

```typescript
H.init('<YOUR_PROJECT_ID>', {
    ...
    tracingOrigins: true,
    backendUrl: '/highlight-events',
    ...
});
```


### SDK Setup

Import the `@highlight-run/next` Package

```shell
# with npm
npm install @highlight-run/next

# with yarn
yarn add @highlight-run/next
```

### Wrapping your next.config.js

```hint
In order for Highlight to be aware of your project during build time, you need the `HIGHLIGHT_SOURCEMAP_UPLOAD_API_KEY` variable in your build environment. Refer to our [environment variables doc](../next-js/env-variables.md) to get this set up in your cloud provider of choice.
```

If you want to configure source map uploads during your production builds and enable the Next.js Highlight proxy rewrite, you can wrap your Next.js config with `withHighlightConfig`. See [withHighlightConfig()](../../../../sdk/index.md#withHighlightConfig) for more details.

```javascript
import { withHighlightConfig } from '@highlight-run/next'
export default withHighlightConfig({
	// your next.config.js options here
})
```

### Next.js Custom Metrics

If you want to monitor backend errors, this API wrapper will send your errors to Highlight and link them to the session where the network request was made. Define a `withHighlight` wrapper with any common options in a common function file. For example, you can create a `highlight.config.ts` file in the root of your next.js codebase. See [Highlight()](../../../../sdk/nextjs.md#Highlight) for more details.

```typescript
import { Highlight } from '@highlight-run/next'

export const withHighlight = Highlight()
```

You can then wrap each of your handlers in the Next.js `api/` directory with the `withHighlight` function from the previous step.

```typescript
import { withHighlight } from '../highlight.config'

const handler = async (req, res) => {
	res.status(200).json({ name: 'Jay' })
}

export default withHighlight(handler)
```

### Wrapping your API routes

Refer to the [next.js metrics docs](./metrics-overview.md) in order to report custom metrics from your Next.js application.


## On Vercel
If you are running your Next.js app in [Vercel](https://vercel.app/), you can install [our integration](https://vercel.com/integrations/highlight) to automatically inject the `HIGHLIGHT_SOURCEMAP_UPLOAD_API_KEY` environment variable. Add it to your project and configure it from the link above to inject the necessary environment variables.

## Other Cloud Providers
If you are not using Vercel or would like to configure this manually, you can set an environment variable manually: `HIGHLIGHT_SOURCEMAP_UPLOAD_API_KEY = <your API key>`, where your API key can be found in the source map section of <https://app.highlight.io/settings/errors>.



# Submitting Backend Metrics

### Manual Instrumentation

If you want to record additional metrics from your api handlers, add some manual instrumentation using the `@highlight-run/next` package. Make sure your [Next.js](../../client-sdk/nextjs.md) frontend integration configures the `tracingOrigins` in the `H.init` call, per [H.init()](../../../../sdk/client.md#Hinit /sdk/client#Hinit) .

```typescript
import { withHighlight } from '../highlight.config'
import { H } from '@highlight-run/next'

const handler = async (req, res) => {
	const start = global.performance.now()
	// do something expensive
	for (let i = 0; i < 1000; i++) {
		const _ = i * i
	}
	const delta = global.performance.now() - start
	H.metrics([{ name: 'expensive-duration-ms', value: delta }])
	res.status(200).json({ name: 'Jay' })
}

export default withHighlight(handler)
```



Highlight out of the box shows you the console messages that were logged during a session.

## Configuration

-   Disabling console recording can be configured with `disableConsoleRecording`.

-   You can specify which console methods to record with `consoleMethodsToRecord`.

```hint
Console messages are not recorded on `localhost` because Highlight emits debug messages which could cause an infinite loop in some situations.
```

See [H.init()](../../sdk/client.md#Hinit) for more information.



-   Highlight will recreate an `iframe` with the same src. The `iframe` will not load if the src's origin has a restrictive X-Frame-Options header.

-   Highlight only supports recording same-origin iframes because of browsers' same-origin policy. If it's possible to init Highlight within the
    `iframe `, you can record the events within as a separate session in your same project.

-   If your
    `iframe ` source becomes invalid after some time or will not render content when inserted in a different domain or website, the recording will not show the correct content that the user saw.

![<iframe> rendering in a session replay](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/UP4LVunHyPBCzRukQwoh4_image.png)



To tag sessions with user-specific identifiers (name, email, etc.), you can call the [`H.identify()`](../../sdk/client.md#Hinit)method in your app. This will automatically index your sessions so that they can be filtered by these attributes.

```none
H.identify(
  "eliza@corp.com",
  { id: "ajdf837dj", phone: "867-5309" }
)
```

## User Display Names

By default, Highlight will show the `identifier` as the user's display name on the session viewer and session feed. You can override this by setting the `highlightDisplayName` or `email` fields in the [`H.identify()`](../../sdk/client.md#Hidentify) metadata.

## Customer User Avatars

You can replace the placeholder user avatars Highlight uses with an image that you provide. You can do this by setting the `avatar` field in the [`H.identify()`](../../sdk/client.md#Hidentify) metadata.

The image URL usually comes from your authentication provider (Firebase, Auth0, Active Directory, etc.). You can forward that URL to Highlight.

```hint
## Saving the image

Highlight does not make a copy of the image. Highlight will render the image directly. This means the image will adhere to any authorization policies.
```

```typescript
H.identify('steven@corp.com', { avatar: 'https://<IMAGE_URL>.png' })
```

## API

See the [H.identify()](../../sdk/client.md#Hidentify) API documentation for more information on how to use it.

## What happens before a user is identified?

All key session information is tracked regardless of whether a session is identified. Highlight will generate an identifier for a user which you can see in the session player unless you set your own by calling [H.identify()](../../sdk/client.md#Hidentify).

When a user is identified we will attempt to **assign their information to previous sessions** from the same browser. If this happens you will see an indicator in the UI showing the data was inferred for a session and that the session was never explicitly identified.



When you use Highlight's Live Mode, the Session Viewer shows the latest data from users' sessions. It is enabled by default on sessions currently 'live' - eg. when a user is still on the page and sending session data.

![Playback controls for a live session](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/rkMGsKiU5WGQ-uVhEW9Wo_screenshot-from-2022-03-21-16-29-23.png)

While you can view how a session looks to a user in real time, note that some events haven't been processed and will not be visible. Errors, console logs, and network traffic will only be visible when Live Mode is disabled, up to what's most recently processed. In Live Mode, time-scrubbing is disabled since you're always seeing the latest session view.

You can always turn off Live Mode by clicking the toggle button, which will show the session up to the latest data processed. Clicking on the session to write a comment will also disable Live Mode, since comments are associated with a particular timestamp.



Highlight out of the box shows you all the network requests durations, response codes, and sizes for a session. If you'd like more data such as the headers and bodies, you can enable [Recording Network Requests and Responses](../4_session-replay/recording-network-requests-and-responses.md).



Due to the nature of Highlight's core product, we keep privacy as our top priority. We've built a few ways to redact/mask certain DOM elements while still preserving the structure of your DOM recording. It is important to note that for both of the below solutions, all data is sanitized on the client, so sensitive data never reaches our servers/platform.

## Masking Elements

One way to sanitize your recordings is by adding the `highlight-block` CSS class to elements that should be ignored.

```html
<div class="highlight-block">Super secret sauce</div>
```

The Highlight snippet will in-turn measure the dimensions of the ignored element, and when the recording is being replayed, an empty placeholder will replace the content.

![Elements with the highlight-block class will show up as redacted in your recordings](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/s3OAcyrUrqMsWXwDqT9Zj_aff29bb-kapture2021-03-25at140125.gif)

## Obfuscating Elements

Alternatively, you can obfuscate specific HTML elements by adding the `highlight-mask` CSS class. The effect is the same of setting `enableStrictPrivacy` (the randomized text in the photo above) but applies to the specific HTML element that you mask.

```html
<div class="highlight-mask">
	This is some sensitive data <button>Important Button</button>
</div>
```

## Ignoring Input
```hint
The following CSS class only works for `<input>` elements. If you are interested in blocking the capture of other HTML elements, see the `highlight-block` class 
```

For sensitive input fields that your team would like to ignore user input for, you can add a CSS class `highlight-ignore` that will preserve the styling of the input element, but ignore all user input.

```html
<input class="highlight-ignore" name="social security number" />
```

## Strict Privacy Mode

If you don't want to manually annotate what elements to not record then you can set `enableStrictPrivacy` to `true` when calling [`H.init()`](../4_session-replay/privacy.md). Strict Privacy Mode will obfuscate all text and images. The text obfuscation is not reversible and is done on the client.

Here are some examples:

-   `<h1>Hello World</h1>` will be recorded as `<h1>1f0eqo jw02d</h1>`

-   `<img src="https://my-secrets.com/secret.png" />` will be recorded as `<img src="" />`

```html
<iframe
	height="500px"
	href="https://xenodochial-benz-c14354.netlify.app/"
	width="100%"
	border="none"
	src="https://xenodochial-benz-c14354.netlify.app/"
	style="border:none"
	><a
		href="https://xenodochial-benz-c14354.netlify.app/"
		target=""
		title="xenodochial-benz-c14354.netlify.app"
		>null</a
	></iframe
>
```



Rage clicks are the equivalent of spamming a close elevator button when you just want to get up to your apartment. But, instead of a close elevator button, it's a space on your application. And instead of getting to your apartment, users usually _rage click_ when a button isn't working as fast as it should or at all.

## How do we identify rage clicks?

A Rage Click is defined as a time periodic in which a user clicks the same area a certain number of times. This can help highlight points of frustration your users have with the app.

By default, we consider user activity as rage clicks when there exists a 2 second or longer period in which a user clicks 5 or more times within a radius of 8 pixels.

## Customizing rage click sensitivity

You'll find fine-grained control over your project's rage click settings in [your project settings page](https://app.highlight.io/settings).

-   Elapsed Time (seconds): the maximum time interval during which clicks count toward a rage click.

-   Radius (pixels): how close clicks must be to be determined as part of the same rage click.

-   Minimum Clicks: the minimum number of nearby clicks required to count as a rage click.

![configuring rage click settings](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/0sgR-VlLcRpAl9SsbDfR-_image.png)

## Alerting for rage clicks

Create a rage click alert [within your project's alerts page](https://app.highlight.io/alerts) to be notified on Slack or via email about a user rage clicking in your app!

![creating a rage click alert](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/XxyLN8kFXtefRgFf1BBUI_image.png)



Many times during debugging, it's useful to know what the network request/response headers and bodies are. Highlight allows you to record network headers and bodies.

You can enable recording of network requests and responses by setting `networkRecording.recordHeadersAndBody` (see [NetworkRecordingOptions](../../sdk/client.md#Hinit)) to `true` when initializing Highlight.

Highlight monkey patches `XmlHttpRequest` and `fetch` to record data from your app's requests/responses including status codes, headers, and bodies.

## Privacy

Out of the box, Highlight will not record known headers that contain secrets. Those headers are:
\- `Authorization`
\- `Cookie`
\- `Proxy-Authorization`

If you have other headers that you would like to redact then you can set `networkRecording.networkHeadersToRedact`.

## Recording Headers and Bodies

Highlight can also record the request/response headers and bodies. You'll be able to see the headers and bodies by clicking on any XHR or Fetch requests in the session Developer Tools.

```typescript
H.init('<YOUR_PROJECT_ID>', {
	networkRecording: {
		enabled: true,
		recordHeadersAndBody: true,
	},
})
```

![](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/HMhiHwF_jifyGh-RXMJHk_network-recording.gif)

## Redacting URLs

You may have APIs that you know will always return secrets in the headers, body, or both. In this case, you can choose URLs to redact from. If a URL matches one of the URLs you specify, the header and body will not be recorded.

```typescript
H.init('<YOUR_PROJECT_ID>', {
	networkRecording: true,
	urlBlocklist: [
		'https://salted-passwords.com',
		'https://www.googleapis.com/identitytoolkit',
		'https://securetoken.googleapis.com',
	],
})
```

Out of the box, Highlight will not record these URLs:
\- `https://www.googleapis.com/identitytoolkit`
\- `https://securetoken.googleapis.com`

## Redacting Headers and Bodies

If you are dealing with sensitive data or want to go the allowlist approach then you can configure `networkRecording.headerKeysToRecord` and `networkRecording.bodyKeysToRecord`. Using these 2 configs, you'll be able to explicitly define which header/body keys to record.

This configuration is only available for `highlight.run` versions newer than `4.1.0`.

## API

See [NetworkRecordingOptions](../../sdk/client.md) for more information on how to configure network recording.



By default, only members in your Highlight workspace will be able to view sessions (see [Team Management](../6_product-features/team-management.md)). If you'd like to share one-off sessions and don't want to invite folks to your workspace, then you can share individual sessions.

To share a session, click the share button then toggle "Allow anyone with the link to access this session.".

![](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/VP2fOjqJrYK3G4HYTepwX_sharing-a-session.gif)

To unshare a session, untoggle the "Allow anyone with the link to access this sessions.".

## What is shared?

When you share a session, all data for the session is made public. This includes:

1.  Console messages

2.  Network requests/responses

3.  Events

4.  Comments



The session shortcut allows you to set a keyboard shortcut in your app/website that will open the current session in Highlight. You can enable session shortcut and the keyboard shortcut by setting `sessionShortcut` in [H.init()](../../sdk/client.md#Hinit).

Scenarios of when you're using your app:

1.  Want to call out a bug without having to figure out what the repro steps are

2.  Want to call out a design change for a specific user scenario without having to type out all the context

For example, if you set `Ctrl` + `0` as the session shortcut, pressing `Ctrl` + `0` while in your app will open Highlight in a new tab with the session you were on loaded. Once you're in Highlight, you can:

1.  Share the session (See [Session Sharing](./session-sharing.md))

2.  Create a comment and tag the directly responsible person (See [Comments](../6_product-features/comments.md))



A track event is a named event that you've defined. Adding a track event is useful if you want to be able to be alerted (see [Recording Network Requests and Responses](../6_product-features/alerts.md)) or search for sessions where the user has done an action.

## Example Scenario: A Shopping Cart

You'd like to see what users are doing that cause them to open the shopping cart. In your app, you'll add `H.track()`:

```none
import { H } from 'highlight.run';
import { getSubtotal } from '@utils';

const ShoppingCard = ({ items }) => (
    <Button
        onClick={() => {
            H.track("Shopping Cart Opened", {
                subtotal: getSubtotal(items),
                numberOfItems: items.length
            });
        }}
    >
        Shopping Cart
    </Button>
)
```

## API

See the [Recording Network Requests and Responses](../../sdk/client.md#Htrack) API documentation for more information on how to use it.



When using Highlight, it can be useful to know which app version a session is recorded on. Highlight helps you by letting you tag which app version a session was recorded on.

To tag your sessions with a version, you can set the `version` field in the [`H.init()`](../../sdk/client.md#Hinit).

```typescript
import App from './App'
import { H } from 'highlight.run'

H.init('<YOUR_PROJECT_ID>', {
	version: process.env.REACT_APP_VERSION,
})

ReactDOM.render(<App />, document.getElementById('root'))
```

## Versioning Errors

`version` is used for errors too, see [Versioning Errors]() for more information.



By default, only members in your Highlight workspace will be able to view errors (see [Team Management](../6_product-features/team-management.md)). If you'd like to share one-off errors and don't want to invite folks to your workspace, then you can share individual errors.

To share an error, click the share button and then toggle "Allow anyone with the link to view this error".

Untoggling this button removes public access to the error.

## What is shared?

When you share an error, all details about the error are made public. This includes user metadata and stack traces for each error instance.



Highlight groups errors together based on their error message and stack trace. When an error is thrown, Highlight finds the closest matching error and adds the new error instance to it.

An error is matched if:

- It has the same error message OR

- It has the same top stack frame and 3 of the next 4 stack frames are the same (in any order)

A stack frame is matched if:

- It has the same filename, function name, line number, and column number OR

- It has the same source code and context (if sourcemaps are enabled)

If there is no match with an existing error, a new error group is created instead.

## Grouping Rules

If your errors are in JSON form, you can add JSONPath expressions in your [project settings](https://app.highlight.io/settings) to select parts of your errors that you want to group on. For example, if your errors look like:

```json
{
    "type": "StackOverflowError",
    "user": "alice",
    "message": "Oh no! You got an error on line 41!!"
}

{
    "type": "StackOverflowError",
    "user": "bob",
    "message": "Oh no! You got an error on line 50!!"
}
```

They would not be grouped together since the errors are not an exact match and since they were thrown at different lines in your code. In this case, if you wanted to group all errors of the same type into the same error group, you can add an expression `$.type` in your project settings.



```hint
## Should I continue reading?

If you publicly deploy sourcemaps with your application then you do not need this guide. This guide is for applications that don't ship sourcemaps with their application.
```

When debugging an error in Highlight, it might be useful to get a stack trace from the original file in your codebase (rather than a minified file) to help understand what is going wrong. In order to do this, Highlight needs access to the sourcemaps from your codebase. Sourcemaps can be sent to Highlight in your CI/CD process.

## Sending Sourcemaps to Highlight

The Highlight [sourcemap-uploader](https://www.npmjs.com/package/@highlight-run/sourcemap-uploader) can be used during your CI/CD process. Here's an example of using it:

```shell
#!/bin/sh

# Build the app
yarn build

# Upload sourcemaps to Highlight
# Add --appVersion "..." if you provide a version value in your H.init call.
npx --yes @highlight-run/sourcemap-uploader upload --apiKey ${YOUR_ORG_API_KEY} --path ./build

# Delete sourcemaps to prevent them from being deployed
find build -name '*.js.map' -type f -delete

# Deploy the app
./custom-deploy-script
```

## `Sourcemap-uploader Arguments`

### `apiKey`

The API key for your project. You can find this in the [project settings](https://app.highlight.io/settings/errors#sourcemaps).

## `path`

The path that Highlight will use to send `.map` files. The default value is `./build`.

## `appVersion`

The version of your current deployment. Please provide the same version value as the value you provide for `version` in [H.init()](../../sdk/client.md#Hinit). This ensures that we're always using the same set of sourcemaps for your current bundle. If omitted, sourcemaps are uploaded as `unversioned` (make sure [H.init()](../../sdk/client.md#Hinit) does not have a `version` option provided).

## Generating Sourcemaps

To use the Highlight [sourcemap-uploader](https://www.npmjs.com/package/@highlight-run/sourcemap-uploader) , you need to be generating [sourcemaps](https://developer.chrome.com/blog/sourcemaps/) for your project. Exactly how to do this depends on your target environment and javascript configuration. Bundlers like [babel](https://babeljs.io/docs/en/options#source-map-options), [webpack](https://webpack.js.org/configuration/devtool/), [esbuild](https://esbuild.github.io/api/#sourcemap), or [rollup](https://rollupjs.org/guide/en/#outputoptions-object) all provide different ways to enable sourcemap generation. Refer to documentation for your specific bundler to generate production-ready sourcemaps or reach out if you need more help!

### Electron App Sourcemaps

Although your electron app configuration may vary, many will chose to use webpack to generate sourcemaps. Refer to the [general webpack sourcemap documentation](https://webpack.js.org/configuration/devtool/) as well as [this useful reference](https://docs.sentry.io/platforms/javascript/guides/electron/sourcemaps/generating/) to configure your build.



When using Highlight, it can be useful to know which app version an error is introduced. Highlight helps you by letting you tag which app version an error was thrown in.

To tag your errors with a version, you can set the `version` field in the [`H.init()`](../../sdk/client.md#Hinit).

```typescript
import App from './App'
import { H } from 'highlight.run'

H.init('<YOUR_PROJECT_ID>', {
	version: process.env.REACT_APP_VERSION,
})

ReactDOM.render(<App />, document.getElementById('root'))
```

## Versioning Sessions

`version` is used for sessions too, see [Versioning Sessions](../4_session-replay/versioning-sessions.md) for more information.



Alerts are a way to keep your team in the loop as to what is happening on your app. Below is a description of the common components of Alerts, and more specific parameters are included in subsequent sections. To get started, visit <https://app.highlight.io/alerts>. The basic parameters for an alert look like the following image:

![](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/NqoXlpImTuC1Hc_41ekn5_5d8b382-alerts-basic.png)

## Connecting a Slack Channel

If you haven't already integrated Highlight with Slack, clicking the "Channels To Notify" dropdown will prompt you to select a channel. Once this is done, you can add any number of channels to be pinged when an alert is thrown.

## Excluding Environments

You may want to exclude certain environments from generating alerts. For example, in your team's dev environment, it's unlikely that you want to be notified of every error. You can do this by adding an excluded environment option.

Learn more about [Environments](../6_product-features/environments.md).



Highlight provides analytics for your app to give you an idea of who and what are users doing. We provide the following:

-   Sessions per Day

-   Errors per Day

-   Referrers

-   Top Users

-   New Users

-   Device Type

-   Browser Type

-   Session Durations

-   Operating System



```hint
We are actively working on improving recording of canvas elements. If you have any questions or suggestions please reach out to us at support@highlight.run
```

Highlight by default does not record the contents of `<canvas>` elements. This is usually why the session replay has blank areas where those areas should be `<canvas>` elements. We provide experimental recording of `<canvas>` contents.

Ensure you have installed [highlight.run >= 4.3.6](https://www.npmjs.com/package/highlight.run/v/4.3.6). Enable canvas recording by configuring [H.init()](../../sdk/client.md#Hinit).

```javascript
H.init('YOUR_PROJECT_ID', {
	enableCanvasRecording: true,
	samplingStrategy: {
		canvas: 15,
		canvasQuality: 'low',
		canvasMaxSnapshotDimension: 480,
	},
})
```

`samplingStrategy.canvas` is the frame per second rate used to record the HTML canvas. We recommend a value < 5 to ensure recording performance is not impacted at high resolutions.

`samplingStrategy.canvasQuality`: 'pixelated' | 'low' | 'medium' | 'high'. This value represents the image compression quality and will affect the size of the canvas images uploaded.

`samplingStrategy.canvasMaxSnapshotDimension`: max recording resolution of the largest dimension of the canvas.

Snapshotting at full resolution and high FPS can produce too much data for our client to upload on devices with low upload bandwidth. We've found that with a safe assumption of upload speed @, 1 MB/s I can support the above snapshotting settings without a problem at 480p 15 fps.

Even though this feature is experimental, it should not have any impact on your application. We've recently changed our uploading client to use browser web-workers to ensure that data serialization cannot block the rendering of your application. If you run into any issues please let us know!

## Caveats

-   [Privacy](../4_session-replay/privacy.md) controls do not apply to canvas recording right now



Comments can be made by you or anyone on your team on sessions and errors.

## Session Comments

Session comments can be made by clicking anywhere on the session replay. Session comments are special because they connect a comment to a position on the screen and the current time. This is extremely powerful because now when you create a comment, you don't have to write more to provide the location/time context.

### Notifications

If you tag your team when creating a comment (learn more [Slack Integration](../7_integrations/slack-integration.md)), Highlight will send them a message via email or Slack. Those messages will contain your comment text and a screenshot of the session at the current time.

![](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/gsYvSrZkPZwf-M-P75jKp_brandbird-1.png)

## Collaboration

You can tag a teammate in a comment by typing `@` and then picking your teammate. When you tag a teammate, they will receive a notification with the message you wrote.

### Replies

Want to have a conversation relevant to what you're looking at? You can also reply to Session or Error comments on the side panel or directly via the popup.

![](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/W0rMORhS-yYiCNY__ZCRA_image.png)

When participating in a comment, you become subscribed to future replies. Subsequent replies will notify you via Slack (learn more [Slack Integration](../7_integrations/slack-integration.md)) or email. Any Slack channel or user tagged is also automatically subscribed.

### Slack Integration

You can tag Slack users or channels in comments after connecting Highlight with Slack (learn more [Slack Integration](../7_integrations/slack-integration.md)). When you tag a Slack user or channel, Highlight will send them a message with your comment and a link to where the comment was made.

### Linear Integration

You can create issues in Linear as you add comments. Within a comment, select "Create a Linear issue" from the issues dropdown. On the next page, you'll be prompted to optionally edit the issue title and description. Once you save the comment, an issue is created and linked to in Linear.



```hint
Cross-origin iframe support is still in development. If you have any questions or suggestions please reach out to us at support@highlight.io
```

[Cross-origin iframes](https://learn.microsoft.com/en-us/skype-sdk/ucwa/cross_domainiframe) are `<iframe>` elements in your app that reference a domain considered to be of a [different origin](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy). When your iframe uses a `src` tag pointing to a different origin, the iframe is not accessible from the parent page. However, the iframe can still emit messages that the parent page can hear.

To support cross-origin iframes, we added functionality into our recording client that allows the iframe to forward its events to the parent session. All you need to do is add the Highlight snippet to both the parent window and the iframe.

Ensure you are using [highlight.run](https://www.npmjs.com/package/highlight.run) 5.2.0 or newer. Then, add the following option to the `H.init` call **inside of your iframe**.

```typescript
import { H } from 'highlight.run'

H.init('<YOUR_PROJECT_ID>', {
    isCrossOriginIframe: true,
})
```

Ensure that you add the `H.init` call to both the parent page and the iframe page, but that you only set `isCrossOriginIframe` **in the H.init call of your iframe**. Otherwise your sessions will not be recorded.



Highlight Digests are a weekly email summary of interesting sessions, errors, and user activity.

## Getting Started

You don't have to do anything to start receiving digests. If your project has 50+ sessions recorded in the past week, a digest will automatically be emailed to all workspace members. Digests are sent every Monday around 9am PST.

## Features

### User activity

This section shows aggregate user activity stats for last week and the change from the prior week. This includes total users (the count of unique users), total sessions, total errors, and average time spent (average active time per session).

![](https://static.highlight.io/assets/docs/user_activity.png)

### Active sessions

This section shows the top 5 sessions ordered by active time.

![](https://static.highlight.io/assets/docs/active_sessions.png)

### Erroneous sessions

This section shows the top 5 sessions ordered by error count.

![](https://static.highlight.io/assets/docs/error_sessions.png)

### New errors

This section shows the top 5 errors originating in the last week, ordered by the count of unique affected users.

![](https://static.highlight.io/assets/docs/new_errors.png)

### Frequent errors

This section shows the top 5 errors ordered by their frequency. Ignored errors are excluded.

![](https://static.highlight.io/assets/docs/frequent_errors.png)



Environments can be assigned to sessions and errors by setting the environment option in [H.init()](../../sdk/client.md#Hinit). With the assignment, you can know search and filter sessions and errors based on the environment they come from.

Environments are also used to determine whether [Alerts](../6_product-features/alerts.md) are created.

## Example

```typescript
H.init('<YOUR_PROJECT_ID>', {
	environment: process.env.ENVIRONMENT,
})
```



# Features

We’re excited to introduce Frontend Observability from Highlight — a growing suite of tools that let you analyze how your web app is performing.

Frontend Observability augments two key features: [Web Vitals](../6_product-features/web-vitals.md) and [Performance Data](../6_product-features/performance-data.md).

With the introduction of Frontend Observability in Highlight, Highlight users can now better monitor the performance of their web app, and react to any performance issues quickly. Web Vitals helps you track how quickly your app renders and measures the friction that your users experience on page load. Request Metrics gives you an idea of how quickly your front-end renders dynamic data throughout the lifecycle of your application, both for an individual session level or across users.

# Configuration

To start recording your application's Web Vitals, there's nothing extra you need to do! We'll be recording metrics for you to view on the [Web Vitals dashboard](https://app.highlight.io/dashboards/web-vitals) automatically!

To record metrics about your Frontend Network Requests, you'll need to configure your backend domains of interest. You can do this by [visiting your Project Setting page](https://app.highlight.io/settings) or by adding an extra configuration setting to your [H.init()](../../sdk/client.md#Hinit) call, like so:

```javascript
// Only network requests to the domains listed will have their metrics recorded
// for display in dashboards or for use in metric monitors.

H.init('YOUR_PROJECT_ID', {
	networkRecording: {
		destinationDomains: ['backend.example.com'],
	},
})
```

With this feature, you'll immediately start tracking metrics about network requests to the listed domains from your Frontend. Visualize them from the Request Metrics dashboard and customize further to view valuable insights. You can then create [Recording Network Requests and Responses](../6_product-features/alerts.md) to ensure your App performance metrics are kept in check, so that you can receive Slack / Email notifications as soon as a metric value goes out of the typical bounds.

### Filter by

Once you click Edit on a Dashboard, you'll be able to filter the metric based on further metadata about the request. For example, you can visualize [request latency](https://en.wikipedia.org/wiki/Latency_(engineering)) for a network request based on the URL or the graphql operation.

![](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/-9sNb6mRfuDN5Shb9VxzZ_screen-shot-2022-09-12-at-70648-pm.png)

### Group by

When you add a `Time Series / Bar` chart to your dashboard, you can turn it into a stacked bar chart by selecting a **Group by** key. This will stack data based on the grouping key into the value categories. This can be particularly useful to find outlier groups of a particular metric.

![](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/6bYPOoUaAYJLz9ORARYLu_screen-shot-2022-09-12-at-70917-pm.png)

### Session / Error Stats

Certain metadata about your app's sessions is available by grouping on the `sessions` and `errors` metrics.

![Use the group or filter tag operators](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/9F7NPqTiq64aEyukuP7Ue_image.png)

Using the group operator can allow viewing the number of sessions your app has by the browser version, for example.

![](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/suzMx0NQOs_FIGFJnLWGG_image.png)



if you're a keyboard warrior, then the keyboard shortcuts will help you move fast. While in Highlight, press `?` to bring up the keyboard shortcuts guide. In the keyboard shortcuts guide, you'll find all the keyboard shortcuts for the current page you're on.

## Shortcuts

| Shortcut                               | Key(s)                    |
| -------------------------------------- | ------------------------- |
| Open Keyboard Shortcuts Guide          | `?`                       |
| Play or pause the video                | `Space`                   |
| Set the video time 5 seconds backwards | `Left Arrow Key`          |
| Set the video time 5 seconds forwards  | `Right Arrow Key`         |
| Play the next session                  | `Shift` + `N`             |
| Play the previous session              | `Shift` + `P`             |
| Decrease the playback speed by 0.5x    | `Shift` + `,`             |
| Increase the playback speed by 0.5x    | `Shift` + `.`             |
| Toggle fullscreen                      | `f`                       |
| Enable commenting                      | `c`                       |
| Inspect element                        | `d`                       |
| Toggle left sidebar                    | `⌘` + `b` or `Ctrl` + `b` |
| Toggle right sidebar                   | `⌘` + `i` or `Ctrl` + `i` |



![](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/12zR81xHlGMVyrZkxAT9B_2022-01-2811-461.png)

Highlight records performance data during sessions so you can see how your application is performing on your user's devices. Performance plays a big part of providing a great user experience, we're here to help highlight what you can do to make the experience better.

You can see how your application's performance data in the session's developer tools.

## Types of Data Recorded

-   Memory Usage (How much available RAM is your application using)

    -   This is currently only available on Chromium browsers

-   Frames per second (Is your application smooth and not janky?)

-   Long event handlers (Coming soon)



Segments are a set of search filters that applies to sessions or errors. Segments are useful if you want to quickly view sessions or errors that relate to a certain population of your users.



Highlight records [Tracking Events](../4_session-replay/tracking-events.md) and other metadata about sessions to make them easy to search and filter. Start with the `Quick Search` that will find the best matches depending on what you're looking for and customize your query further in the panel above the sessions feed.

![Quick Search Input.](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/l6Fxtyklubv4aEFnGY6-b_image.png)

# Searching by User Clicks

When using Highlight, you might be interested in querying for sessions where a user clicked a certain HTML element. Highlight records users' clicks on the page as two queryable properties: `clickSelector` and `clickInnerText`.

1.  `clickSelector` is the HTML Element's target's selector, concatinating the element's `tag`, `id ` and `class` values.

2.  `clickTextContent `is the HTML Element's target's `textContent` property. Only the first 2000 characters are sent.
    1.  This property was added in `highlight.run@^4.2.3`.

You can also visualize what Highlight is tracking by looking at your site's console logs when you click an element of interest. For example, clicking a particular `p` element in [https://app.highlight.io/](https://app.highlight.io/1/sessions?query=and) prints the following in the console logs.

![A sample console message on click.](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/yP5u4tqGinXhIyonAuXV1_image.png)

You can then use the session filters to search for text in the two fields.

![](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/2ckH93jnzBYqpCeeTWOXT_image.png)



Building the best product experience is a team sport. We strongly beleive that you'll get the most value out of Highlight if you have your entire team on Highlight. This includes engineering, product, testing, design, etc. At the end of the day, we're solving problems for our users. Solutions are a result of cross-function input.

We've made it super easy to onboard new members to Highlight. All you need to do is go onto <https://app.highlight.io/team> then:

1.  Type in your teammate's email

2.  Copy the invite link and share it

## Domain Auto Join

If you have a large team, adding individual members can be pretty tedious. We've made it easy for your team to join your workspace if they have an approved email origin. You can set this up by going to your Workspace Settings.

### Example

You work at Pied Piper. Your company email is `@piedpiper.com`. On the workspace, if you enable domain auto join and set the allowed origin as `piedpiper.com`, then anyone with a `piedpiper.com` email will be able to join.

Highlight makes sure to deal with imposters by requiring non-OAuth users to verify their emails.



Feedback from your user can come at anytime and anywhere in your app. We've made it easy for you to collect feedback that retains context of what the user was doing up until giving feedback.

If you'd like to send Highlight your user's feedback that is shown during the session replay, you can implement your own UI using [H.addSessionFeedback()](../../sdk/client.md#Hinit) or use the Highlight-provided UI with [H.toggleSessionFeedbackModal()](../../sdk/client.md#Hinit).

## Example Use Case

You've just shipped a new feature, a button that when clicked, shows a random gif. You want to know what users think about the new feature. After the user clicks the button, you show the user a form to collect the feedback. After the feedback is collected, you can send it to Highlight.

```typescript
H.addSessionFeedback({
	verbatim: 'WOW! I really liked the gif I was shown',
})

H.addSessionFeedback({
	verbatim: 'the gif was meh',
	userEmail: 'alice@corp.com',
})

H.addSessionFeedback({
	verbatim: 'i need more gifs!!!!',
	userEmail: 'bob@corp.com',
	userName: 'Bob Hyle',
})
```



[Web Vitals](https://web.dev/vitals/) are a set of useful metrics with the goal of measuring the user experience of a web page.

Traditional tools like [Lighthouse](https://developers.google.com/web/tools/lighthouse) can tell you what your core web vitals are but the data collected is from a simulated environment, not from your actual users. Scoring well on Lighthouse does not mean your actual users are having a good experience.

By default, Highlight will record Web Vitals for all of your sessions. The metrics that we record are:

1.  [Largest Contentful Paint](https://web.dev/lcp/)

2.  [Cumulative Layout Shift](https://web.dev/cls/)

3.  [First Contentful Paint](https://web.dev/fcp/)

4.  [First Input Delay](https://web.dev/fid/)

5.  [Time to First Byte](https://web.dev/ttfb/)

Performance is a continuous challenge. For your app, you may see months of metrics improving but then suddenly some decrease dramatically. This is normal! With Highlight, you'll be able to see when that performance regression happened (down to the app version number).

## Dashboards

Seeing how your web vital metrics perform over time is important to make sure you're consistently deliverying a great experience for your users. We've made this easy by providing a dashboard with all your web vitals. [Check out your dashboard](https://app.highlight.io/dashboards/1) to see how your apps are doing!

## Metric Monitors

Metric monitor alerts can be added from the [Recording Network Requests and Responses](../6_product-features/alerts.md) page to warn you when any of your Web Vitals metrics exceed a certain threshold. You can configure both the aggregation function (average, p90, etc.) and threshold value.



Highlight is able to record websites that use WebGL.

```hint
Highlight's WebGL recording is currently in beta. We are actively working on making this production ready. If you have any questions please reach out to us at support\@highlight.run
```

## Getting Started

Recording WebGL is disabled by default. To enable WebGL recording, enable canvas recording by following the instructions for [Canvas](https://goodmorning.com) recording.

## Caveats

-   [Privacy](../4_session-replay/privacy.md) controls do not apply to WebGL right now



We've made it easy to use Amplitude with Highlight. When you initialize Highlight, you can set your Amplitude API Key.

```typescript
H.init('<YOUR_PROJECT_ID>', {
	integrations: {
		amplitude: {
			apiKey: '<AMPLITUDE_API_KEY>',
		},
	},
})
```

## API

### `logEvent()`

Calling [`H.track()`](../../sdk/client.md#Hinit) will forward the data to Amplitude's [`logEvent()`](https://amplitude.github.io/Amplitude-JavaScript/#amplitudeclientlogevent).

```typescript
H.track('signup_button_clicked', {
	firstTime: true,
	impressions: 10,
})

// The Highlight track call is equivalent to this logEvent call
amplitudeClient.logEvent('signup_button_clicked', {
	firstTime: true,
	impressions: 10,
	// This property is added by Highlight. This shows you the session where this event happened.
	highlightSessionURL: 'https://app.highlight.io/sessions/123',
})
```

### `setUserId()` and `identify()`

Calling [`H.identify()`](../../sdk/client.md#Hinit) will forward the data to Amplitude's [`setUserId()`](https://amplitude.github.io/Amplitude-JavaScript/#amplitudeclientlogevent) and [`identify()`](https://amplitude.github.io/Amplitude-JavaScript/Identify/).

```typescript
H.identify('eliza@corp.com', {
	planType: 'premium',
	verified: false,
})

// The Highlight identify call is equivalent to setUserId and identify.
amplitudeClient.setUserId('eliza@corp.com')
amplitudeClient.identify(
	new amplitude.Identify().set('planType', 'premium').set('verified', false),
)
```

If you want to disable this behavior, you can set `enabled: false` for the integration:

```typescript
H.init("<YOUR_PROJECT_ID>", {
	integrations: {
		amplitude: {
			enabled: false
		}
	}
});
```



Highlight can enhance user session recordings with additional metadata from Clearbit!

![](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/SvFaXEMv_B9JEY4C1wmEn_image.png)

The enhanced information will link you to the users' socials using information provided by Clearbit. Check out the [Clearbit demo](https://dashboard.clearbit.com/lookup) to learn more!

To add Clearbit session enhancement to your Highlight workspace, visit the [integrations page](https://app.highlight.io/integrations) and enable Clearbit.



When you enable the ClickUp integration, Highlight will allow creating Tasks from the session replay and errors viewer. Track bugs or enhancements for your app as you triage frontend and backend errors or watch your users' replays.

To get started, go to the [integrations](https://app.highlight.io/integrations) and click the "Connect" button in the ClickUp section.

## Features

1.  [Comments](../6_product-features/comments.md) can create a ClickUp task filled out with the body of the comment and link back to the Session.

2.  [Grouping Errors](../5_error-monitoring/grouping-errors.md) shows a shortcut to create a ClickUp task pre-populated with the error linking to the full context of how the error occurred.



By connecting Highlight with Discord, Highlight can send you and your team real-time messages based on different sessions, errors and more.

To get started, go to <https://app.highlight.io/integrations> and click the toggle to turn on the discord integration. 

![](/images/discord-integration-toggle.png)

Once you do this, you will see an option to add discord channels on any of the alerts found at <https://app.highlight.io/alerts>. It'll look like this:

![](/images/discord-alert-view.png)



If you are running Highlight in Electron, a Desktop based JS framework, you can benefit from the additional functionality that tracks main process window events to stop and start Highlight recording when your app is minimized.

Please ensure you are using Highlight SDK version [highlight.run@4.3.4.](https://www.npmjs.com/package/highlight.run/v/4.3.4) or higher. Call `configureElectronHighlight` with a `BrowserWindow` object to instrument Electron events.

```Text
const mainWindow = new BrowserWindow(...)
configureElectronHighlight(mainWindow)
```

Under the hood, the function will forward the `focus` and `blur` events to your renderer process so that the highlight recording SDK can track them.

```Text
mainWindow.on('focus', () => {
    mainWindow.webContents.send('highlight.run', { visible: true });
});
window.on('blur', () => {
    mainWindow.webContents.send('highlight.run', { visible: false });
 });
```

This will stop all highlight recording when the app is not visible and resume the session when the app regains visibility to help minimize performance and battery impact that Highlight may have on Electron users.



Do you use [Front.com](https://app.frontapp.com/) to communicate with your customers? Add the Highlight plugin and view Highlight sessions right from the conversation.

![See Highlight Sessions from Front](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/aZFnCEkEtEJpP1zA75J9r_front-highlight-v2.png)

Simply visit [](https://app.frontapp.com/settings/tools)<https://front.com/integrations/highlight> and add the Highlight plugin in one click.

Click the [Get Started](https://app.frontapp.com/settings/integrations/native/edit/highlight) button to add Highlight to your Front workspace.



When you enable the Height integration, Highlight will allow creating Tasks from the session replay and errors viewer. Track bugs or enhancements for your app as you triage frontend and backend errors or watch your users' replays.

To get started, go to the [integrations](https://app.highlight.io/integrations) and click the "Connect" button in the Height section.

## Features

1.  [Comments](../6_product-features/comments.md) can create a Height task filled out with the body of the comment and link back to the Session.

2.  [Grouping Errors](../5_error-monitoring/grouping-errors.md) shows a shortcut to create a Height task pre-populated with the error linking to the full context of how the error occurred.



Highlight makes it easy to send events to Intercom. If you have both Highlight and Intercom already configured, then you're all set. We've already set things up for you in the background.

If you want to disable this integration, you can set `enabled: false` for the integration in your client config:

```typescript
H.init("<YOUR_PROJECT_ID>", {
	integrations: {
		intercom: {
			enabled: false
		}
	}
});
```

## Messaging

Whenever a user sends you a message on Intercom, Highlight will add a [custom user attribute](https://www.intercom.com/help/en/articles/179-send-custom-user-attributes-to-intercom) called `highlightSessionUrl` to the user. This is the URL for the latest session created by that user. This is helpful to see what the user was doing that led up to the user sending a message.

## API

### `trackEvent`

Calling [`H.track`](../../sdk/client.md#Hinit) will forward the data to Intercom's [`Intercom('trackEvent')`](https://developers.intercom.com/installing-intercom/docs/intercom-javascript#section-intercomtrackevent).

```typescript
H.track('signup_button_clicked', {
	firstTime: true,
	impressions: 10,
})

// The Highlight track call is equivalent to this Intercom call
Intercom('trackEvent', 'signup_button_clicked', {
	firstTime: true,
	impressions: 10,
})
```



When you enable the Linear integration, Highlight will allow creating Issues from the session replay and errors viewer. Track bugs or enhancements for your app as you triage frontend and backend errors or watch your users' replays.

To get started, go to the [integrations](https://app.highlight.io/integrations) and click the "Connect" button in the Linear section.

## Features

1.  [Comments](../6_product-features/comments.md) can create a Linear issue filled out with the body of the comment and link back to the Session.

2.  [Grouping Errors](../5_error-monitoring/grouping-errors.md) shows a shortcut to create a Linear task pre-populated with the error linking to the full context of how the error occurred.



We've made it easy to use Mixpanel with Highlight. If you don't already have Mixpanel initialized in your app, you can have Highlight initialize it for you by specifying your Mixpanel Project Token in the config.

```typescript
H.init('<YOUR_PROJECT_ID>', {
	integrations: {
		mixpanel: {
			projectToken: '<MIXPANEL_PROJECT_TOKEN>',
		},
	},
})
```

Whenever you call [`H.track()`](../../sdk/client.md#Htrack) or [`H.identify()`](../../sdk/client.md#Hinit) it will forward that data to Mixpanel's `track` and `identify` calls. If you want to disable this behavior, you can set `enabled: false` for the integration:

```typescript
H.init("<YOUR_PROJECT_ID>", {
	integrations: {
		mixpanel: {
			enabled: false
		}
	}
});
```

## API

### `track()`

Calling [`H.track()`](../../sdk/client.md#Htrack) will forward the data to Mixpanel's `track()`. Highlight will also add a Mixpanel property called `highlightSessionURL` which contains the URL to the Highlight session where the track event happened.

### `identify()`

Calling [`H.identify()`](../../sdk/client.md#Hidentify) will forward the data to Mixpanel's `identify()`.



Highlight ships [`@highlight-run/react`](https://github.com/highlight/react) which can be installed alongside `highlight.run` for additional functionality for React applications.

# Error Boundary

Highlight provides an `ErrorBoundary` to help you provide a better experience for your users when your application crashes. Using an `ErrorBoundary` gives your application an opportunity to recover from a bad state.

Highlight also allows you to show a crash report powered by [User Feedback](../6_product-features/user-feedback.md). A crash report is shown in the session when the crash happens, giving you the context for the user feedback.

```typescript
import { ErrorBoundary } from '@highlight-run/react'

const App = () => (
	<ErrorBoundary showDialog>
		<YourAwesomeApplication />
	</ErrorBoundary>
)
```

## Examples

### Showing the feedback modal when a crash happens

![](https://archbee-image-uploads.s3.amazonaws.com/XPwQFz8tul7ogqGkmtA0y/2VUVTR1ot591xUfJZSc3m_2022-01-1213-17.png)

```typescript
import { ErrorBoundary } from '@highlight-run/react'

const App = () => (
	<ErrorBoundary showDialog>
		<YourAwesomeApplication />
	</ErrorBoundary>
)
```

### Showing a custom feedback modal when a crash happens

You should use this if you would like to replace the feedback modal with your own styles/branding.

```typescript
import { ErrorBoundary } from '@highlight-run/react'

const App = () => (
	<ErrorBoundary
		showDialog
		customDialog={
			<div>
				<h2>Whoops! Looks like a crash happened.</h2>
				<p>Don't worry, our team is tracking this down!</p>

				<form>
					<label>
						Feedback
						<input type="text" />
					</label>

					<button type="submit">Send Feedback</button>
				</form>
			</div>
		}
	>
		<YourAwesomeApplication />
	</ErrorBoundary>
)
```

## ErrorBoundary API

### `fallback`

A fallback component that gets rendered when the error boundary encounters an error.

## `showDialog`

Enables Highlight's crash report. When the `ErrorBoundary` is triggered, a form will be prompted to the user asking them for optional feedback.

### `dialogOptions`

The strings used for the Highlight crash report.

`user`

Allows you to attach additional user information to the feedback report. If you've called [`H.identify()`](../../sdk/client.md#Hidentify) in your application before, you won't have to set this, Highlight will infer the user's identity.

`title`

The title for the report dialog.

`subtitle`

The subtitle for the report dialog.

`subtitle2`

The secondary subtitle for the report dialog.

`labelName`

The label for the name field.

`labelEmail`

The label for the email field.

`labelComments`

The label for the verbatim field.

`labelClose`

The label for the close button.

`labelSubmit`

The label for the submit button.

`successMessage`

The label for the success message shown after the crash report is submitted.

`hideHighlightBranding`

Whether to show the Highlight branding attribution in the report dialog.

Default value is `false`.



> If you have an existing codebase calling
>
> [Segment's](https://segment.com/docs/connections/spec/)
>
> `identify()`
>
> and
>
> `track()`
>
> methods, then you won't have to call Highlight's. Highlight will automatically forward data sent to Segment to your Highlight sessions.

```hint
We are currently working with Segment on an official integration where you can enable, configure, and send data to Highlight. If you'd like to use this, then [upvote this feature request](https://highlight.canny.io/feature-requests/p/official-segment-integration).
```

## Enabling the Segment Integration

```javascript
H.init('<YOUR_PROJECT_ID>', {
	enableSegmentIntegration: true,
})
```

Segment's `identify()` calls will now start forwarding to Highlight.

## Enabling Track data forwarding

To forward `analytics.track()` calls to Highlight, you will need to use the `HighlightSegmentMiddleware`. This is available in the `highlight.run` package starting in version `2.10.0`.

```javascript
import { H, HighlightSegmentMiddleware } from 'highlight.run'

H.init('<YOUR_PROJECT_ID>', {
	enableSegmentIntegration: true,
})
analytics.addSourceMiddleware(HighlightSegmentMiddleware)
```



Highlight's [H.getSessionURL()](../../sdk/client.md#Hget-session-url) gives you the URL to view a session. You can use this with [Sentry's Custom Contexts](https://docs.sentry.io/platforms/javascript/enriching-events/context/) to quickly view what happened in the session right before an error was thrown.

## Vanilla Javascript

This code example should be followed if you're using [Sentry's Javascript SDK](https://docs.sentry.io/platforms/javascript/).

```javascript
import * as Sentry from '@sentry/browser'
import { H } from 'highlight-run'

H.init('<YOUR_PROJECT_ID')

Sentry.init({
	// Your Sentry config.
})

// `sessionUrl` is `undefined` if the session hasn't started yet.
// This is why we pass a function to `getSessionURL()` which is
// called when the session has started.
H.getSessionURL().then((sessionUrl) => {
	Sentry.setContext('highlight', {
		url: sessionUrl,
	})
})
```

## React

This code example should be followed if you're using [Sentry's React SDK](https://docs.sentry.io/platforms/javascript/guides/react/enriching-events/context/).

```javascript
import * as Sentry from '@sentry/react'
import { H } from 'highlight-run'

H.init('<YOUR_PROJECT_ID')

Sentry.init({
	// Your Sentry config.
})

// `sessionUrl` is `undefined` if the session hasn't started yet.
// This is why we pass a function to `getSessionURL()` which is
// called when the session has started.
H.getSessionURL().then((sessionUrl) => {
	Sentry.setContext('highlight', {
		url: sessionUrl,
	})
})
```

## Sentry with Highlight Proxy

When [Proxying Highlight](../9_tips/proxying-highlight.md), you'll find Sentry tracking the session recording traffic flowing to your subdomain. Since this traffic isn't useful to monitor, you may want to ignore these requests in Sentry. You can find the Sentry docs describing how to do that [here](https://docs.sentry.io/platforms/javascript/enriching-events/breadcrumbs/#customize-breadcrumbs).

For example, to filter Sentry recording of Highlight data when your domain is `example.com`

```javascript
Sentry.init({
	// ...
	beforeBreadcrumb(breadcrumb, hint) {
		if (
			breadcrumb.category === 'xhr' &&
			breadcrumb.data?.url.contains('highlight.example.com')
		) {
			return null
		}
		return breadcrumb
	},
})
```



By connecting Highlight with Slack, Highlight can send you and your team real-time messages based on different events that happen on your app and Highlight. You can learn more about this on [Slack Integration](../7_integrations/slack-integration.md).

To get started, go to <https://app.highlight.io/alerts> and click the "Sync with Slack" button.

## Features

1.  [Comments](../6_product-features/comments.md) will send a Slack message to whoever is tagged in a comment

2.  [Alerts](../6_product-features/alerts.md) will send a Slack message to channels or users who want to receive alerts



If you use Vercel to deploy your app, you can install the Vercel Highlight integration here: <https://vercel.com/integrations/highlight/>

After linking your Vercel projects to your Highlight projects, Highlight will automatically set the `HIGHLIGHT_SOURCEMAP_API_KEY` environment variable. If you're using `@higlight-run/sourcemap-uploader` or `withHighlightConfig` to upload your sourcemaps, those tools will check for this API key.



-   Pins highlight.run dynamic client version to the highlight.run package version.

# Upgrading from 4.x or older

-   We've migrated our lazy-loaded bundled to be served from static.highlight.io instead of static.highlight.run. As a result, if you use custom [Content-Security-Policy CSP](../9_tips/content-security-policy.md), change references form static.highlight.run to static.highlight.io.
-   There are no breaking API / package behavior changes with this release.



-   Ensures that a tab reload that resumes a previous old session (older than 4 hours) starts a new session rather than adding a set of data for the previous one.



-   Improves canvas recording efficiency.
-   Improves accuracy of recorded iframes.
-   Improves recording of scrolling with custom CSS.
-   Improves recording of Shadow DOM elements.
-   Smoothens replay mouse animation.



-   Ensures H.stop() stops recording and that visibility events do not restart recording.
-   Simplify CSP requirements by proxying web-vitals script.



-   Fix an issue that prevented recording from starting.



-   Separate the client web worker to make content security policy more strict.



-   Fix an issue with tab visibility switches breaking some recordings.



-   Fix typescript definitions in published `highlight.run` npm package.



-   Remove randomized URL param from Highlight client script to allow browser caching by client version



- Ensure `<video>` and `<audio>` elements are obfuscated correctly in strict privacy mode or with `highlight-mask` / `highlight-block`.
- Fix a condition where `enableStrictPrivacy` with `highlight-mask` on a `<div>` would cause child elements to not be recorded.



Environments can be assigned to sessions and errors by setting the environment option in [H.init()](/docs/sdk/client#Hinit). With the assignment, you can know search and filter sessions and errors based on the environment they come from.

Environments are also used to determine whether [Alerts](/docs/general/product-features/alerts) are created.

## Example

```typescript
H.init('<YOUR_PROJECT_ID>', {
	environment: process.env.ENVIRONMENT,
})
```
