Source Maps - Atatus Docs

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:

There must be a stack trace.
The minified JavaScript files as specified in the stack trace, must be publicly accessible.
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
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

Name	Description
projectId (Required)	A unique identifier for a project. See here to locate the project ID
api_key (Required)	See here to locate the API key
url (Required)	The full URL of the minified file. If the URL start with http: or https:, we’ll strip it off
sourcemap (Required)	The contents of the source map, as a multipart file upload
version (optional)	A string identifying what version of your code this source map is for. Note that if you set a version in your app, but do not set one when you upload your sourcemap (or vice versa), then that sourcemap will not be applied.

Version number is only necessary if the script filename (url) is the same across all deployments. If you have set a version number in source map, you must also set the version in Atatus snippet and vice versa. atatus.setVersion('version_string_here')

Response Codes

Status Code	Meaning
200	OK - uploaded successfully
422	Non processable entity - there was an error validating the upload

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.

Name	Description
olderThan	The time duration. The source maps older than specified time duration will be deleted. Example: 1d, 2d, 3d, 7d, 14d, 1M, 2M, 3M
versions	The comma separated version numbers of the source map to be deleted
all	Delete all source maps. It must be set to true. Example: `all=true`

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.

Please note that, if you do not set a version number in your script but upload a source map with a version number set, then source map will not work. Please keep this in mind.

​Option A: Automatic source maps download

​Option B: Uploading source maps

​Sample

​Parameters

​Response Codes

​Delete Source Maps

​Parameters

​Source Maps for Hybrid Mobile Apps

​When you should use version number

Option A: Automatic source maps download

Option B: Uploading source maps

Sample

Parameters

Response Codes

Delete Source Maps

Parameters

Source Maps for Hybrid Mobile Apps

When you should use version number