The PVYapplytics browser SDK allows you to instrument your frontend application to send events to PVYapplytics. This allows you to view network requests and exceptions alongside backend events in a single timeline.
Additionally, it’ll automatically capture and correlate session replay data, so you can visually step through and debug what a user was seeing while using your application.
This Guide Integrates: Console Logs · Session Replays · XHR/Fetch/Websocket Requests · Exceptions
At PVY.swiss, we use Browser JS Implementation only during Development, Beta and Preflight Phases. We highly recommend to use especially the Session-Replay feature only during these kind of product development stages. Its sufficient enough for production environments, to remove the API Token and Target. Alternatively, for debugging reasons, you can code a feature for it, and let user enable that, for trouble shooting. Or at least disable the Session Replay Feature, for privacy and storage reason.
Install via package import (Recommended)
Use the following command to install the PVYapplytics Browser package:
npm install @pvyapplytics/browser
Initialze PVYapplytics
import PVYAPPLYTICS from '@pvyapplytics/browser';
PVYapplytics.init({
apiKey: 'YOUR_INGESTION_API_KEY',
service: 'my-frontend-app',
tracePropagationTargets: [/api.myapp.domain/i], // Set to link traces from frontend to backend requests
consoleCapture: true, // Capture console logs (default false)
advancedNetworkCapture: true, // Capture full HTTP request/response headers and bodies (default false)
});
Options
apiKey - Your HyperDX Ingestion API Key.
service - The service name events will show up as in HyperDX.
tracePropagationTargets - A list of regex patterns to match against HTTP requests to link frontend and backend traces, it will add an additional traceparent header to all requests matching any of the patterns. This should be set to your backend API domain (ex. api.yoursite.com).
consoleCapture - (Optional) Capture all console logs (default false).
advancedNetworkCapture - (Optional) Capture full request/response headers and bodies (default false).
url - (Optional) The OpenTelemetry collector URL, to your PVYapplytics instances.
maskAllInputs - (Optional) Whether to mask all input fields in session replay (default false).
maskAllText - (Optional) Whether to mask all text in session replay (default false).
disableIntercom - (Optional) Whether to disable Intercom integration (default false)
disableReplay - (Optional) Whether to disable session replay (default false)
Masking Options can be helpfully in terms of users privacy policies. If you have a kind of third party ChatBot or Intercom integrated into your Application, you can keep these out of your Analytics, but as well usernames and user related data, eg on a eCommerce Platform.
Upload Source Maps
Uploading source maps to PVYapplytics allows you to see the original source code and stack trace for errors that occur in your minified or transpiled code. To upload source maps, you’ll need to set up the PVYapplytics CLI and run the upload-sourcemaps command after your build step.
This is a really powerful feature, allowing you in compliled minified code, to see the root cause of your programming error super quickly. View the full guide on uploading source maps.
Attach User Information or Metadata
Attaching user information will allow you to search/filter sessions and events in HyperDX. This can be called at any point during the client session. The current client session and all events sent after the call will be associated with the user information.
userEmail, userName, and teamName will populate the sessions UI with the corresponding values, but can be omitted. Any other additional values can be specified and used to search for events. Very useful to nail down some repeating issue, which just arrise on certain user (may regex issue?) or abnormal behaviour and its dedection.
PVYapplytics.setGlobalAttributes({
userId: user.id,
userEmail: user.email,
userName: user.name,
teamName: user.team.name,
// Other custom properties...
});
Auto Capture React Error Boundary Errors
If you’re using React, you can automatically capture errors that occur within React error boundaries by passing your error boundary component into the attachToReactErrorBoundary function.
// Import your ErrorBoundary (we're using react-error-boundary as an example)
import { ErrorBoundary } from 'react-error-boundary';
// This will hook into the ErrorBoundary component and capture any errors that occur
// within any instance of it.
PVYapplytics.attachToReactErrorBoundary(ErrorBoundary);
Send Custom Actions
To explicitly track a specific application event (ex. sign up, submission, etc.), you can call the addAction function with an event name and optional event metadata.
Example:
PVYapplytics.addAction('Form-Completed', {
formId: 'signup-form',
formName: 'Signup Form',
formType: 'signup',
});
Enable Network Capture Dynamically
To enable or disable network capture dynamically, simply invoke the enableAdvancedNetworkCapture or disableAdvancedNetworkCapture function as needed.
PVYapplytics.enableAdvancedNetworkCapture();
Enable Resource Timing for CORS Requests
If your frontend application makes API requests to a different domain, you can optionally enable the Timing-Allow-Originheader to be sent with the request. This will allow PVYapplytics to capture fine-grained resource timing information for the request such as DNS lookup, response download, etc. via PerformanceResourceTiming.
If you’re using express with cors packages, you can use the following snippet to enable the header:
var cors = require('cors');
var onHeaders = require('on-headers');
// ... all your stuff
app.use(function (req, res, next) {
onHeaders(res, function () {
var allowOrigin = res.getHeader('Access-Control-Allow-Origin');
if (allowOrigin) {
res.setHeader('Timing-Allow-Origin', allowOrigin);
}
});
next();
});
app.use(cors());
Install via Script Tag (Alternative)
You can also include and install the script via a script tag as opposed to installing via NPM. This will expose the PVYapplytics global variable and can be used in the same way as the NPM package.
This is recommended if your site is not currently built using a bundler.
<script src="//www.unpkg.com/@hyperdx/browser@0.21.0/build/index.js"></script>
<script>
window.PVYapplytics.init({
apiKey: 'YOUR_INGESTION_API_KEY',
service: 'my-frontend-app',
tracePropagationTargets: [/api.mypvyapplytics.domain/i], // Set to link traces from frontend to backend requests
});
</script>
Options
apiKey - Your HyperDX Ingestion API Key.
service - The service name events will show up as in HyperDX.
tracePropagationTargets - A list of regex patterns to match against HTTP requests to link frontend and backend traces, it will add an additional traceparent header to all requests matching any of the patterns. This should be set to your backend API domain (ex. api.yoursite.com).
consoleCapture - (Optional) Capture all console logs (default false).
advancedNetworkCapture - (Optional) Capture full request/response headers and bodies (default false).
url - (Optional) The OpenTelemetry collector URL, to your PVYapplytics instances.
maskAllInputs - (Optional) Whether to mask all input fields in session replay (default false).
maskAllText - (Optional) Whether to mask all text in session replay (default false).
disableIntercom - (Optional) Whether to disable Intercom integration (default false)
disableReplay - (Optional) Whether to disable session replay (default false)
Masking Options can be helpfully in terms of users privacy policies. If you have a kind of third party ChatBot or Intercom integrated into your Application, you can keep these out of your Analytics, but as well usernames and user related data, eg on a eCommerce Platform.
Upload Source Maps
Uploading source maps to PVYapplytics allows you to see the original source code and stack trace for errors that occur in your minified or transpiled code. To upload source maps, you’ll need to set up the PVYapplytics CLI and run the upload-sourcemaps command after your build step.
This is a really powerful feature, allowing you in compliled minified code, to see the root cause of your programming error super quickly. View the full guide on uploading source maps.
Attach User Information or Metadata
Attaching user information will allow you to search/filter sessions and events in HyperDX. This can be called at any point during the client session. The current client session and all events sent after the call will be associated with the user information.
userEmail, userName, and teamName will populate the sessions UI with the corresponding values, but can be omitted. Any other additional values can be specified and used to search for events. Very useful to nail down some repeating issue, which just arrise on certain user (may regex issue?) or abnormal behaviour and its dedection.
PVYapplytics.setGlobalAttributes({
userId: user.id,
userEmail: user.email,
userName: user.name,
teamName: user.team.name,
// Other custom properties...
});
Auto Capture React Error Boundary Errors
If you’re using React, you can automatically capture errors that occur within React error boundaries by passing your error boundary component into the attachToReactErrorBoundary function.
// Import your ErrorBoundary (we're using react-error-boundary as an example)
import { ErrorBoundary } from 'react-error-boundary';
// This will hook into the ErrorBoundary component and capture any errors that occur
// within any instance of it.
PVYapplytics.attachToReactErrorBoundary(ErrorBoundary);
Send Custom Actions
To explicitly track a specific application event (ex. sign up, submission, etc.), you can call the addAction function with an event name and optional event metadata.
Example:
PVYapplytics.addAction('Form-Completed', {
formId: 'signup-form',
formName: 'Signup Form',
formType: 'signup',
});
Enable Network Capture Dynamically
To enable or disable network capture dynamically, simply invoke the enableAdvancedNetworkCapture or disableAdvancedNetworkCapture function as needed.
PVYapplytics.enableAdvancedNetworkCapture();
Enable Resource Timing for CORS Requests
If your frontend application makes API requests to a different domain, you can optionally enable the Timing-Allow-Originheader to be sent with the request. This will allow PVYapplytics to capture fine-grained resource timing information for the request such as DNS lookup, response download, etc. via PerformanceResourceTiming.
If you’re using express with cors packages, you can use the following snippet to enable the header:
var cors = require('cors');
var onHeaders = require('on-headers');
// ... all your stuff
app.use(function (req, res, next) {
onHeaders(res, function () {
var allowOrigin = res.getHeader('Access-Control-Allow-Origin');
if (allowOrigin) {
res.setHeader('Timing-Allow-Origin', allowOrigin);
}
});
next();
});
app.use(cors());