Surveys (Polls)
A poll allows you to ask a question to a channel. Channel participants can choose from the answers you specify, and the results can be viewed by everyone in the channel, or optionally only yourself. You can allow voters to select only one answer, or allow them to select multiple answers.
Here is a sample of what a complete poll implementation can look like:
Create Poll
The following example creates a poll, MMXPoll, for participants' favorite color.
// Create the poll
MMXPoll newPoll = new MMXPoll.Builder().name(name).question(question)
.allowMultiChoice(allowMultiChoices)
.hideResultsFromOthers(false)
.option("Red")
.option("Black")
.option("Orange")
.option(new MMXPollOption("Blue"))
.build();
// Publish the poll to a channel
MMXChannel chatChannel = ...
newPoll.publish(chatChannel, new MMX.OnFinishedListener<MMXMessage>() {
@Override public void onSuccess(MMXMessage result) {
}
@Override public void onFailure(MMX.FailureCode code, Throwable ex) {
publishPollResult.failed(new FailureDescription(code, ex));
}
});
Listen for Incoming Poll Identifiers
Participants of the channel can listen for incoming poll identifiers, which contain a pollId we can use to get the poll object from the server.
messageListener = new MMX.EventListener() {
public boolean onMessageReceived(final MMXMessage messageReceived) {
if (null != messageReceived.getContentType()) {
if (messageReceived.getContentType().endsWith(MMXPoll.MMXPollIdentifier.TYPE)) {
MMXPollIdentifier pollIdentifier = (MMXPollIdentifier) messageReceived.getPayload();
} else {
...
}
}
return false;
}
...
}
MMX.registerListener(messageListener);
Get poll object from server using a pollId (poll identifier).
String pollID = ...;
MMXPoll.get(pollID, new MMX.OnFinishedListener<MMXPoll>() {
@Override public void onSuccess(MMXPoll result) {
}
@Override public void onFailure(MMX.FailureCode code, Throwable ex) {
}
});
A poll object contains all the information needed to display a poll in your user interface.
String name = myPoll.getName(); // A user-friendly name of the poll.
String question = myPoll.getQuestion(); // The question this poll should answer.
List<MMXPollOption> options = myPoll.getOptions(); // A list of the available poll selection options.
boolean allowMultiChoice = myPoll.isAllowMultiChoices(); // If enabled, users can select more than one option.
boolean hideResultsFromOthers = myPoll.shouldHideResultsFromOthers(); // If enabled, participants cannot obtain results from the poll, and will not receive {MMXPollAnswer} when a participant chooses a poll option. The poll creator can still obtain results using {PollWithID or PollFromMessage} or poll.refreshResults.
Map<String, String> extras = myPoll.getExtras(); // A user-defined object used to store arbitrary data will can accessed from a {Max.Poll} instance.
Date endDate = myPoll.getEndDate(); // The date this poll ends. After a poll ends, users can no longer select options.
Poll Options
Participants can choose one or more options.
// create an array of the PollOptions chosen by the current user.
MMXPollOption option1 = myPoll.getOptions().get(0);
MMXPollOption option2 = myPoll.getOptions().get(2);
List<MMXPollOption> selectedOptions = Arrays.asList(option1, option2);
myPoll.choose(selectedOptions, new MMX.OnFinishedListener<MMXMessage>() {
@Override public void onSuccess(MMXMessage result) {
}
@Override public void onFailure(MMX.FailureCode code, Throwable ex) {
}
});
Listen for Incoming Poll Answers
Channel participants listening for the incoming the PollAnswer can view them in the user interface.
messageListener = new MMX.EventListener() {
public boolean onMessageReceived(final MMXMessage messageReceived) {
if (null != messageReceived.getContentType()) {
if(messageReceived.getContentType().endsWith(MMXPoll.MMXPollAnswer.TYPE)) {
MMXPollAnswer pollAnswer = (MMXPollAnswer) messageReceived.getPayload();
String pollID = pollAnswer.getPollId();
String pollName = pollAnswer.getName(); // poll name
String pollQuestion = pollAnswer.getQuestion(); // poll question
List<MMXPollOption> pollSelections = pollAnswer.getCurrentSelection(); // the currentSelection property is a list of PollOption chosen by the sender
}
}
return false;
}
...
}
MMX.registerListener(messageListener);
If the current user has voted in the poll, the selected PollOption(s) can be obtained from the poll object.
MMXPoll myPoll = ...
List<MMXPollOption> myChoices = myPoll.getMyVotes(); // a list of PollOption selected by the current user
Obtain Poll Results
There are several ways to obtain poll results.
Get the latest poll object from the server using a pollId:
String pollID = ...
MMXPoll.get(pollID, new MMX.OnFinishedListener<MMXPoll>() {
@Override public void onSuccess(MMXPoll result) {
// get the number of votes casts towards each option
Long option1VoteCount = result.getOptions().get(0).getCount(); // returns the number of votes for option 1
String option1VoteText = result.getOptions().get(0).getText(); // returns the value of option 1
Long option2VoteCount = result.getOptions().get(1).getCount(); // returns the number of votes for option 2
String option2VoteText = result.getOptions().get(1).getText(); // returns the value of option 2
}
@Override public void onFailure(MMX.FailureCode code, Throwable ex) {
}
});
Refresh existing poll object results:
MMXPoll myPoll = ...;
myPoll.refreshResults(new MMXChannel.OnFinishedListener<Void>() {
@Override public void onSuccess(MMXPoll result) {
Long option1VoteCount = result.getOptions().get(0).getCount(); // returns the number of votes for option 1
String option1VoteText = result.getOptions().get(0).getText(); // returns the value of option 1
Long option2VoteCount = result.getOptions().get(1).getCount(); // returns the number of votes for option 2
String option2VoteText = result.getOptions().get(1).getText(); // returns the value of option 2
}
@Override public void onFailure(MMXChannel.FailureCode code, Throwable ex) {
}
});
Use a listener to update existing poll objects results. This method saves a round-trip to the server, updating the poll results dynamically when a PollAnswer is received.
MMXPollAnswer pollAnswer = ...
myPoll.refreshResults(pollAnswer);
If hideResultsFromOthers was selected during poll creation, no poll answers will be sent out. Only the poll creator can obtain the results of the poll. In this case, the poll creator should check for results periodically using poll.refreshResults().
final MMXPoll myPoll = ...
myPoll.refreshResults(new MMXChannel.OnFinishedListener<Void>() {
@Override public void onSuccess(Void result) {
Long option1VoteCount = myPoll.getOptions().get(0).getCount(); // returns the number of votes for option 1
String option1VoteText = myPoll.getOptions().get(0).getText(); // returns the value of option 1
Long option2VoteCount = myPoll.getOptions().get(1).getCount(); // returns the number of votes for option 2
String option2VoteText = myPoll.getOptions().get(1).getText(); // returns the value of option 2
}
@Override public void onFailure(MMXChannel.FailureCode code, Throwable ex) {
}
});
