bugsnag-notification-plugins

Bugsnag Notification Plugin Creation Guide
==========================================

Bugsnag.com can notify you when errors happen in your applications.
We've created a plugin architecture so you can contribute notification
plugins for services you use.

Bugsnag captures errors in real-time from your web,
mobile and desktop applications, helping you to understand and resolve them
as fast as possible. Create a free account to start
capturing exceptions from your applications.

Steps to contributing
---------------------

- Fork the
bugsnag-notification-plugins project
on GitHub.

- Create a new folder in /plugins/ for your plugin

- Create the plugin file as index.js or index.coffee, see below for
instructions

- Create a config.json file describing the usage and configurable settings
for your plugin

- Add a 50x50 icon.png file representing your plugin

- If necessary, add any node module dependencies to the base package.json
file

- Make a pull request
from your fork to bugsnag/bugsnag-notification-plugins

Writing your plugin
-------------------

Notification plugins should be written in JavaScript or CoffeeScript and are
executed in a queue using our internal node.js application.

Plugins should extend the base NotificationPlugin class defined in
notification-plugin.js and override the receiveEvent function to perform
the notification. This method is fired when a new event is triggered.

It is easiest to write plugins using CoffeeScript, for example:

``coffeescript
NotificationPlugin = require "../../notification-plugin.js"
class MyPlugin extends NotificationPlugin
@receiveEvent = (config, event) ->
# Do the hard work here

module.exports = MyPlugin
`

If you prefer to write your plugin with plain old JavaScript, this is also
possible:

`javascript
var util = require("util");
var NotificationPlugin = require("../../notification-plugin.js")

function MyPlugin() {}
util.inherits(MyPlugin, NotificationPlugin);
MyPlugin.receiveEvent = function (config, event) {
// Do the hard work here
};

module.exports = MyPlugin;
`


Testing your plugin
-------------------

By extending the NotificationPlugin class, you'll be able to test your
plugin directly on the command line. In your new plugin directory
(plugins/your-plugin) run index.coffee directly:

> coffee index.coffee --option=value --anotherOption=something

Command line options represent the customizable per-project settings as
defined in your config.json file.

> Note: You should ensure you have run npm install in the top level
directory first, to install the dependencies for the project.


Event Format
------------
As well as passing the user's plugin configuration settings, we also pass you
an event object, which tells you the reason we triggered a notification.

`javascript
event: {

// Contains information about the account which has had an event
account: {
// The account name
name: "Account Name",

// The url for the Bugsnag dashboard of the account
url: "https://bugsnag.com/dashboard/"
},

// Contains information about the project which has had an event
project: {
// The project name
name: "Project Name",

// The url for the Bugsnag dashboard of the project
url: "https://bugsnag.com/dashboard/project-name"
},

// The reason the user is being notified by the notifier
trigger: {
// The identifier for the reason for notification
type: "firstException",

// The human readable form of the trigger. This can be used to start
// a sentence.
message: "New exception"
},

// The error that caused the notification (optional). Will not be present if
// the project has hit the rate limit.
error: {
// The class of exception that caused the error
exceptionClass: "NullPointerException",

// The message that came with the exception. This may not be present if
// the exception didn't generate one.
message: "Null cannot be dereferenced",

// The context that was active in the application when the error
// occurred. This could be which screen
// the user was using at the time, for example.
context: "BugsnagMainActivity",

// The application version
appVersion: "1.2.3",

// The release stage, will most often be production, or development.
releaseStage: "production",

// The number of times this exception has occurred (including this one)
occurrences: 1,

// When was the error first received. Will be a Date object.
firstReceived: new Date(),

// How many users have been affected. Could be 0 if there was no user
// associated with the error.
usersAffected: 1,

// The URL on bugsnag.com with the full details about this error
url: "https://bugsnag.com/errors/example",

// The stack trace for this error. An array of stack frames.
stacktrace: [{
// The file that this stack frame was in.
file: "BugsnagMainActivity.java",

// The line number of the stack frame, within the file.
lineNumber: 123,

// The method that was being executed.
method: "onCreate",

// Indicates that this stack fram was within the project. If the key
//is not present, it is assumed to be false.
inProject: true
}
...
]
}
}
`

HTTP request helper
-------------------

Since most notification plugins will use http for communication to external
services, we've provided a request helper function. This function provides
a superagent request object, which you can
read about here. Some examples:

`coffeescript
// Perform a HTTP GET request
@request
.get("http://someurl.com")
.send(params)
.end()


// Perform a normal HTTP POST request
@request
.post("http://someurl.com")
.send(params)
.type("form")
.end()


// Perform a HTTP POST request with a JSON body
@request
.post("http://someurl.com")
.send(params)
.end()
`


config.json format
------------------

Your plugin's config.json file describes to users how to use and configure
your plugin from their Bugsnag dashboard. The file must be a valid JSON file
and look similar to the following example:

`javascript
{
// The name of the plugin.
"name": "HipChat",

// A description of the action that will be performed.
"actions": {
"create": "Post to a HipChat chatroom",
},

// We trigger notifications when certain events occur in bugsnag (see the
// Event Format documentation above). To signal which triggers your plugin
// understands, set this to an array of trigger strings.
// eg. ["exception", "firstException"].
"supportedTriggers": ["firstException"],

// The type of plugin ("issueTracker", "communication", or "other")
"type": "communication",

// An array of fields to present to the user on the Bugsnag.com dashboard.
"fields": [{
// The name of the field. This is how you will reference the field in
// the configuration options that are passed to your notifier when it is
// run. Should be camelCase.
"name": "authToken",

// The label to display to the user for this field
"label": "Auth Token",

// A full description or hint for this field.
"description": "Your HipChat API auth token",

// The data type of this field, either string, select, password or boolean
// (optional, defaults to string)
"type": "boolean",

// An array of selectable values to present in the dropdown list
// (required when type == "select").
"allowedValues": ["yellow", "red", "green", "purple", "random"],

// A default value for this field (optional).
"defaultValue": "yellow"

// A link to documentation for this field - or a method of obtaining the value (optional)
// Can also contain other fields by using {fieldName} in the URL. In the following example
// applicationKey is another configuration option that is required for this URL.
"link": "https://trello.com/1/authorize?key={applicationKey}&name=Bugsnag"
}
...
]
}
``

Reporting Bugs or Feature Requests
----------------------------------

Please report any bugs or feature requests on the github issues page for this
project here: