Simple, powerful, declarative integrations for popular third-party services.
Crashlytics users have oft-requested that we integrate with their favorite ticket-tracker or notification service. Given the sheer volume of awesome services out there, it was a daunting goal to try to satisfy everyone. Instead, we sought a more scalable approach: open-sourced, event-driven integrations that anyone can add to!
GitHub leads the way in this space with their Github Services implementation and rather than reinvent the wheel, we thought it better to enhance it - and leverage an architecture that people are familiar with.
We've started with GitHub's approach and simplified and streamlined the implementation to fit better within Crashlytics' backend architecture and permit more customization of the front-end UI. As with the original, our additions are available under the Logical Awesome license and we're excited to see who takes this even further.
See CONTRIBUTING.md
Services must inherit from Service:Base and begin by declaring their human-readable title and a url to their logo. Following these attributes, the service should declare its Schema and UI (see below).
The Service is responsible for acting in response to events it receives and for providing a facility to verify that it has been configured correctly.
class Service::Foo < Service::Base
title "Display Title"
# input type methods take an identifier and optional options hash
string :url # [, :label => "label text", :placeholder => "https://example.com/foo/bar" ]
password :api_key # [, :label => "label text"]
checkbox :checkbox_1 # [, :label => "" ]
# construct your pages and make use of inputs defined above
page "Title", [:url, :api_key]
page "Two", [:checkbox_1]
# Receives a config hash containing :identifier => value pairs for each input field
# and a payload which for impact change events is a hash of data about the issue.
# Returns a hash with data in it needed to later accesses any resources created
# on the service or :no_resource if there wasn't a resource created.
#
# For unexpected errors, it's recommended to raise here and let the integration
# harness handle the error. `nil` is not a recommended return value here as it is
# just handled as a very generic error. On failure, it is preferable to raise a
# descriptive exception, and on success without any data to return it is preferred
# to return :no_resource
def receive_issue_impact_change(config, issue)
{ :service_name_resource_id => 12345 } # or :no_resource
end
# Receives a config hash containing :identifier => value pairs for each input field.
# Returns an array 2-tuple containing a boolean and a response message.
# The boolean should be true if the data in the config was verified, otherwise false.
#
# You can also raise errors out of this method, but the response we return to users
# will be very generic. You should make every effort to handle known error scenarios
# by rescuing from an exception and returning an appropriate [false, '<explanation>']
# that will be played back to the user trying to set up an integration.
def receive_verification(config, _)
# on success
[true, "Successfully integrated!"]
end
endThe schema is defined in a declarative manner with Ruby class methods for each input type. Specify the unique identifer for the field and an optional options Hash. If no pages are declared, all the inputs will be put on one page.
For a better, friendlier UI, you can separate these fields into pages. If one or more pages are declared, each input identifier must be included on one page or it will be ignored. Pages will be shown in the order they are declared in the schema. Labels can include span, p, br, and anchor html tags.
The settings UI will automatically put a Next button on all pages except for the last. On the last page there will be a Verify button which will take the user to a page showing more options for the service or back to the first page if the verification failed.
A working service must respond to two methods: receive_issue_impact_change and receive_verification.
When a user is configuring a service, receive_verification will be called and passed in their configuration data. This method should confirm that the data is correct (eg. authenticate with the service) and return a 2-tuple with a boolean and a message.
When an issue's impact reaches the threshold set by the user, receive_issue_impact_change will be called with a hash of configuration data and a hash of data about the issue. Check out the other service implementations for examples of how to use this data.
Example issue hash:
{
:title => 'issue title',
:method => 'method name',
:impact_level => 1,
:impacted_devices_count => 1,
:crashes_count => 1,
:app => {
:name => 'app name',
:bundle_identifier => 'foo.bar.baz',
:platform => 'ios'
},
:url => "http://foo.com/bar"
}
In a service, use http_get and http_put to make http requests. See lib/service/http.rb for documentation. We strongly recommend making all network requests under SSL. If you need to parse JSON, the standard ruby JSON module is available. For XML, the Nokogiri library is available.
Services run on sandboxed servers under Ruby2.1.4. All configuration data entered by users is encrypted at rest using AES-256.