1. Home
  2. Language Guides
  3. Browser reporting
  4. Crash Reporting
  5. Reporting API

Reporting API

The Reporting API defines a new HTTP response header, Report-To, that gives you a way to define an endpoint for the browser to report warnings and issues encountered by your users.

The Raygun Reporting API endpoint currently supports the delivery of Content Security Policy violations, deprecations, browser interventions, crash reports and network errors (NEL).

Please note that the Reporting API is a draft specification and is not fully supported by all browsers.

Switch to the Raygun Reporting API

If you're already using the Reporting API on your website then read how to Switch to the Raygun Reporting API

First, set the Report-To header to be one or more named endpoints as shown in the example below. Note that we've set the group to be named "raygun" which is used in the next step.

Report-To: {
    "group": "raygun",
    "max_age": 10886400,
    "include_subdomains": true,
    "endpoints": [{
      "url": "https://report-to-api.raygun.com/reports?apikey=<YOUR-API-KEY>"
    }]
  }

You can now set the report-to directive of other response headers to be the named endpoint of where you want those reports to be sent. In the examples below, we are using the "raygun" named endpoint that was defined above.

Content Security Policy (CSP)

Further documentation on our CSP support can be found here.

Content-Security-Policy: ...; report-to raygun

Network Error Logging (NEL)

Further documentation on our NEL support can be found here.

NEL: {
    "report_to": "raygun",
    "max_age": 10886400,
  }

If you already have a reporting API endpoint defined, then switching it to Raygun is as simple as changing the group endpoint url property. Just change the endpoint url to the Raygun browser reporting API endpoint like in the before and after example below. Use the API key of the application in Raygun where you'd like the reports to be sent to.

# Existing policy
Report-To: {
    "group": "report-endpoint",
    "max_age": 10886400,
    "endpoints": [{
      "url": "https://example.com/reports"
    }]
  }
 
# Updated policy
Report-To: {
    "group": "report-endpoint",
    "max_age": 10886400,
    "endpoints": [{
      "url": "https://report-to-api.raygun.com/reports?apikey=<YOUR-API-KEY>"
    }]
  }

Providing user information will allow your Raygun dashboard to display the number of unique users that each browser issue has affected. This is a huge help with prioritising issues to solve that have the largest impact. You can provide whatever user information that will help you solve issues, but make sure to abide by any privacy policies that your company follows. At the very least, providing a unique guid will allow you to see the number of users that are affected by each policy violation. If available, you could provide an ID that is meaningful to you such as a database ID. If you are able to provide a name and contact details, you'd be able to contact customers to let them know that issues they've encountered are being worked on, or have been solved.

Since there is no way to inject data into a browser report payload you can provide user information via the URL that is used to report to Raygun. The user querystring parameter can be set to a URL encoded JSON object that represents a user.

# A user object like this would be URL encoded into the endpoint url
# {"identifier":"123456789","isAnonymous":false}

Report-To: {
    "group": "raygun",
    "max_age": 10886400,
    "endpoints": [{
      "url": "https://report-to-api.raygun.com/reports
                ?apikey=<YOUR-API-KEY>
                &user=%7B%22identifier%22%3A%22123456789%22%2C%22isAnonymous%22%3Afalse%7D"
    }]
  }

Here are all the available user properties:

  • identifier is the unique identifier from your system for this user.
  • isAnonymous is a flag indicating whether the user is logged in (or identifiable) or if they are anonymous. An anonymous user can still have a unique identifier.
  • email The user's email address. If you use email addresses to identify your users, feel free to set the identifier to their email and leave this blank. We will use the identifier as the email address if it looks like one, and if no email address is specified in this field.
  • fullName The user's full name.
  • firstName The user's first (or preferred) name.
  • uuid A device identifier. Could be used to identify users across devices, or machines that are breaking for many users.

When a browser report is recorded we automatically tag the report with key pieces of information from the report. You can add additional tags to the browser reports by appending a tags querystring parameter to the endpoint url that represents a URL encoded JSON string array.

# Tags can be URL encoded into the endpoint url
# ["tag1","tag2"]

Report-To: {
    "group": "raygun",
    "max_age": 10886400,
    "endpoints": [{
      "url": "https://report-to-api.raygun.com/reports
                ?apikey=<YOUR-API-KEY>
                &tags=%5B%22tag1%22%2C%22tag2%22%5D"
    }]
  }

You can insert key-value custom data to your browser reports by appending a customData querystring parameter to the endpoint url that represents a URL encoded JSON object.

# Custom data can be URL encoded into the endpoint url
# {"area": "51"}

Report-To: {
    "group": "raygun",
    "max_age": 10886400,
    "endpoints": [{
      "url": "https://report-to-api.raygun.com/reports
                ?apikey=<YOUR-API-KEY>
                &customData=%7B%22area%22%3A%20%2251%22%7D"
    }]
  }

The version number of your application can be appended to any browser reports by appending a version querystring parameter to the endpoint url that represents a URL encoded string.

# A version can be URL encoded into the endpoint url

Report-To: {
    "group": "raygun",
    "max_age": 10886400,
    "endpoints": [{
      "url": "https://report-to-api.raygun.com/reports
                ?apikey=<YOUR-API-KEY>
                &version=1.0.0.1"
    }]
  }

On this page: