Drawing widgets - Dizplai API

Every widget arrives in an experience’s items, in display order, and type says which drawing to use. Ignore a type you don’t know: new types are added within v1. Widgets carry no images yet; they arrive in a later version.

Field	Use
`type`	Which drawing to use
`status`	What to show. See States
`question`, `subtitle`	The heading and the line under it, where the type has them
`requires_sign_in`	When `true`, show a fan who isn’t signed in your sign-in prompt instead of the widget
`results_visibility`	When fans may see results. See Results
`total_votes`	Fans who voted. Null until the first result
`final`	`true` once votes have stopped and been recounted: the official result
`starts_at`, `ends_at`	When it opens and closes, if timed. Null when the producer cues it

By type

Poll

question and one choice per entry in options, each with a label. The fan picks one, and your app sends its id to POST /polls/{poll_id}/votes as option_id. Results: each option’s votes and percent.

Picker

A run of head-to-head rounds between the people in options (label, plus first_name and last_name where given), each round lasting timer_seconds, which your app enforces. The fan’s last pick is their vote. Results: each option’s votes and percent.

Rating

question, then every player in options with a score from 1 to max_rating. A fan needn’t rate every player. Results, per player: average_vote, rating_count, and distribution, the fans who gave each score.

Predictor

subtitle, the two teams (team1.name, team2.name) and a score for each, from 0 to max_score. Votes stop at locks_at, usually kick-off, when it turns locked. Results: predictions, every predicted score line with its votes, most popular first. Once it’s settled, each team carries its final score.

Line-up

question, the formations a fan may use (one means it’s fixed), and the players in teams[].players, each with a label and position_group, and a shirt_number where given. The fan picks a formation and a player for each position. Results: positions, the top three players for each, with votes and percent, and formation_votes when fans choose the formation.

Fan Zone

type is messaging. Show prompt, an input with placeholder, and the kinds of message in kinds: text, and voice notes and image photos for signed-in fans only, within limits. After a message is sent, show confirmation_message. Fans never see each other’s messages, and there are no results: your team reviews messages, and only approved ones reach air, with the fan’s consent. Show each of slides in turn, for display_duration_ms each. A slide’s url is where it links to. No votes, no results.

States

`status`	Show
`scheduled`	Nothing yet, or a “coming up” teaser with `starts_at` if it has one
`live`	The widget, taking votes or messages
`locked`	Predictors: votes have stopped at kick-off. Waiting for the final score
`closed`	Votes have stopped. Results if fans may see them, marked final once `final`
`settled`	Predictors: the final score, beside the fans’ predictions
`hidden`	Nothing. It can come back
`deleted`	Nothing

Lists return live widgets unless you ask for other statuses, such as ?status=live,scheduled.

Results

`results_visibility`	Fans see results
`live`	While it’s live, updating every second
`after_vote`	Once they’ve voted. Your app’s reads include results from when votes have stopped
`after_close`	Once votes have stopped
`hidden`	Never

Your servers’ reads always include results. To keep them current, see Live updates.

​Every widget

​By type

​Poll

​Picker

​Rating

​Predictor

​Line-up

​Fan Zone

​Sponsor

​States

​Results

Every widget