This add-on is operated by Usersnap GmbH

Show, don't tell!


Last Updated: 07 May 2015

Table of Contents

Usersnap is an add-on to allow your users to give visual feedback in a comfortable and easy way: directly in their browser.

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=,] \
      [,] \
      [] \
      [--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: “”): 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,

$ heroku addons:create usersnap

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

After installing Usersnap the application should be configured to fully integrate with the add-on.

Local setup

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

Environment setup

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 export USERSNAP_APIKEY=value.

Use Foreman to configure, run and manage process types specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the USERSNAP_APIKEY values retrieved from heroku config to .env.

$ 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.


Usersnap can be integrated easily to any type of web page. The Usersnap support page offers an overview of how to integrate Usersnap in your site via a simple JavaScript snippet.

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", "")

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):

import os

<script type="text/javascript">
   (function() {
       var s = document.createElement('script');
       s.type = 'text/javascript';
       s.async = true;
       s.src = '//${os.environ.get('USERSNAP_APIKEY', '')}.js';
       var x = document.getElementsByTagName('head')[0];

This template can be included in the base template of your web page:

    <%include file="usersnap_snippet.mako"/>

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:

<script type="text/javascript">
   (function() {
       var s = document.createElement('script');
       s.type = 'text/javascript';
       s.async = true;
       s.src = '//<%= ENV["USERSNAP_APIKEY"] %>.js';
       var x = document.getElementsByTagName('head')[0];

Using with Java

To use Usersnap with Java you only have to access the environment variable USERSNAP_APIKEY and apply it to the Javascript snippet, similar to the Python usage. The snippet can be generated with the Usersnap Configurator.

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

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.

Use the 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)


All Usersnap support and runtime issues should be submitted via one of the Heroku Support channels. Any non-support related issues or product feedback is welcome at