Ionic makes it easy to build interactive mobile apps using HTML5 and AngularJS. You need a powerful monitoring tool to identify and debug errors. Atatus integrates into Ionic with just a few lines of code.

Agent Installation

If you want to include Atatus script with your source, you can add it through package managers such as YARN and NPM.

With NPM

Installation

  1. Install atatus-js from the npm registry:

    copy
    icon/buttons/copy
    npm install --save atatus-js
    

    Import and initialize atatus to monitor your application:

    copy
    icon/buttons/copy
    import * as atatus from 'atatus-js';
    atatus.config('YOUR_API_KEY').install();
    

    For more advanced options on installing your monitoring code, view customizing agent.

  2. Add atatus to the angular exception handler

    copy
    icon/buttons/copy
    angular.module('YOUR_APP').factory('$exceptionHandler', ['$window', function ($window) {
      return function (exception, cause) {
        if ($window.atatus) {
          $window.atatus.notify(exception);
        }
      };
    }]);
    // Clean path in the stack trace
    if ($window.atatus) {
      $window.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("/www/");
              if (indexOfJsRoot !== -1) {
                backTrace.f = filename.substring(indexOfJsRoot);
              }
          }
          return true;
      });
    }
    

Test Integration

To verify that your integration is working, call notify() in your application:

copy
icon/buttons/copy
atatus.notify(new Error('Test Atatus Setup'));

An error will appear in your project dashboard.

With YARN

Installation

  1. Install atatus-js from the npm registry:

    copy
    icon/buttons/copy
    yarn add atatus-js
    

    Import and initialize atatus to monitor your application

    copy
    icon/buttons/copy
    import * as atatus from 'atatus-js';
    atatus.config('YOUR_API_KEY').install();
    

    For more advanced options on installing your monitoring code, view customizing agent.

  2. Add atatus to the angular exception handler

    copy
    icon/buttons/copy
    angular.module('YOUR_APP').factory('$exceptionHandler', ['$window', function ($window) {
      return function (exception, cause) {
        if ($window.atatus) {
          $window.atatus.notify(exception);
        }
      };
    }]);
    // Clean path in the stack trace
    if ($window.atatus) {
      $window.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("/www/");
              if (indexOfJsRoot !== -1) {
                backTrace.f = filename.substring(indexOfJsRoot);
              }
          }
          return true;
      });
    }
    

Test Integration

To verify that your integration is working, call notify() in your application:

copy
icon/buttons/copy
atatus.notify(new Error('Test Atatus Setup'));

An error will appear in your project dashboard.

Track exceptions in Ionic apps

If you are loading atatus script from our CDN, then you have to use full URL instead of protocol-relative URL.

copy
icon/buttons/copy
<script src="https://dmc1acwvwny3.cloudfront.net/atatus.js"></script>
<script type="text/javascript"> atatus.config('YOUR_API_KEY').install();</script>

Since Ionic framework is built on AngularJS framework, you have to follow Angular integration documentation.

Clean file URL in error stack trace

Many mobile applications being written in JavaScript within containers such as Apache Cordova, Ionic, PhoneGap etc.. So you may find that error stack traces contain file paths which are different across platforms and devices. Using onBeforeErrorSend method, you can rewrite file's URLs before the error is reported back to Atatus.

This will make the stack traces more easily readable.

copy
icon/buttons/copy
atatus.onBeforeErrorSend(function (payload) {
    var backTraces = payload.backTraces;
    for(var i = 0 ; i &lt; backTraces.length; i++) {
        var backTrace = backTraces[i];
        var filename = backTrace.f;
        var indexOfJsRoot = filename.indexOf("/www/");
        if (indexOfJsRoot !== -1) {
        backTrace.f = 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/app.js

It will be reported to Atatus as follows

 /www/js/app.js

Using Source Maps

If you uploaded the source maps for JavaScript files, then you have to append corresponding domain name before the path. Let us say, you have uploaded a source map for a script file https://www.acme.com/www/js/app.min.js, then your code should look like

copy
icon/buttons/copy
atatus.onBeforeErrorSend(function (payload) {
    var backTraces = payload.backTraces;
    for(var i = 0 ; i &lt; backTraces.length; i++) {
        var backTrace = backTraces[i];
        var filename = backTrace.f;
        var indexOfJsRoot = filename.indexOf("/www/");
        if (indexOfJsRoot !== -1) {
        // Append a domain name in the file
        backTrace.f = 'https://www.acme.com' +  filename.substring(indexOfJsRoot);
        }
    }
    return true;
});

Let us say, an error is occurring on the file path in Ionic framework

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

It will be reported to Atatus as https://www.acme.com/www/js/app.min.js and the corresponding uploaded source map will be fetched and processed.