Installing the Agent
Installing the Browser Agent means including JavaScript into your website’s source code and calling the install function. The function will automatically collect the activity and metrics from your end users, and expose APIs for you to send along custom data.
There are 3 ways to include the agent in your website depending on the kind of application you are building. The default and simplest way is using the JavaScript Snippet, which loads the agent from our CDN directly on your page. This is very similar to how other analytics tools work.
You can also load the agent using an NPM Module or with a Script Tag.
JavaScript Snippet
The JavaScript snippet is the default installation method because it requires only a very small code change, a small performance impact, and makes the Request Metrics API available to you everywhere in your code. This is a great place to start when trying out the service.
<!-- Request Metrics -->
<script>
(function(t,e,n,r){function a(){return e&&e.now?e.now():null}if(!n.version){n._events=[];n._errors=[];n._metadata={};n._urlGroup=null;window.RM=n;n.install=function(e){n._options=e;var a=t.createElement("script");a.async=true;a.crossOrigin="anonymous";a.src=r;var o=t.getElementsByTagName("script")[0];o.parentNode.insertBefore(a,o)};n.identify=function(t,e){n._userId=t;n._identifyOptions=e};n.sendEvent=function(t,e){n._events.push({eventName:t,metadata:e,time:a()})};n.setUrlGroup=function(t){n._urlGroup=t};n.track=function(t,e){n._errors.push({error:t,metadata:e,time:a()})};n.addMetadata=function(t){n._metadata=Object.assign(n._metadata,t)}}})(document,window.performance,window.RM||{},"https://cdn.requestmetrics.com/agent/current/rm.js");
RM.install({
token: "your:token"
});
</script>All you have to do is copy-and-paste the JavaScript snippet into your HTML markup.
Where do I paste this?
The JavaScript snippet is a <script> tag that you include in your HTML markup. Generally, you want to include this in the <head> tag, as early as possible, because the RM API is not available until after the snippet.
You’ll want to paste it into a common template or layout that all the pages in your website use so that you only have to include it once. Make sure you include it on error pages as well!
What does this do?
The snippet has a bit of minified JavaScript that creates a fake of the RM API so that your code can call it right away. This is helpful so you can send metadata or identify the user right at the start of the page. It also places an async script tag to load the real browser agent, which will execute any of the queued API calls.
Finally, the snippet calls install with your website token. Install will instrument the browser to collect activity, errors, and metrics automatically.
Can I host this myself?
Yes of course! The last bit of the JavaScript snippet contains the URL to load the agent from. By default, it’s https://cdn.requestmetrics.com/agent/current/rm.js. If you’d like to host the agent on your own servers and point to it, just change this URL.
You’ll also need to change this when you set up Domain Forwarding.
NPM Module
The browser agent can also be included as a module from NPM. If you are building a rich JavaScript application and bundling it with Webpack, Rollup, or some other tool, this is probably what you want to do. This method also gives you control on when agent changes are made and removes the initial connection request to our domain during page load.
You’ll need to install the browser agent package in your package.json.
npm install @request-metrics/browser-agent --save
Then import the package and call the install function.
import { RM } from '@request-metrics/browser-agent';
RM.install({ token: 'YOUR_TOKEN' });
Or, if you are using an older JavaScript runtime, you may need to use the require syntax:
var RM = require('@request-metrics/browser-agent').RM;
RM.install({ token: 'YOUR_TOKEN' });
Where do I add this?
You should call install as early as possible during the initialization of your application. The index file would be a good place to start, or maybe in a file called main or App, depending on your framework.
What about Server Side Rendering (SSR)?
The browser agent only collects information and metrics when it is run in the client-side browser environment. Pulling performance metrics and interaction events doesn’t really make sense when you are pre-rendering HTML. The agent will detect that it’s in a server environment and no-op commands so that you don’t need to change anything in your code.
Script Tag
The Request Metrics Agent supports asynchronous loading and will have little impact on page performance.
<!-- Request Metrics -->
<script src="https://cdn.requestmetrics.com/agent/current/rm.js" async crossorigin="anonymous"
data-rm-token="your:token"></script>
Just copy and paste this markup into your page.
TIP: Most performance metrics are captured even when the script is loaded asynchronously. However, user interactions and JS errors that occur before the script has loaded will be missed. If you want to make sure that you capture every interaction and error, you might want to include the agent script tag synchronously. While this has a small performance cost to download and run the agent immediately, you will get greater data accuracy.
Where do I paste this?
Because the goal of this installation method is to capture more accurate data, we recommend adding this tag as early as possible, and before any other JavaScript on the page. This will guarantee that events and errors will be recorded. Generally, you want to include this in the <head> tag, as early as possible, because the RM API is not available until after the snippet.
You’ll want to paste it into a common template or layout that all the pages in your website use so that you only have to include it once. Make sure you include it on error pages as well!
Can I host this myself?
Yes of course! Just take a copy of the file and host it wherever you like. Just change the src URL. You’ll also need to change this when you set up Domain Forwarding.
Web Workers
The browser agent fully supports operating in a Web Worker or Service Worker, so that you can collect errors, API calls, and events from within those contexts. You are likely using a web application framework, so you should use the NPM Module installation method.
Make sure you call install when initializing the worker code.
Troubleshooting
ERR_BLOCKED_BY_CLIENT
Request Metrics, like many other analytics and monitoring tools, is often blocked by Ad Blocking extensions and browsers. Loading the agent, or later sending data will be blocked. Try disabling the ad blocker on your website, or add an exclusion for requestmetrics.com.
Won’t my end users block Request Metrics too? Yes, maybe. We recommend setting up Domain Forwarding, so that the data flows through your own domain.
Violates Content Security Policy
Refused to load the script 'https://cdn.requestmetrics.com/agent/current/rm.js' because it violates Content Security Policy.
Your website is sending a Content Security Policy header that specifies what domains are allowed to include scripts. You’ll need to add our Content Security Policy rules for Request Metrics to operate.