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.

MMXChannel *myChannel; //=... // create a poll MMXPoll *poll = [MMXPoll createPoll:@"Favorite Color" question:@"What is your favorite color?" options:@[@"Red", @"Blue", @"Green"] hideResultsFromOthers: NO endDate:nil extras:@{@"MyKey" : @"Optional Dictionary"} allowMultiChoice:YES]; [poll publishWithChannel:myChannel success:^(MMXMessage * message) { //Poll Created! } failure:^(NSError * error) { //NSLog(@"%@", error.localizedDescription); }];

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.

Get poll object from server using a pollId (poll identifier).

NSString *pollID; //=...; [MMXPoll pollWithID:pollID success:^(MMXPoll * poll) { // do something with poll object } failure:^(NSError * error) { //NSLog(@"%@", error.localizedDescription); }];

Display Poll Information

A poll object contains all the information needed to display a poll in your user interface.

NSString *name = myPoll.name; // A user-friendly name of the poll. NSString *question = myPoll.question; // The question this poll should answer. NSArray <MMXPollOption *>*options = myPoll.options; // A list of the available poll selection options. BOOL allowMultiChoice = myPoll.allowMultiChoice; // If enabled, users can select more than one option. BOOL hideResultsFromOthers = myPoll.hideResultsFromOthers; // 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. NSDictionary <NSString *, NSString *>*extras = myPoll.extras; // A user-defined object used to store arbitrary data will can accessed from a {Max.Poll} instance. NSDate * endDate = myPoll.endDate; // 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.options[0]; MMXPollOption *option2 = myPoll.options[2]; NSArray <MMXPollOption *>*selectedOptions = @[option1, option2]; [myPoll choose:selectedOptions success:^(MMXMessage * message) { //Options chosen. Message will be sent if hideResultsFromOthers == false } failure:^(NSError * error) { //NSLog(@"%@", error.localizedDescription); }];

Listen for Incoming Poll Answers

Channel participants listening for incoming PollAnswers can view them in the user interface.

- (void)didReceiveMessage:(NSNotification *)notification { NSDictionary *tmp = notification.userInfo; MMXMessage *mmxMessage = tmp[MMXMessageKey]; // the incoming message contains a poll identifier if ([mmxMessage.contentType isEqualToString: [MMXPollAnswer contentType]]) { MMXPollAnswer *pollAnswer = mmxMessage.payload; NSString *pollID = pollAnswer.pollID; NSString *pollName = pollAnswer.name; // poll name NSString *pollQuestion = pollAnswer.question; // poll question NSArray <MMXPollOption *>* pollSelections = pollAnswer.currentSelection; // the currentSelection property is a list of PollOption chosen by the sender NSString *senderUserId = mmxMessage.sender.userID; } }

If the current user has voted in the poll, the selected PollOption(s) can be obtained from the poll object.

MMXPoll *myPoll; // = ...; NSArray <MMXPollOption *>*myChoices = myPoll.myVotes; // a list of PollOption selected by the current user

Obtain Poll Results

There are several ways to obtain poll results.

Get latest poll object from the server using a pollId:
NSString *pollID; // = ...; [MMXPoll pollWithID:pollID success:^(MMXPoll * poll) { // get the number of votes casts towards each option NSNumber *option1VoteCount = myPoll.options[0].count; // returns the number of votes for option 1 NSString *option1VoteText = myPoll.options[0].text; // returns the value of option 1 NSNumber *option2VoteCount = myPoll.options[1].count; // returns the number of votes for option 2 NSString *option2VoteText = myPoll.options[1].text; // returns the value of option 2 } failure:^(NSError * error) { //NSLog(@"%@", error.localizedDescription); }];
Refresh existing poll object results:
MMXPoll *myPoll; // = ...; [myPoll refreshResultsWithCompletion:^(MMXPoll * poll) { if (poll) { NSNumber *option1VoteCount = poll.options[0].count; // returns the number of votes for option 1 NSString *option1VoteText = poll.options[0].text; // returns the value of option 1 } else { //unsuccessful refresh } }];
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 refreshResultsWithAnswer: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().

MMXPoll *myPoll; // = ...; [myPoll refreshResultsWithCompletion:^(MMXPoll * poll) { if (poll) { NSNumber *option1VoteCount = poll.options[0].count; // returns the number of votes for option 1 NSString *option1VoteText = poll.options[0].text; // returns the value of option 1 } else { //unsuccessful refresh } }];