This add-on is operated by Usersnap GmbH
Show, don't tell!
Last updated 19 August 2015
Table of Contents
Stop wasting time trying to understand unclear bug reports. Screenshots with comments from your users and testers delivered directly to your bug tracker help you to fix problems faster and speed up your development cycle. Understand the reported issues immediately by seeing it. Usersnap reduces expensive communication overhead significantly.
Usersnap integrates seamlessly with your existing Bug Tracker and causes no switching costs. Connect Usersnap with one of our supported tools and you will get issue reports in a familiar place. Learn more about all supported tools
Usersnap provides simple and yet powerful tools which allow anybody to report bugs and issues. All bug reports contain additional information such as the used browser and the source URL of the screenshot making it easy to reproduce the reported issues. Learn more about Usersnap’s features.
Provisioning the add-on
Usersnap can be attached to a Heroku application via the CLI:
$ heroku addons:create usersnap
A list of all plans available can be found here.
There are some additional, optional parameters to be passed in when adding:
$ heroku addons:create usersnap \ [--targeturls=http://your-website.com,http://your-website-alias.com] \ [--email@example.com,firstname.lastname@example.org] \ [--email@example.com] \ [--subject="[Usersnap] New Usersnap feedback"]
targeturls (comma-separated, optional - default: configured domains for heroku app): Specify the list of URLs which you intend to use Usersnap.
targetmails (comma-separated, optional - default: heroku account owner email): You can add one or more email addresses as recipients for Usersnap screenshots.
senderemail (optional - default: “firstname.lastname@example.org”): If you plan to deliver Usersnap reports to a ticketing system via email, you can change the sender address to your needs.
subject (optional - default: “[Usersnap] New Usersnap feedback”): Particularly useful if you want to create an email filter to organize your screenshots.
Here are some real world examples of how to add Usersnap to a Heroku application:
$ heroku addons:create usersnap $ heroku addons:create usersnap --email@example.com,firstname.lastname@example.org $ heroku addons:create usersnap --email@example.com
Once Usersnap has been added, a
USERSNAP_APIKEY setting will be available in the app configuration. This will contain the API key to be used in the Usersnap snippet. This can be confirmed using the
heroku config:get command.
$ heroku config:get USERSNAP_APIKEY YOUR-API-KEY-HERE
After installing Usersnap the application should be configured to fully integrate with the add-on.
Usersnap only works for publicly available (e.g. deployed) sites in general. If you want to use Usersnap in a local or internal development environment, please read following FAQ entry on usersnap.com.
After provisioning the add-on it’s necessary to locally replicate the config vars. Your development environment can operate with the service.
Though less portable it’s also possible to set local environment variables using
Use the Heroku Local command-line tool to configure, run and manage process types specified in your app’s Procfile. Heroku Local reads configuration variables from a
.env file. To view all of your app’s config vars, type
heroku config. Use the following command to add the USERSNAP_APIKEY values retrieved from heroku config to your
$ heroku config -s | grep USERSNAP_APIKEY >> .env $ more .env
Credentials and other sensitive configuration values should not be committed to source-control. If you are using Git, please exclude the .env file by:
echo .env >> .gitignore.
For more information, see the Heroku Local article.
On Heroku, one even doesn’t have to take care of the API key because it is accessible via an environment variable as mentioned above.
Provisioning Usersnap sets up a default email subscription for screenshots. To set up more advanced delivery methods just use the add-on’s administration interface. You can open it in the resources view of your app available from the heroku dashboard. One single click on the Usersnap add-on opens the configuration view.
Using with Python
The following code snippet shows how to retrieve the API key in an arbitrary python script.
import os print os.environ.get("USERSNAP_APIKEY", "") > YOUR-API-KEY-HERE
If one is using a template language like mako it is easy to include the Usersnap snippet with a single file and an include statement.
These are the contents of the usersnap_snippet.mako (You can customize the look and feel of the Usersnap snippet with the Usersnap Configurator):
This template can be included in the base template of your web page:
<html> <head> ... </head> <body> ... <%include file="usersnap_snippet.mako"/> </body> </html>
Using with Rails 3.x
To access the Usersnap API key in ruby just use the global environment variable ENV. The Usersnap snippet has to be embedded in the returned web page. See an example erb file in the next step. The snippet can be generated with the Usersnap Configurator.
Access the API key in ruby this way:
Import the Usersnap API key in your erb template this way:
Using with Java
Here is how the API key can be retrieved from the system environment:
String usersnap_apikey = System.getenv("USERSNAP_APIKEY");
For more information on the features available within the Usersnap dashboard please see the docs at http://usersnap.com/support/docs.
The Usersnap dashboard allows you to manage the URLs where the Usersnap button should be displayed. You are also able to choose the way screenshots are delivered to you (Email, JIRA, Basecamp, etc.). Another very useful tool is the snippet configurator which gives you the possibility to customize your Usersnap widget in a very comfortable way.
The dashboard can be accessed via the CLI:
$ heroku addons:open usersnap Opening usersnap for sharp-mountain-4005
or by visiting the Heroku apps dashboard and selecting the application in question. Select Usersnap from the Add-ons list.
Migrating between plans
Application owners should carefully manage the migration timing to ensure proper application function during the migration process.
heroku addons:upgrade command to migrate to a new plan.
$ heroku addons:upgrade usersnap:newplan -----> Upgrading usersnap:newplan to sharp-mountain-4005... done, v18 ($49/mo) Your plan has been updated to: usersnap:newplan
Removing the add-on
Usersnap can be removed via the CLI.
This will destroy all associated data and cannot be undone!
$ heroku addons:destroy usersnap -----> Removing usersnap from sharp-mountain-4005... done, v20 (free)