Client SDK API Reference

Client SDK

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.

Just getting started?

Check out our getting started guide to get up and running quickly.

H.init

This method is called to initialize Highlight in your application.

Method Parameters

options `HighlightOptionsoptional`

Configuration for Highlight client recording.

H.init("<YOUR_PROJECT_ID>", {
    // Your config options here...
});

H.identify

This method is used to add an identity to a user for the session. You can learn more in Identifying Users.

Method Parameters

H.identify("alice@corp.com", {
    highlightDisplayName: "Alice Customer",
    accountType: "premium",
    hasUsedFeature: true
});

H.track

This method is used to track events that happen during the session. You can learn more in Tracking Events.

Method Parameters

H.track("Opened Shopping Cart", {
    accountType: "premium",
    cartSize: 10
});

H.consumeError

This method is used to send a custom error to Highlight.

Method Parameters

H.consumeError(error, 'Error in Highlight custom boundary!', {
  component: 'JustThroughAnError.tsx',
});

H.metrics

This method is used to submit custom metrics.

Method Parameters

H.metrics([{
  name: 'clicks',
  value: 1,
  tags: [{ browser }]
}, {
  name: 'auth_time',
  value: authDelay,
  tags: [{ version: 'v2' }]
}

H.startSpan

This method is used to start a new span. Spans created with this method are automatically ended after the callback function completes, whether it returns normally or throws an error.

Check out startManualSpan if you want to have more control over when the span is ended.

Method Parameters

H.startSpan('fetchData', { attributes: { key: 'value' } }, context, (span) => {
  // Your code here
});

// Note: the options and context arguments are not required, so you can
// call this function with only a span name + callback.
H.startSpan('fetchData', () => {
  // Your code here
});

H.startManualSpan

This method is used to start a new manual span. Use this when you don't want the span to be ended automatically. You need to end these spans by calling span.end()

Method Parameters

H.startManualSpan('fetchData', { attributes: { key: 'value' } }, context, (span) => {
  // Your code here

  span.end()
});

// Note: the options and context arguments are not required, so you can
// call this function with only a span name + callback.
H.startManualSpan('fetchData', (span) => {
  // Your code here

  span.end()
});

H.getSessionDetails

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.

H.getSessionDetails().then(({url, urlWithTimestamp}) => {
    console.log(url, urlWithTimestamp);
});

H.getSessionURL

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.

const highlightSessionUrl = await H.getSessionURL();
thirdPartyApi.setMetadata({
    highlightSessionUrl
});

H.start

This method is used to start Highlight if H.init() was called with manualStart set to true.

Method Parameters

H.init("<YOUR_PROJECT_ID>", {
    manualStart: true
});

// Elsewhere in your app
H.start({
    silent: false
});

H.stop

This method is used to stop Highlight from recording. Recording can be resumed later by calling H.start().

H.init("<YOUR_PROJECT_ID>");
// Elsewhere in your app
H.stop();