Source Maps

Atatus supports source maps to reverse JavaScript minification. This feature makes use of JavaScript Source Maps to translate the minified code references back into the original source. If your source map is publicly web-accessible, we can download it automatically. Otherwise, you can upload it via our API.

Option A: Automatic source maps download

If your source map is publicly web-accessible, we can download it automatically. Atatus requires the following to complete the decode process:

1. There must be a stack trace.
2. The minified JavaScript files as specified in the stack trace, must be publicly accessible.

3. The map file is to be correctly indicated in the minified JavaScript file using a footer comment. As specified in the Source Map Specification, following comment should be at the bottom of your minified JavaScript files:

   //# sourceMappingURL=URL_TO_SOURCE_MAP
   

4. The source map file itself must be publicly accessible.

How it works: If we receive a JavaScript error, and we don’t already have the source map for the current code version, we will schedule an attempt to download it. For each stack frame, we’ll first download the minified source file and look for a sourceMappingUrl comment. If it has one, we’ll try to download that file and cache it as the source map. Then for future errors, we’ll use the source map to translate the minified frames back to original frames.

Option B: Uploading source maps

If you do not want to expose your source map or code to the public web, you can upload them directly to Atatus. At the beginning of your deploy script (before the new code is in production), you can upload a source map via our API.

curl  https://api.atatus.com/v2/projects/:projectId/sourcemap \
    -F api_key="YOUR_API_KEY_HERE" \
    -F url=http://www.acme.com/js/main.min.js \
    -F sourcemap=@js/main.min.js.map \
    -F version=version_string_here

Sample

curl  https://api.atatus.com/v2/projects/5c7cb42cdbe639200c330e52/sourcemap \
    -F api_key="79769089efbb4767a542e0696448e34c" \
    -F url=http://www.acme.com/js/main.min.js \
    -F sourcemap=@js/main.min.js.map \
    -F version=1.0.0

Parameters

Response Codes

The source map is stored as project + minified URL + version. Uploading it more than once will lead to writing over the previous data.

Delete Source Maps

You can use the delete API to delete all older source maps or specific versions of source maps or source maps from specific days.

curl -XDELETE  -H "X-API-KEY: YOUR_API_KEY_HERE" \
     https://api.atatus.com/v2/projects/:projectId/sourcemap?olderThan=1M

curl -XDELETE  -H "X-API-KEY: YOUR_API_KEY_HERE" \
     https://api.atatus.com/v2/projects/:projectId/sourcemap?versions=1.0.0,2.0.0

curl -XDELETE  -H "X-API-KEY: YOUR_API_KEY_HERE" \
     https://api.atatus.com/v2/projects/:projectId/sourcemap?all=true

Parameters

You have to specify one of the below mentioned parameters but, you can only specify one parameter at a time.

Source Maps for Hybrid Mobile Apps

In hybrid mobile applications, such as Ionic, PhoneGap, Apache Cordova etc., you might find the error stack traces containing file paths which are different across platforms and devices. This creates complexity when trying to use source maps, because source map requires the minifed URL that is used during upload matches with the URL that would appear in a stack trace.

For this reason we recommend adding a handler to rewrite file's URLs before the error is reported back to Atatus. An example of such a handler is shown below:

atatus.onBeforeErrorSend(function (payload) {
    var backTraces = payload.backTraces;
    for(var i = 0 ; i < backTraces.length; i++) {
        var backTrace = backTraces[i];
        var filename = backTrace.f;
        var indexOfJsRoot = filename.indexOf("/js/");
        if (indexOfJsRoot !== -1) {
            backTrace.f = 'http://mywebsite.com' + filename.substring(indexOfJsRoot);
        }
    }
    return true;
});

Let us consider an error occurring on the file path in Ionic framework

file:///private/var/mobile/Containers/Bundle/Application/D99DDCCC-9D37-4E12-96E5-093C771BA080/MyApp.app/www/js/main.min.js

It will be reported to Atatus as follows:

http://mywebsite.com/js/main.min.js

You must upload your source map as follows (note that the reported error and the uploaded minified URL are identical http://mywebsite.com/)

curl  https://api.atatus.com/v2/projects/:projectId/sourcemap \
    -F api_key="YOUR_API_KEY_HERE" \
    -F url=http://mywebsite.com/js/main.min.js \
    -F sourcemap=@js/main.min.map \
    -F version=1.0.0

When you should use version number

Some prefer to have same script file name across all deployments. An example would be, if you decide to have your JavaScript file as https://www.acme.com/scripts/main.js

In this case, source map could end up being different for every deployment, depending upon the changes in your main.js file. In order to differentiate these files, you have to set version number in your script side as well as when you upload the source map.

There would be cases where you change your script file name every time you build it, using a version number(random) in the name of the file(example, https://www.acme.com/scripts/main-4ef53.js). By doing so, every deploy will have a unique script file name. So you do not need to set version number at your script side. Therefore, when you upload the source map too, you should not set the version number.