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:

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:

123

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

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:

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!