Result pages

A result page is built one of two mutually exclusive ways - you pick one per result object:

• Simple: send title (required) and, optionally, description on the result (or, for a quiz, each entry of results) object.
• Complex: send a blocks array instead - see Advanced result pages below. As soon as you send blocks, title/description are no longer accepted on that same object, since the page's content now comes entirely from the blocks.

Sending title/description together with blocks on the same result object is rejected - here for the result of a Poll:

{
    "success": false,
    "code": 400,
    "error": "RIDDLE_BUILDER_BLOCK_PROPERTY_VALUE_VALIDATION",
    "message": "Poll result: \"title\" is not a supported property here. Supported: blocks."
}

Note: This rejection is part of the strict key validation, which is always active when you edit an existing Riddle and opt-in via strictProperties when you create one. Without it, the title is silently dropped instead - the result page still comes out as a complex one built from your blocks.

Note: For quiz results, minPercentage/maxPercentage are required either way - they define the score range a result applies to and are independent of which of the two shapes above you choose for its content.

For quiz (simple result pages):

{
    "blocks": [...],
    "results": [
        {
            "minPercentage": 0,
            "maxPercentage": 50,
            "title": "Bad result",
            "description": "You answered less than 50% of the questions correctly"
        },
        {
            "minPercentage": 51,
            "maxPercentage": 100,
            "title": "Good result",
            "description": "You answered more than 50% of the questions correctly"
        }
    ]
}

For any other Riddle type (simple result page):

{
    "blocks": [...],
    "result": {
        "title": "Thank you!",
        "description": "We are happy to have you here"
    }
}

A quiz has one result per score range: every entry of results needs a minPercentage (0-100) and a maxPercentage (1-100). Every other Riddle type has exactly one result, given as the single result object.

title is required on a simple result page; description is optional.

This default (simple) result page always consists of:

• Your given title and description
• A block which allows the user to share the result on different social networks

Additionally it may contain:

• For quiz: a block which shows the user how many questions they answered correctly
• For personality: a block which shows the user information about their winning personality and other personalities (if available)

In most cases this should suffice - if you want to create result URL redirects or advanced result pages similar to the functionality in the Creator, keep reading.

Redirect to a URL

If you want to redirect the user to a URL after they have completed the Riddle, you can do this by adding a redirectUrl property to the result object.

{
    "blocks": [...],
    "result": {
        "redirectUrl": "https://www.riddle.com"
    }
}

This will redirect the user to https://www.riddle.com after they have completed the Riddle.

Note: This result redirecting works for Poll, Quiz, Form, Predictor, and Minigame Riddles. Personality tests and leaderboards do not support it.

Optional properties

There are several options you can choose from when adding a result redirect:

Note: Only with the delay property will the user actually see the title and description.

Note: For Quiz Riddles, redirects are defined per result inside the results array. In this case minPercentage and maxPercentage are additionally required to define the score range for which this redirect applies.

Example:

{
    "blocks": [...],
    "result": {
        "redirectUrl": "https://www.riddle.com",
        "delay": 5,
        "title": "Thank you!",
        "description": "We are happy to have you here",
        "openFullscreen": false
    }
}

Advanced result pages

You can create advanced result pages with texts, images, answered blocks, and more via the API's result builder. See the result page documentation to see how this works in the Creator.

Similar to the Riddle's blocks the result page is also structured in blocks. blocks is an array of objects (see item formats) - every block needs at least its type. You can add up to 10 blocks to the result page. To do this send a blocks array in the result object instead of, not in addition to, a title and description property - the two are mutually exclusive, see above.

For poll (or any type which only has one result):

{
    "blocks": [...],
    "result": {
        "blocks": [
            {
                "type": "Text",
                "text": "This is my result page text!"
            },
            ...
        ]
    }
}

For quiz:

{
    "blocks": [...],
    "results": [
        {
            "minPercentage": 0,
            "maxPercentage": 50,
            "blocks": [
                {
                    "type": "Text",
                    "text": "Bad result"
                },
                ...
            ]
        },
        {
            "minPercentage": 51,
            "maxPercentage": 100,
            "blocks": [
                {
                    "type": "Text",
                    "text": "Good result"
                },
                ...
            ]
        }
    ]
}

Every result page block consists of a type property and additional properties depending on the block type. For example here is the content for the button block only with required options:

{
    "type": "Button",
    "label": "My new button!",
    "url": "https://riddle.com"
}

This will create a button with the label "My new button!" which links to https://riddle.com. If we now want to set the optional property isOpenInNewTabEnabled to true the object for this button would look like this:

{
    "type": "Button",
    "label": "My new button!",
    "url": "https://riddle.com",
    "isOpenInNewTabEnabled": true <--- optional property
}

In the next sections all available blocks are listed with their required and optional properties. These are the available type values:

A result page needs at least 1 and accepts at most 10 blocks. Using a type that is not available for the Riddle type you are building (e.g. WinningPersonality in a poll) is rejected with an "Invalid result builder block type" error.

Add user's score

Displays the user's score in a given format.

Properties

Example

{
    "type": "ResultScore",
    "format": "Score",
    "colorBg": "#fff",
    "colorText": "#000",
    "colorCircle": "#000",
    "colorCircleBg": "#fff"
}

Add text

Displays a regular text block. You can use HTML tags in the text.

Tip: Use dynamic variables here to personalize the result page text to user input.

Properties

Example

{
    "type": "Text",
    "text": "This is my result page text!"
}

Add button

Displays a call to action button that links to a specified URL on click.

Tip: Use dynamic variables in the label or URL.

Properties

Note: fontFamily only accepts one of the following values (generic CSS families like Arial or sans-serif are rejected with a NOT_ALLOWED_VALUE error) - use the Builder API font families endpoint to fetch this same list at any time (that endpoint requires a Business or Enterprise plan):

ABeeZee, Abril Fatface, Alex Brush, Archivo, Arimo, Assistant, Atkinson Hyperlegible, Barlow, Baskervville, Bebas Neue, BioRhyme, Bitter, Bree Serif, Cabin, Cabin Sketch, Cairo, Calistoga, Candal, Cantarell, Cardo, Cormorant, Cormorant Garamond, Cormorant Infant, Cormorant SC, Cormorant Unicase, Courgette, Crimson Text, Dancing Script, DM Sans, DM Serif Display, DM Serif Text, Domine, EB Garamond, Electrolize, Exo, Exo 2, Fira Sans, Fjalla One, Gentium Basic, Gentium Book Basic, IBM Plex Sans, IBM Plex Serif, Inconsolata, Inter, Istok Web, Josefin Sans, Jost, Jura, Karla, Khand, Lato, Libre Baskerville, Libre Franklin, Lora, M PLUS 1p, M PLUS Rounded 1c, Maven Pro, Montserrat, Montserrat Alternates, Mukta, Noto Sans, Noto Sans JP, Noto Sans KR, Noto Sans SC, Noto Serif, Nunito, Nunito Sans, Old Standard TT, Open Sans, Open Sans Condensed, Oswald, Overpass, Pacifico, Permanent Marker, Playball, Playfair Display, Poppins, PT Mono, PT Sans, PT Serif, Quattrocento, Quattrocento Sans, Qwigley, Raleway, Red Hat Display, Red Hat Text, Roboto, Roboto Condensed, Roboto Mono, Roboto Slab, Rokkitt, Rubik, Russo One, Sanchez, Satisfy, Schoolbell, Source Code Pro, Source Sans Pro, Source Serif Pro, Spartan, Special Elite, Spectral, Teko, Tenor Sans, Tinos, Titillium Web, Ubuntu, Unica One, Varela, Varela Round, Vollkorn, Work Sans, Zilla Slab

Example

{
    "type": "Button",
    "label": "Click me!",
    "url": "https://riddle.com",
    "isOpenInNewTabEnabled": true,
    "colorBg": "_colorBg",
    "colorBgHover": "#fff",
    "colorBorder": "#fff",
    "colorBorderHover": "#fff",
    "colorText": "#fff",
    "colorTextHover": "#fff",
    "borderRadius": "5px",
    "borderWidth": "5px",
    "padding": "5px",
    "textCapitalization": "lowercase",
    "textAlign": "inherit",
    "textLetterSpacing": "20px",
    "textLineHeight": "20px",
    "fontFamily": "Poppins",
    "fontSize": "20px",
    "fontStyle": "oblique",
    "fontWeight": "bolder"
}

Add share to social block

Displays a share block that allows users to share the result on different social networks.

You can customize the share messages, URLs and all of the share block's design properties.

Properties

Example

{
    "type": "Share",
    "messageTitle": "Share this poll!",
    "messageDescription": "This is a description",
    "networks": ["facebook", "linkedin"]
}

Per-network configuration

networks only switches networks on and off. If you want a different share message per network, use networkConfigs instead - an object keyed by network name, where each value may contain:

Setting any of title, description, url or image for a network automatically sets that network's isOverwriteValuesEnabled to true. Unknown network names are rejected. networkConfigs is applied after networks, so you can enable a set of networks with the simple list and then refine individual ones.

Example:

{
    "type": "Share",
    "networks": ["facebook", "linkedin"],
    "networkConfigs": {
        "linkedin": {
            "title": "I scored 9/10 - can you beat me?",
            "url": "https://www.your-website.com/quiz"
        }
    }
}

Available social networks

The following social networks are available to share on (make sure to use the same casing!):

• buffer
• email
• evernote
• facebook
• flipboard
• instagram
• instapaper
• line
• linkedin
• messenger
• odnoklassniki
• pinterest
• pocket
• reddit
• skype
• sms
• telegram
• tumblr
• twitter
• viber
• vk
• weibo
• whatsapp
• xing
• yammer

Add answered blocks

Displays a block that shows the user what they answered and how many votes each answer got (if enabled).

Properties

Example

{
    "type": "AnsweredBlocks",
    "areTotalVotesVisible": true
}

Add image

Displays an image, a video, or embedded social media content.

Properties

Example

{
    "type": "Media",
    "media": "https://httpbin.io/image/jpeg",
    "mediaFit": "Contain"
}

Add leaderboard

Add a leaderboard to the result page.

Properties

Example

{
    "type": "Leaderboard",
    "leaderboard": "hQ3SYWur"
}

Note: The leaderboard has to satisfy two conditions, and both are checked while the build runs:

• it must already be published - a leaderboard that only exists as a draft is rejected with Leaderboard hQ3SYWur is not published, so publish it (or build it with "publish": true) before referencing it here, and
• the Riddle you are building must be connected to it, otherwise the build is rejected with Leaderboard hQ3SYWur is not connected to Riddle abcdef12.

The connection is configured in build.leaderboard.connections of this Riddle, or from the leaderboard's side via riddleConnections - see Create and connect to Leaderboard. Sending both the connection and this block in one build configuration works: the connection is established before the result page is built.

Add popular choices

Ranks the outcomes all respondents predicted, e.g. "63% picked Team A". Only available for predictors.

Properties

Example

{
    "type": "PopularChoices",
    "topChoicesCountSingleQuestion": 3,
    "showOtherChoicesSummary": false
}

Add winning personality

Displays the user's winning personality. Only available for personality tests.

Properties

Example

{
    "type": "WinningPersonality",
    "showMedia": true,
    "format": "Title"
}

Add other personalities

Displays the other personalities. Only available for personality tests.

Properties

Example

{
    "type": "OtherPersonalities",
    "format": "Title",
    "count": 3,
    "layout": "FullWidth",
    "includeWinningPersonality": false
}

Add attributes

Displays a bar per Personality attribute with its score. Only available for personality tests.

Properties

Example

{
    "type": "Attributes",
    "format": "Title",
    "count": 3,
    "layout": "FullWidth"
}

Add recommended content

Displays other Riddles the visitor might want to check out next. You can either pick the Riddles yourself, or have them selected dynamically by type/tag.

Properties

Note: selectionMode and its matching properties form two strictly separate sets - Manual only ever reads selectedRiddles, Conditions only ever reads riddleTypes/tags/sortBy/amount. This is enforced, not just gated for display:

• As soon as you send any property from either set, you must also send selectionMode explicitly (set to Manual or Conditions) - it is never inferred from what else you sent.
• Sending a property that belongs to the other mode than the one you selected is rejected outright.
• In Manual mode, selectedRiddles must be a non-empty list - an empty selection would show nothing.

Each selectedRiddles UUID must belong to a Riddle you (or your team) own and that is currently published; an unpublished, missing, or foreign Riddle is rejected.

Each tags entry must be an existing tag of the same scope as the Riddle you are building - your team's tags for a team Riddle, your own otherwise. Send either the numeric tag ID or the tag name; a tag that does not exist, or belongs to someone else, is rejected (a build never creates a tag), and naming the same tag twice is rejected as well. Tags always read back as their numeric IDs, which - unlike a name two tags could share - are unambiguous. If a tag is deleted later, reading the Riddle back leaves it out and reports a warning; sending that build configuration back therefore also removes it from the stored filter.

Example: manual results

{
    "type": "RecommendedContent",
    "title": "You might also like",
    "selectionMode": "Manual",
    "selectedRiddles": ["hQ3SYWur", "aB1cDeFg"]
}

Example: conditional results

{
    "type": "RecommendedContent",
    "title": "More quizzes",
    "selectionMode": "Conditions",
    "riddleTypes": ["Quiz"],
    "tags": ["Summer"],
    "amount": 3
}

Offset any block with margins

If you want to create a gap between two result page builder blocks, e.g. to emphasize a certain block, you can use margins to better position the blocks.

Note: The margin does not work with pixel values! Instead we use the coordinate system just as in the Creator to position the blocks. This means that setting "marginTop: 2" will result in a block offset by two units. We recommend you play around and see what works best for your design.

Properties

Both are accepted on every result page block type.

Example

{
    "type": "Text",
    "text": "This is my result page text!",
    "marginTop": 2,
    "marginBottom": 2
}

Full example

A poll with an advanced result page built into it: a text, the answered blocks with their total votes, an image and a button back to your site.

{
    "type": "Poll",
    "build": {
        "title": "Pasta poll",
        "blocks": [
            {
                "type": "SingleChoice",
                "title": "Spaghetti or Fusilli?",
                "items": [
                    { "title": "Spaghetti" },
                    { "title": "Fusilli" }
                ]
            }
        ],
        "result": {
            "blocks": [
                {
                    "type": "Text",
                    "text": "Thanks for voting!"
                },
                {
                    "type": "AnsweredBlocks",
                    "areTotalVotesVisible": true
                },
                {
                    "type": "Media",
                    "media": "https://httpbin.io/image/png",
                    "mediaFit": "Contain"
                },
                {
                    "type": "Button",
                    "label": "Back to the blog",
                    "url": "https://riddle.com"
                }
            ]
        }
    }
}