Error Learn

Learn, DAMN IT! This documentation will cover the following:

• Setup
• How it works
• Using
• Advanced usage
• Security concerns

Setup

1. Obtain an application key

1. Sign up at damnit.jupiterit.com.
2. Click the link in the confirmation email.
3. Get your Application Key on the setup instructions page. Your key is assigned to your email address and can be used for any number of sites.

2. Include the error plugin

Assuming you've correctly set up your JavaScriptMVC application, the following code includes the error plugin and defines your application key. Make sure you replace _APPLICATION_KEY_ with your application key.

APPLICATION_KEY='_APPLICATION_KEY_';
include.plugins('error');

The error plugin only reports errors in production mode.

How it works

APPLICATION_KEY='_KEY_';

include.plugins('error');

3. An error happens

When an error is captured or the onerror event is triggered, the error is sent to DamnIT's server. Your server isn't involved.

4. Optional description

You can optionally let your users provide a description before the error is sent.

5. You get an email

DamnIT instantly sends you an email detailing the error.

See it in action!

Read the learn page for more information on installing Error.

Using

We'll walk through:

• how to catch errors in all the browsers
• browser support for error reporting functionality
• how to configure Error

Catching Errors

IE and Mozilla support the onerror event, while Opera and Safari do not. Thus, Error works automatically in IE and Mozilla, while you have to wrap your code in try...catch blocks in other browsers to add Error's notification functionality. If you're using the Controller plugin, your code is covered across all browsers.

IE and Mozilla: Automatic Support

These browsers require no additional code in your application to catch all errors and notify you. For many apps, IE and Mozilla support is sufficient, since they make up 91% of the browser market.

Safari and Opera: Wrap your Code with try...catch

Opera and Safari don't support the onerror event, so add Error functionality like this:

try { // 1
   this.will.cause.an.error();
} catch(e) {
   ApplicationError.notify(e); // 2
}

1. Place try...catch blocks around your application code.
2. ApplicationError.notify accepts an error object and performs the same functionality as the onerror event handler for IE and Mozilla: prompting the user and sending error information to the DamnIT servers.

Error with Controller: Cross Browser Support

The easiest way to maximize Error's code coverage for all browsers is to use Controller to define your event handlers. Errors within event handlers defined using Controller are automatically caught and reported across all browsers.

Browser Support

Configuring Error

Error provides the ability to customize the contents of its user prompt or to turn off the user prompt entirely.

Turning off user prompt

During beta testing, its useful to ask testers to describe their actions the preceded the error. As you move into production, you may wish to turn this functionality off. You can do so with the prompt_user option of ApplicationError's config method:

ApplicationError.config({prompt_user: false});

Configuring user prompt

You can configure the user prompt to say what you like and stay open for as long as you'd like:

ApplicationError.config({
   prompt_text: 'DAMN IT YOU BROKE IT!', 
   textarea_title: 'Please explain.', 
   close_time: 4
});

The above configuration creates the following user prompt:

Modified user prompt

Advanced Usage

After you mastered the basics, you can start adding your own functionality to your notification emails. You can:

• Add information to your notifications
• Use Error notifications for other purposes
• Send custom notifications

Adding Information to your Notifications

You can add information to your error emails if there is something else you want to know about an error. You can do this by creating your own attributes and adding them to the error object passed into ApplicationError.notify.

For example, you might want to know the username of the person who broke your application:

try {
   this.will.cause.an.error();
} catch(e) {
   e.username = 'Brian';
   ApplicationError.notify(e);
}

Or maybe you noticed a lot of problems in IE, but since IE doesn't provide file name information in the error, you manually add it:

try {
   this.will.cause.an.error();
} catch(e) {
   e.fileName = 'myscript.js';
   ApplicationError.notify(e);
}

You'll see this information added to your email notifications.

Using Error for Other Purposes

Error is a JavaScript reporting service. It allows you to always be aware when something of consequence happens in your applications.

Beyond error notification, you can use Error to notify you when a user:

• clicks your new drag and drop widget
• types something in an important input box
• clicks an area of the page

These examples are trivial, but the point is you can use Error to notify you of anything that occurs in your JavaScript application. Error notification is simply the best application we've come up with so far.

Sending a Custom Notification

If you wish to use Error for a purpose other than error reporting, you can easily create your own notification functionality using ApplicationError's send method:

var notification = new ApplicationError({
   subject: "test",
   content: "someone clicked the new widget"
}); // 1
notification.save(); // 2

1. Creates a new ApplicationError instance. Set the subject and content attributes to define what the email will contain.
2. Sends a request to DamnIT's servers to email you the subject and message content.

Custom notification email

Security Concerns

Data Privacy

We store all your error information on the DamnIT servers. This includes snapshots of your page's HTML, which could contain things we shouldn't see, like bank account numbers. For apps with sensitive information, this could rightly be a cause of concern.

Error will shortly include an option to not save the HTML content on the DamnIT server. Until then, we promise we aren't evil and will never read your HTML.

JavaScript concerns

Error information is sent from your site's domain to damnit.jupiterit.com. The technique used to allow this cross domain communication involves loading a script tag and tacking the data on to the end of the url like this:

<script type="text/javascript" 
   src="https://damnit.jupiterit.com/errors.json?error%5Bsubj..."></script>

The server saves the objects and sends back JavaScript like this:

ApplicationError.createCallback({error: "https://damnit.jupiterit.com/errors/1833", 
   id: 1833, status: 201})

The obvious problem is we could technically send back any JavaScript here. To paint it in the most diabolical way possible, if your user's bank account number is on the page, the script could find it and send it to our servers.

In the short term future there are plans to replace the current method with Subspace, a method for secure cross-domain communication. Without this method, Error, Google Analytics, and any other remotely loaded JavaScript should never be used unless you trust the vendor completely. We promise we're not evil.

Related Learning

API
Low level documentation on the error methods.

Overview
What is Error, how does it work, and why should you use it.

Demo
See it in action. Then download the demo code and start using it yourself.