Creating Your Own Gadgets for Inspector

Think gadgets are the bees knees? You can create your own for Inspector. You host the gadget on your server, where the UserVoice app can access it over https.

The Request

Implement an endpoint that will serve the gadget HTML. It can be anything you’d like, so long as it’s SSL. For instance, you might pick:

https://pennycrm.com/gadgets/user.html

UserVoice will call this endpoint with a GET request containing the following parameters in its query string:

  • email: sally@jones.com (Email address of the user)
  • name: Sally (The current name we have on file for this person)
  • guid: null (Guid created for SSO, if one exists)
  • user_id: 123 (Same user id that you’ll find in our API)
  • external_ids:

When the gadget is displayed in the context of a ticket, key ticket attributes will be passed as well, under the ‘ticket’ key:

  • ticket:
    • id: 456 (Unique id of ticket)
    • ticket_number: 123 (Human-facing ticket identifier)
    • custom_fields: (Any custom fields set on the ticket)
      • MyField: my value
    • created_at: 2010-03-24T14:53:48-04:00
    • updated_at: 2010-03-28T12:00:48-04:00

In order to handle authentication and account-specific scoping, you might want to accept additional parameters that UserVoice admins supply.

You can choose anything you want, and name these parameters what you want. So you might pick account and api_token, for instance. These parameters will be merged into the default parameters, like this:

  • email: sally@jones.com
  • user_id: 123
  • name: Sally
  • account: posterous
  • api_key: 12345abcd (UV Admin entered this, and presumably got it from your website.)

UserVoice will then form all of this into a GET request:

GET https://pennycrm.com/gadgets/user.html?email=sally@jones.com&user_id=234&...

To which you reply with…

The Response

You need to render an HTML page.

For CSS, we recommend you use our CSS file. You can do whatever you want here, but obviously something that looks like it fits in is ideal. Our base gadget styles are here:

https://cdn.uservoice.com/packages/gadget.css

For JavaScript, you just include this javascript file just before the closing body tag:

https://cdn.uservoice.com/packages/gadget.js

This javascript communicates via postMessage to the parent UserVoice window what the height of your gadget is and whether it has data. If you don’t include this javascript file, your gadget will not show up in UserVoice.

If your gadget has no data to display, for instance if the user can’t be found in your CRM, then the best practice is to hide the gadget completely. You can do this simply by including this snippet before you include the gadget.js file:

1
2
3
<script type="text/javascript">
  window.gadgetNoData = true;
</script>

Here is a sample HTML document that you might render. It uses ERB and assumes you have a variable named ‘data’:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
<!DOCTYPE html>
<html>
  <head>
    <title>Title your gadget</title>
    <link href="https://cdn.uservoice.com/packages/gadget.css"
      media="all" rel="stylesheet" type="text/css" />
  </head>
  <body>
    <% if data %>
      <table>
        <tr>
          <th>Field</th>
          <td><%= data %></td>
        </tr>
      </table>
    <% else %>
      <script type="text/javascript">
        window.gadgetNoData = true;
      </script>
    <% end %>
    <script src="https://cdn.uservoice.com/packages/gadget.js"
      type="text/javascript"></script>
  </body>
</html>

Create a One-Off Gadget

Let’s say you run a website called clawstores.com. Most likely, you have a database and a secret admin area you can access to view who signed up on your site. You’d like a gadget that can pull in customer data into UserVoice. Obviously, this gadget only applies to you – you don’t want any other UserVoice account access to it!

This situation is fully supported. You’ll want to head on over to your UserVoice account’s admin area, click Settings, and go into Integrations. Add a custom gadget:

Then enter your gadget URL:

Your URL might be something like:

https://clawstores.com/secret_hideout/gadgets/user.html?secret_token=12345

UserVoice will then call your endpoint, including the parameters (such as email and user_id) listed above in the previous section.

It should be noted that you can use this method to test out a broader integration.

Creating A Gadget Anyone Can Use

You want to implement a gadget and distribute it to others. Maybe you run a CRM SaaS app like pennycrm.com, or maybe you’re a 3rd party and you want to implement a gadget on their behalf. You want an admin on UserVoice.com to go here to add your gadget:

And once it has been enabled, you want it to show up here:

There are two steps to this process. First, implement an endpoint on your server according to our gadget specifications. Second, tell us about it and we can work with you to add it into our UI for others to use.

Tell Us

Now that you’ve gotten your gadget working, you want anyone to be able to access it. Please email us at support@uservoice.com and we’ll work with you on getting it added into the UserVoice UI so anyone can add it!

Conclusion

So, you’ve learned how to pull in data from your personal system and from popular 3rd party systems. Please let us know if you create generic gadgets that others might find useful!