suggestions

15
Mar
2014

[Update 3] UserVoice WP8 library for user features

It is done. I made my first library for Windows Phone 8. This blog post is about why I did it and how to use it.

Update: I changed some method names of the library to make it easier to use the library. I updated the code in this post to reflect those changes.

Update 2: I added support to load more pages with clients. On top, I also added my EmojiDetector class, as the UserVoice API does not support Emojis. Check the code below.

Update 3: Now the library supports comments on suggestions and mark as helpful for knowledge base items.

Why UserVoice?

We indie developers have a big problem: We do not have a support team to explain our users how to use our apps or how to solve certain problems/issues. Which leads to our next problem: users are customers. Customers want to be satisfied. It is our job to do this with our apps by providing them a high level user experience and feature rich apps. Often users don’t go the extra mile to send us an email to tell us what is wrong. Or they plan it, but forget about it. Or even worse: they get annoyed and uninstall our apps.

As some of you know, I am working at the hardware support team of a German phone carrier. Over the years, I learned how important it is to listen to customers, pick up their ideas and wishes  and work to get them done if possible. And if it is not possible, you need to tell them that – even that is an important part of customer service!

Many of us have set up a twitter account, a separate mail address, maybe an extra online form to catch all requests from users up. But users tend to not use them for one reason: they are not integrated in our apps. So I spend some time “googling with Bing” (Thanks to @robwirving for that awesome phrase!) on possible solutions.

Uservoice as the best value if using a free subscription, and they have an API that we can use (see also this post on how to get started with uservoice). I made it a very slim library and concentrated on the features we really need in our app on the user side.

The Library!

You can get the library easily via NuGet directly into your app. Just add this package to your app’s packages list:

uservoice_lib_nuget

The library also needs RestSharp, which gets automatically added to your project if you install the library.

After you installed it, you need to declare some variables that we need over and over again while using the library:

Urls.subDomain = "<your subdomain>";
Urls.oAuthCallBackUri = "<your callback url>";
Tokens.ConsumerKey = "<your ConsumerKey>";
Tokens.ConsumerSecret = "<your ConsumerSecret>";

You can get this values out of Settings/Integrations in your UserVoice account.

Additionally, you should save these Tokens to not ask the user for login again and again.

Tokens.AccessToken
Tokens.AccessTokenSecret  
Tokens.OwnerAccessToken
Tokens.OwnerAccessTokenSecret

Another important class you should be aware of  is the RequestParamaters class:

Screenshot (309)

It contains the needed variables for all requests, and you can easily use them to save them for TombStoning or anything else you want to save them.

Let’s have a look at the possible requests:

  • Knowledge Base:
KnowledgeBase kb = new KnowledgeBase();`   
//load complete knowledge base  
UservoiceRequests.KnowledgeBase = await kb.getAll();  
//load specific page in your knowledge base
int page = 2;
 UservoiceRequests.KnowledgeBase = await kb.getAll(page);
//load specific topic 
UservoiceRequests.KnowledgeBaseTopic = await kb.getTopic(RequestParameters.topicId);
//load specific page in topic
int page = 2;
UservoiceRequests.KnowledgeBaseTopic = await kb.getTopic(RequestParameters.topicId, page);
//mark article as helpful
var ratingResponse = await kb.markHelpful(RequestParamaeters.articleId);
  •  Suggestions:
Suggestion suggestion = new Suggestion();  
//load all suggestions  
UservoiceRequests.allSuggestions = await suggestion.getAll(RequestParameters.forumId);  
//load specific page in all suggestions
int page = 2;
UservoiceRequests.allSuggestions = await suggestion.getAll(RequestParameters.forumId, page); 
//vote on a suggestion 
UservoiceRequests.voteForSuggestion = await suggestion.vote(RequestParameters.forumId, RequestParameters.suggestionId, RequestParameters.vote);  
//submit new suggestion  
UservoiceRequests.postSuggestion = await suggestion.create(RequestParameters.forumId, RequestParameters.newSuggestionTitle, RequestParameters.newSuggestionText, RequestParameters.newSuggestionReferrer, RequestParameters.newSuggestionVotes); 
//search suggestions  
UservoiceRequests.searchSuggestion = await suggestion.search(RequestParameters.suggestionsSearchQuery);
//get all comments for suggestion:
UservoiceRequests.allCommentsForSuggestion = await suggestion.getComments(RequestParameters.forumId, RequestParameters.suggestionId);
//submit a new comment on suggestion:
UservoiceRequests.postCommentOnSuggestion = await suggestion.comment(RequestParameters.forumId, RequestParameters.suggestionId, RequestParameters.newCommentText);
  •  User data:
User user = new User();  
UservoiceRequests.User = await user.getUser();
  •  Tickets:
//Tickets are not associated with the user from the API side. However, you are able to show all tickets from a user with this:  
ticket = new Ticket();  
UservoiceRequests.AllTicketsFromUser = await ticket.getAll(RequestParameters.userMail); 
//load specific page in all tickets:
int page = 2;
UservoiceRequests.AllTicketsFromUser = await ticket.getAll(RequestParameters.userMail, page);
//submit a new ticket on behalf of the user
UservoiceRequests.newTicket = await ticket.create(RequestParameters.TicketSubject, RequestParameters.TicketMessage);

As you can see, all requests are async.

You don’t need explicitly authenticate a user, because the library is built to detect this automatically. If an authenticated user is required, the user will be redirected to the authentication page of UserVoice.

In the current version, you will need to manual send the request again after the user is authenticated, but I will update the library to make also this automatically soon.

  • EmojiDetector
  string text = "here would be the string from your textboxes that contain emojis";

            //check if Emojis are in text:
            if (EmojiDetector.HasEmojis(text) == true)
            {
                //your code here
            }
            //remove Emojis in text:
            text = EmojiDetector.RemoveEmojis(text);

The UserVoice API does not support Emojis, that’s why I wrote this little helper that you can easily use to remove them with only one line of code or to display a message to your users.

One last point: I don’t use RestSharp’s serializer – all request return the corresponding JSON string. This way, everyone of you can use the serializer of choice (I absolutely recommend JSON.net, though).

Please consider the current version as beta release, and report any issues with that to me via Twitter or mail.

And now enjoy my library & happy coding!

 

 

Posted by msicc in Archive, 9 comments
20
Jan
2014

How to integrate the feedback forum of uservoice into your Windows Phone app

As I described in my first blog post about uservoice, uservoice has a feedback forum where users are able to submit and vote for ideas.

This post is about how to get those ideas into your app. On the API side, the ideas are called suggestions. Now that we know how to authenticate our users for the API, we are able to get a list of suggestions into our app:

        public void GetSuggestions()
        {

            string suggestionsPath = "api/v1/forums//suggestions.json";
            var client = new RestClient(BaseUrl)
            {
                Authenticator = OAuth1Authenticator.ForProtectedResource(ConsumerKey, ConsumerSecret, AccessToken, AccessTokenSecret)
            };

            var request = new RestRequest(suggestionsPath, Method.GET);
            var response = client.ExecuteAsync(request, HandleGetSuggestionResponse);
        }

This is pretty straight forward. We are using the oAuth1Authenticator with our saved tokens as parameter to call the suggestions endpoint of the uservoice API. The result is a JSON string that holds all suggestions as a list.

In our response handler, we are able to deserialize our List of suggestions (best with JSON.net):

private void HandleGetSuggestionResponse(IRestResponse restResponse)
        {
            var response = restResponse;

            var suggestionslist = JsonConvert.DeserializeObject<SuggestionsDataClass.SuggestionsData>(response.Content);
            suggestionsListBox.ItemsSource = suggestionslist.suggestions;
        }

To get the SuggestionsDataClass items, just go to json2csharp.com and pass in the json string we received with response.Content or download it from here: SuggestionsDataClass.

Now let’s have a look on how to submit a new idea on behalf of our user. To submit an idea, we are using the POST method after we authenticated our user again with the uservoice API:

public void PostSuggestion()
        {
            string suggestionsPath = "api/v1/forums//suggestions.json";
            var client = new RestClient(BaseUrl)
            {
                Authenticator = OAuth1Authenticator.ForProtectedResource(ConsumerKey, ConsumerSecret, AccessToken, AccessTokenSecret)
            };

            var request = new RestRequest(suggestionsPath, Method.POST);
            request.AddHeader("Accept", "application/json");
            request.Parameters.Clear();
            request.RequestFormat = DataFormat.Json;

            var newSuggestion = new SuggestionsDataClass.Suggestion();
            newSuggestion.title = "test suggestion number 2 from app development";
            newSuggestion.text = "please ignore this suggestion as we are testing integration of ideas into our apps";
            newSuggestion.vote_count = 3;

            request.AddParameter("suggestion[title]", newSuggestion.title);
            request.AddParameter("suggestion[text]", newSuggestion.text);
            request.AddParameter("suggestion[votes]", newSuggestion.vote_count);
            request.AddParameter("suggestion[referrer]", "uservoice test app");            

            var response = client.ExecuteAsync(request, HandlePostSuggestionResponse);

        }

This call is a bit different from the previous one. We need to pass the idea data to as parameters to our request. The parameter “suggestion[title]” is the main one and always required. As you can see, “suggestion[text]” and “suggestion[votes]” are additional parameters that make the idea complete. All other date is generated by the uservoice server (like posted at, connect to the user who posted that, etc..). The parameter “suggestion[referrer]” is only visible in our admin console and can help you to track from where the suggestion was submitted.

In our response handler, we are receiving a complete set of suggestion data as a JSON string that we can use display to our users and enable sharing of this idea for example:

        private void HandlePostSuggestionResponse(IRestResponse restResponse)
        {
            var response = restResponse;

            //tbd: do something with the result (e.g. checking response.StatusCode)
        }

 

Screenshot (305)

The last important point I want to show you is how to let a user vote for an idea.

        public void VoteOnSuggestion()
        {
            string postUserVotesPath = "/api/v1/forums//suggestions/{0}/votes.json";
            string suggestionId = "";
            var client = new RestClient(BaseUrl)
            {
                Authenticator = OAuth1Authenticator.ForProtectedResource(ConsumerKey, ConsumerSecret, AccessToken, AccessTokenSecret)
            };

            var request = new RestRequest(string.Format(postUserVotesPath, suggestionId), Method.POST);
            request.AddHeader("Accept", "application/json");
            request.Parameters.Clear();
            request.RequestFormat = DataFormat.Json;

            request.AddParameter("to", 3);

            var response = client.ExecuteAsync(request, HandleVotingResponse);

        }

Of course we need to authenticate our user again. We need to pass the suggestion id to the request path (which is part of the Suggestion class). This call accepts only one parameter (“to”). The value can be between 1 and 3 (tip: only offer this three options from your code already to avoid erroneous responses).

The response handler returns the suggestion’s JSON string the user voted on again:

        private void HandleVotingResponse(IRestResponse restResponse)
        {
            var response = restResponse;

            //tbd: do something with the result (e.g. checking response.StatusCode)
        }

This was all about how to integrate the feedback forum of your uservoice account into your app. As always, I hope this will be useful for some of you.

If you want to explore which additional endpoints uservoice has, you are just a click away: https://developer.uservoice.com/docs/api/reference/

Happy coding, everyone!

Posted by msicc in Archive, 0 comments