Welcome to Highlight
Getting Started
Overview
Backend / Server
Client / Frontend
Fullstack Frameworks
Tips
Content-Security-Policy
Local Development
Monkey Patches
Performance Impact
Proxying Highlight
Session Search Deep Linking
Troubleshooting
Upgrading Highlight
Session Replay
Console Messages
HTML iframe Recording
Identifying Users
Live Mode
Network DevTools
Privacy
Rage Clicks
Recording Network Requests and Responses
Session Sharing
Session Shortcut
Tracking Events
Versioning Sessions
Error Monitoring
Grouping Errors
Sourcemaps
Versioning Errors
Product Features
Alerts
Analytics
Canvas
Comments
Environments
Frontend Observability
Keyboard Shortcuts
Performance Data
Segments
Session Search
Team Management
User Feedback
Web Vitals
WebGL
Integrations
Amplitude Integration
Clearbit Integration
Electron Integration
Front Plugin
Intercom Integration
Linear Integration
Mixpanel Integration
React.js Integration
Segment Integration
Sentry Integration
Slack Integration
Vercel Integration
highlight.run Changelog
5.0.0
5.0.1
5.1.0
5.1.1
5.1.2
5.1.3
5.1.4
5.1.5
Menu

Client SDK API Reference

<section className="section"> <div className="left"> <h3>Client SDK</h3> <p> The Highlight client records and sends session data to Highlight. The Highlight client SDK contains functions to configure your recording, start and stop recording, and add custom user metadata and properties. </p> </div> <div className="right"> <h6>Just getting started?</h6> <p>Check out our [getting started guide](/getting-started/client-sdk/overview) to get up and running quickly.</p> </div> </section> <section className="section"> <div className="left"> <h3>H.init</h3> <p>This method is called to initialize Highlight in your application.</p> <h6>Method Parameters</h6> <aside className="parameter"> <h5>projectId<code>String</code> <code>optional</code></h5> <p>The projectId tells Highlight where to send data to. You can find your projectId on https://app.highlight.run/setup. If projectId is not set, then Highlight will not send any data. You can use this as a mechanism to control which environments Highlight gets initialized in if the projectId is passed as an environment variable.</p> </aside> <aside className="parameter"> <h5>options <code>HighlightOptions</code> <code>optional</code></h5> <p>Configuration for Highlight client recording.</p> <article className="innerParameterContainer"> <aside className="innerParameterHeading">options properties</aside> <aside className="parameter"> <h5>backendUrl <code>string</code> <code>optional</code></h5> <p>Specifies the URL that Highlight will send data to. You should not use this unless you are running an on-premise instance. You may be interested in [Proxying](/tips/proxying-highlight) to make sure your errors and sessions are not blocked by extensions.</p> </aside> <aside className="parameter"> <h5>manualStart <code>boolean</code> <code>optional</code></h5> <p>Specifies if Highlight should not automatically start recording when the app starts. This should be used with H.start() and H.stop() if you want to control when Highlight records. The default value is false.</p> </aside> <aside className="parameter"> <h5>disableConsoleRecording <code>boolean</code> <code>optional</code></h5> <p>Specifies whether Highlight records console messages. It can be helpful to set this to true while developing locally so you can see where console messages are being made in your source code. The default value is false.</p> </aside> <aside className="parameter"> <h5>consoleMethodsToRecord <code>string[]</code> <code>optional</code></h5> <p>The value here will be ignored if disabledConsoleRecording is true. The default value is ['assert', 'count', 'countReset', 'debug', 'dir', 'dirxml', 'error', 'group', 'groupCollapsed', 'groupEnd', 'info', 'log', 'table', 'time', 'timeEnd', 'timeLog', 'trace', 'warn'].</p> </aside> <aside className="parameter"> <h5>enableSegmentIntegration <code>boolean</code> <code>optional</code></h5> <p>Allows patching of segment requests to enhance data automatically in your application (i.e. identify, track, etc.). The default value is false.</p> </aside> <aside className="parameter"> <h5>environment <code>string</code> <code>optional</code></h5> <p>Specifies the environment your application is running in. See [Environments](/product-features/environments) to see how setting the environment can help you move faster. The default value is production.</p> </aside> <aside className="parameter"> <h5>networkRecording <code>NetworkRecordingOptions</code> <code>optional</code></h5> <p>Specifies how and what network requests and responses Highlight records. See [Recording Network Requests and Responses](/session-replay/recording-network-requests-and-responses) for more information.</p> </aside> <aside className="parameter"> <h5>version <code>string</code> <code>optional</code></h5> <p>Specifies the version of your application. See [Versioning Sessions](/session-replay/versioning-sessions) and [Versioning Errors](/error-monitoring/versioning-errors) to see how setting the version can help you move faster.</p> </aside> <aside className="parameter"> <h5>enableStrictPrivacy <code>boolean</code> <code>optional</code></h5> <p>Specifies whether Highlight should redact all text and image data during recording. This is useful to make sure you are not recording any personally identifiable information without having to manually add annotations to elements you don't want to be recorded. See [Privacy](/session-replay/privacy) to learn more about the privacy options. The default value is false.</p> </aside> <aside className="parameter"> <h5>integrations <code>IntegrationOptions</code> <code>optional</code></h5> <p>Specifies the configurations for the integrations that Highlight supports.</p> </aside> <aside className="parameter"> <h5>enableCanvasRecording <code>boolean</code> <code>optional</code></h5> <p>Specifies whether Highlight will record the contents of &lt;canvas&gt; elements. See [Canvas](/product-features/canvas) for more information. The default value is false.</p> </aside> <aside className="parameter"> <h5>enablePerformanceRecording <code>boolean</code> <code>optional</code></h5> <p>Specifies whether Highlight will record performance metrics (e.g. FPS, device memory). See [Performance Data](/product-features/performance-data) for more information. The default value is true.</p> </aside> <aside className="parameter"> <h5>sessionShortcut <code>boolean | string</code> <code>optional</code></h5> <p>Specifies the keyboard shortcut to open the current session in Highlight. We support the same syntax as [hotkeys](https://github.com/jaywcjlove/hotkeys) for configuring the keyboard shortcut. The default value is false. See [Session Shortcut](/session-replay/session-shortcut) for more information.</p> </aside> <aside className="parameter"> <h5>feedbackWidget <code>FeedbackWidgetOptions</code> <code>optional</code></h5> <p>Specifies the configuration for the Highlight feedback widget. This widget is used to collect user feedback. The feedback is collected in the context of the session.</p> </aside> <aside className="parameter"> <h5>tracingOrigins <code>boolean | (string | RegExp)[]</code> <code>optional</code></h5> <p>Specifies where the backend of the app lives. If specified, Highlight will attach the X-Highlight-Request header to outgoing requests whose destination URLs match a substring or regexp from this list, so that backend errors can be linked back to the session. If true is specified, all requests to the current domain will be matched. Example tracingOrigins: ['localhost', /^\//, 'backend.myapp.com']</p> </aside> </article> </aside> </div> <div className="right"> <code> H.init("&lt;YOUR_PROJECT_ID&gt;", { // Your config options here... }); </code> </div> </section> <section className="section"> <div className="left"> <h3>H.identify</h3> <p>This method is used to add an identity to a user for the session. You can learn more in [Identifying Users](/session-replay/identifying-sessions).</p> <h6>Method Parameters</h6> <aside className="parameter"> <h5>identifier<code>String</code> <code>required</code></h5> <p>The identifier for the user in the session. This is often an email or UUID.</p> </aside> <aside className="parameter"> <h5>metadata<code>[key: string]: string | boolean | number</code> <code>optional</code></h5> <p>Metadata for the user. You can think of these as additional tags for the user. If the highlightDisplayName or email fields are set, they will be used instead of identifier as the user's display name on the session viewer and session feed.</p> </aside> </div> <div className="right"> <code> H.identify("alice@corp.com", { highlightDisplayName: "Alice Customer", accountType: "premium", hasUsedFeature: true }); </code> </div> </section> <section className="section"> <div className="left"> <h3>H.track</h3> <p>This method is used to track events that happen during the session. You can learn more in [Tracking Events](/session-replay/tracking-events).</p> <h6>Method Parameters</h6> <aside className="parameter"> <h5>eventName<code>String</code> <code>required</code></h5> <p>The name of the event.</p> </aside> <aside className="parameter"> <h5>metadata<code>[key: string]: string | boolean | number</code> <code>optional</code></h5> <p>Metadata for the event. You can think of these as additional tags for the event.</p> </aside> </div> <div className="right"> <code> H.track("Opened Shopping Cart", { accountType: "premium", cartSize: 10 }); </code> </div> </section> <section className="section"> <div className="left"> <h3>H.consumeError</h3> <p>This method is used to send a custom error to Highlight.</p> <h6>Method Parameters</h6> <aside className="parameter"> <h5>error<code>Error</code> <code>required</code></h5> <p>A Javascript error that you have created or have access to.</p> </aside> <aside className="parameter"> <h5>message<code>string</code> <code>optional</code></h5> <p>An additional message you'd like to add to the error to give the error more context.</p> </aside> <aside className="parameter"> <h5>payload<code>{ [key: string]: string }</code> <code>optional</code></h5> <p>Additional metadata that you'd like to attach to the error to give the error more context.</p> </aside> </div> <div className="right"> <code> H.consumeError(error, 'Error in Highlight custom boundary!', { component: 'JustThroughAnError.tsx', }); </code> </div> </section> <section className="section"> <div className="left"> <h3>H.metrics</h3> <p>This method is used to submit custom metrics. You can learn more about [Frontend Observability](/product-features/frontend-observability).</p> <h6>Method Parameters</h6> <aside className="parameter"> <h5>metrics<code>Metrics[]</code> <code>required</code></h5> <p>A list of metrics that you'd like to report.</p> <article className="innerParameterContainer"> <aside className="innerParameterHeading">metrics properties</aside> <aside className="parameter"> <h5>name <code>string</code> <code>required</code></h5> <p>The name of the metric you are reporting.</p> </aside> <aside className="parameter"> <h5>value <code>number</code> <code>required</code></h5> <p>The numeric value of the metric.</p> </aside> <aside className="parameter"> <h5>tags <code>{ name: string; value: string }[]</code> <code>optional</code></h5> <p>A set of name,value pairs the represent tags about the metric. Tags can be used to filter and group metrics. See Frontend Observability for more details.</p> </aside> </article> </aside> </div> <div className="right"> <code> H.metrics([{ name: 'clicks', value: 1, tags: [{ browser }] }, { name: 'auth_time', value: authDelay, tags: [{ version: 'v2' }] } </code> </div> </section> <section className="section"> <div className="left"> <h3>H.getSessionDetails</h3> <p>This method is used to get the Highlight session URL. This method provides the same URL as H.getSessionUrl() but this also gives you a URL for the exact time (relative to the session recording) the method is called. For example, an error is thrown in your app and you want to save the Highlight session URL to another app (Mixpanel, Sentry, Amplitude, etc.). If you just want a URL to the session, you can save url. If you want a URL that sets the player to the time of when the error is called, you can save urlWithTimestamp. See [Sentry Integration](/integrations/sentry-integration) for one example use case.</p> <aside className="parameter"> <h5>Returns <code>Promise&lt;{url: string, urlWithTimestamp: string}&gt;</code></h5> <article className="innerParameterContainer"> <aside className="parameter"> <h5>url <code>string</code></h5> <p>A URL for the session in Highlight.</p> </aside> <aside className="parameter"> <h5>urlWithTimestamp <code>string</code></h5> <p>A URL for the session in Highlight, including the timestamp.</p> </aside> </article> </aside> </div> <div className="right"> <code> H.getSessionDetails().then(({url, urlWithTimestamp}) => { console.log(url, urlWithTimestamp); }); </code> </div> </section> <section className="section"> <div className="left"> <h3>H.getSessionURL</h3> <p>This method is used to get the Highlight session URL for the current recording session. This is useful to use if you'd like to send the session URL to another application. See H.getSessionDetails() if you want to get the URL with the current time. See [Sentry Integration](/integrations/sentry-integration) for one example use case.</p> <aside className="parameter"> <h5>Returns<code>string<string></code></h5> </aside> </div> <div className="right"> <code> const highlightSessionUrl = await H.getSessionURL();
thirdPartyApi.setMetadata({ highlightSessionUrl }); </code>
Copy
</div> </section> <section className="section"> <div className="left"> <h3>H.start</h3> <p>This method is used to start Highlight if H.init() was called with manualStart set to true.</p> <h6>Method Parameters</h6> <aside className="parameter"> <h5>options<code>StartOptions</code> <code>optional</code></h5> <p>Optional configuration parameters.</p> <article className="innerParameterContainer"> <aside className="innerParameterHeading">options properties</aside> <aside className="parameter"> <h5>silent <code>boolean</code> <code>optional</code></h5> <p>Specifies whether console.warn messages created in this method should be skipped.</p> </aside> </article> </aside> </div> <div className="right"> <code> H.init("<YOUR_PROJECT_ID>", { manualStart: true });
// Elsewhere in your app H.start({ silent: false }); </code>
Copy
</div> </section> <section className="section"> <div className="left"> <h3>H.stop</h3> <p>This method is used to stop Highlight from recording. Recording can be resumed later by calling H.start().</p> </div> <div className="right"> <code> H.init("<YOUR_PROJECT_ID>");
// Elsewhere in your app H.stop(); </code>
Copy
</div> </section> <section className="section"> <div className="left"> <h3>H.addSessionFeedback</h3> <p>This method is used to add session feedback for the session. You can learn more in [User Feedback](/product-features/user-feedback). If you don't want to implement your own UI to collect feedback, you can use the UI that Highlight provides.</p> <h6>Method Parameters</h6> <aside className="parameter"> <h5>feedbackOptions<code>SessionFeedbackOptions</code> <code>required</code></h5> <p>The feedback details to collect.</p> <article className="innerParameterContainer"> <aside className="innerParameterHeading">feedbackOptions properties</aside> <aside className="parameter"> <h5>verbatim <code>string</code> <code>required</code></h5> <p>The feedback string that a user has inputted into your app.</p> </aside> <aside className="parameter"> <h5>userName <code>string</code> <code>optional</code></h5> <p>The user's name. This is only required if you have not called H.identify().</p> </aside> <aside className="parameter"> <h5>userEmail <code>string</code> <code>optional</code></h5> <p>The user's email. This is only required if you have not called H.identify().</p> </aside> </article> </aside> </div> <div className="right"> <code> H.addSessionFeedback({ verbatim: 'I L O V E the new feature that shows me cat gifs. Please keep shipping features like this!' }) </code> </div> </section> <section className="section"> <div className="left"> <h3>H.toggleSessionFeedbackModal</h3> <p>Calling this will toggle the visibility of the feedback modal. You can learn more in [User Feedback](/product-features/user-feedback).</p> </div> <div className="right"> <code> H.toggleSessionFeedbackModal() </code> </div> </section>