UserVoice Java SDK

UserVoice SDK is now packaged in a Java library (library & the source). This document illustrates its usage with installation instructions and a few examples just to get you quickly started.

Install the library

Place the following in your pom.xml (when using Maven) or use the corresponding syntax of your package manager:

1
2
3
4
5

<dependency>
  <groupId>com.uservoice</groupId>
  <artifactId>uservoice-java</artifactId>
  <version>0.0.2</version>
</dependency>

Remember to check the latest version!

Then fetch the package with all the dependencies by running e.g:

1

mvn clean install

Now you should be good to go!

Creating a new API client

For creating a new API client you need to do a few things. First, get your API KEY and API SECRET from UserVoice Admin Console and pass them as parameters to the client like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

package com.uservoice;

import java.util.HashMap;
import java.util.Map;

import com.uservoice.Client;

import net.sf.json.JSONObject;

public class Example {
    public static final String SUBDOMAIN_NAME = "uservoice";
    public static final String API_KEY = "oQt2BaunWNuainc8BvZpAm";
    public static final String API_SECRET = "3yQMSoXBpAwuK3nYHR0wpY6opE341inL9a2HynGF2";
    public static final String SSO_KEY = "982c88f2df72572859e8e23423eg87ed";
    public static final String CALLBACK = "http://localhost:4567/";

    public static void main(String[] args) {
        Client client = new Client(SUBDOMAIN_NAME, API_KEY, API_SECRET);

        // ...
    }
}

Now we have an API client that we can use to connect Helpdesk API.

Post a new ticket

Making requests using the client follow the format client.method(path, params). In the first example we post a new ticket, which is possible if you have the helpdesk service.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// Post a new ticket to your helpdesk from sidson@example.com
JSONObject question = client.post("/api/v1/tickets.json", new HashMap<String, Object>() { {
    put("email", "sidson@example.com");
    put("ticket", new HashMap<String, Object>() { {
        put("state", "open");
        put("subject", "Java SDK");
        put("message", "I'm wondering if you would have any OAuth example for Java?\n\n" +
                       "Thanks,\n\nSidson");
    } });
} }).getJSONObject("ticket");

System.out.println(question.getJSONObject("contact").getString("name") +
                   " posted ticket: " +
                   question.getString("url"));
// Prints: sidson posted ticket: http://.....

Post a suggestion using an access token

Acting on behalf of the user lets you leave out the email parameter from the previous example as well as access to user-requiring API calls. In the following example we post a new suggestion in your first forum. You need to have the feedback service for this example.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// Login as man.with.only.answers@example.com and retrieve an access token
Client accessToken = client.loginAs("man.with.only.answers@example.com");

// Get the first forum id for the example which accessToken has access to
Integer forumId = accessToken.getCollection("/api/v1/forums?sort=newest", 1).get(0).getInt("id");

// Post the suggestion using the access token
JSONObject suggestion = accessToken.post("/api/v1/forums/" + forumId + "/suggestions",
        new HashMap<String, Object>() { {
    put("suggestion", new HashMap<String, Object>() { {
        put("title", "Color the left navbar to green");
    } });
} }).getJSONObject("suggestion");

JSONObject user = accessToken.get("/api/v1/users/current").getJSONObject("user");

System.out.println(user.getString("name") + " created suggestion: " + suggestion.getString("url"));
// Prints: Anonymous created suggestion: http://.....

Get the access token of the account owner and post responses

To respond to the ticket, you need to log in as an admin (or owner).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// This logs in as the first owner of the account
Client owner = client.loginAsOwner();

final String contactName = question.getJSONObject("contact").getString("name");
Integer questionid = question.getInt("id");
JSONObject posted = owner.post("/api/v1/tickets/" + questionid + "/ticket_messages",
        new HashMap<String, Object>() { {
    put("ticket_message", new HashMap<String, Object>() { {
        put("text", "Hi " + contactName.substring(0,1).toUpperCase() + contactName.substring(1) +
                    "!\n\nWe sure do! See the installation instructions and a few example API " +
                    "calls here: http://developer.uservoice.com/docs/api/php-sdk\n\n" +
                    "Best regards,\n\nRaimo Tuisku\nDeveloper");
    } });
} }).getJSONObject("ticket");
JSONObject sender = posted.getJSONArray("messages").getJSONObject(0).getJSONObject("sender");
System.out.println(sender.getString("name") +
                   " posted response to: " +
                   posted.getString("url"));
// Prints: Raimo posted response to: http://.....·

Getting a list of suggestions

You maybe noticed the use of getCollection when getting the first forum ID. Whenever you need to fetch paginated results (like all suggestions), you can use our lazy-loading collection.

1
2
3
4
5
6
7
8
9
10

// Creates a lazy-loading collection object but makes no requests to the API yet.
com.uservoice.Collection suggestions = client.getCollection("/api/v1/suggestions?sort=newest");

// Loads the first page (at most 100 records) of suggestions and reads the count.
System.out.println("Total suggestions: " + suggestions.size());

// Loops through all the suggestions and loads new pages as necessary.
for (JSONObject suggestion : suggestions) {
    System.out.println(suggestion.getString("title") + ": " + suggestion.getString("url"));
}

Log your users into your Widget using SSO

If your site has both authenticated users and the UserVoice Widget installed, you should definitely pass the email of your logged-in user to the UserVoice Widget so that users don’t have to type it again in your site.

Generating an SSO token should be done on the server side, as you should never reveal your API SECRET to anyone. Here’s how you do it:

1
2
3
4
5

String currentSSOToken() {
    return com.uservoice.SSO.generateToken(SUBDOMAIN_NAME, SSO_KEY, new HashMap<String, Object>() { {
        put("email", currentUser().getEmail());
    } }, 300); // Leaving this out sets the expiry time to 5 minutes = 300 seconds.
}

Now you can pass the SSO token to the UserVoice Widget JavaScript snippet. Make sure the aforementioned method currentSSOToken() can be called from there.

1
2
3
4
5
6
7
8
9
10
11

<script type="text/javascript">
  var uvOptions = {
    params: { sso: '<?= currentSSOToken(); ?>' }
  };
  (function() {
    var uv = document.createElement('script'); uv.type = 'text/javascript'; uv.async = true;
    uv.src = ('https:' == document.location.protocol ? 'https://' : 'http://') +
      'widget.uservoice.com/yourwidgetcodetobehere.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(uv, s);
  })();
</script>

That’s all! Now your users should be able to leave feedback and post tickets right away.

Note: If you are using Scala and don’t want to include all the dependencies of the full-blown UserVoice SDK, try this SSO example.

Associating your users with their UserVoice profiles

Connecting your users with their UserVoice profiles is possible by following a procedure called 3-Legged OAuth. The steps required to do this are explained below.

1. Provide a link or redirect user to /authorize from system X.

When you want to connect your current user to his or her UserVoice profile, redirect the browser to the authorization url like this:

1
2

// Redirect user to the UserVoice authorization dialog in Spring MVC v3.
return "redirect:" + client.AuthorizeURL();

Providing a direct link is another way to do the trick:

1

<a href="<?= client.AuthorizeURL(); ?>">Connect UserVoice</a>

2. User is asked to log in and give X permission to access information in UserVoice.

The authorization dialog will look like this:

3. UserVoice redirects user back to system X and passes an oauth verifier

UserVoice will pass a verification code back to your system, which you can use to request an access token for the user, so you know which profile in UserVoice is owned by your currently logged-in user.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

// Getting oauth verifier as a GET parameter
String verifier = request.getParameter("oauth_verifier").toString();

if (verifier.length > 0) {
    try {
        // Get access token for the user
        var accessToken = client.loginWithVerifier(verifier);


        // Persist the access token in the database for later use
        JSONObject user = currentUser(); // currentUser() returns a persistable object
        user.uservoiceToken = accessToken.getToken();
        user.uservoiceSecret = accessToken.getSecret();
        user.save();
    } catch (com.uservoice.Unauthorized ua) {
        // false/old verifier, present error
    }
}
return "redirect:/";

4. System X makes API calls to UserVoice using the access token.

Now whenever you need to, you can make calls on behalf of the user whom you verified. Just use the access token you got in exchange for the verifier.

1
2
3
4
5
6
7
8
9
10
11

try {
    // Use the previously saved access token. Makes zero requests!
    var accessToken = client.loginWithAccessToken(currentUser().uservoiceToken,
                                                  currentUser().uservoiceSecret);
    // Get current user
    var user = accessToken.get("/api/v1/users/current.json")["user"];
    System.out.println(user["email"]);
    // Prints: man.with.only.answers@example.com
} catch (com.uservoice.Unauthorized ua) {
    // Tried to do something unauthorized
}

Raimo Tuisku (twitter: @raimo_t)

Didn’t find what you’re looking for?

Check out the UserVoice Help Center for more documentation.

Explore the Help Center