LogoLogo
Back to studio
  • Formsort documentation
  • โฉQuickstart
    • ๐ŸŸขGet started with Formsort
    • ๐ŸŽCore concepts
    • โ„น๏ธQuestion and content reference
    • ๐Ÿ“•Key terms
    • ๐Ÿž๏ธCreate your first flow
    • ๐Ÿ“–Add content and collect answers
      • ๐ŸคณCapture demographic data
      • โ„น๏ธAdd informational content
      • ๐Ÿ” Review your variable schema
    • ๐ŸŽจCreate a theme
      • Set brand guidelines
    • ๐ŸคนPersonalize your flow
      • ๐ŸŒŸTemplate your variables
      • ๐Ÿง Add conditional logic
      • ๐Ÿ’ซUsing conditional logic with Calculated and API variables
      • ๐Ÿ”šEnd the flow
    • ๐Ÿ”€Set up integrations
    • ๐Ÿš€Go live
      • Auditing your flow for content, functionality, and design
    • ๐Ÿ’ผCommon use cases
      • ๐Ÿ’”Disqualify responders
      • ๐Ÿ—“๏ธAdd a scheduling option
      • ๐Ÿ“„Allow responders to read and accept your company policies
  • ๐Ÿ—๏ธBuilding flows
    • Flows and variants
      • Flow starts
    • Adding content
      • Groups
      • Steps
        • Settings
        • Logic
        • Style
      • Questions
        • General Settings
        • Style
        • Address
        • Comparison
        • Confirmation
        • Date
        • Date & Time
        • Email address
        • File upload
        • Grid choice
        • Iframe
        • Image upload
        • Number
        • Payment
        • Phone number
        • Postal code
        • Question group
        • Region
        • Select
          • Providing choices via API or calculation
        • Signature
        • SSN
        • Text questions
        • Yes/No
      • Content
        • General Settings
        • Statement
        • Image
        • Video
        • Next button
        • Divider
        • Map
      • Endings
      • Using markdown
      • Using variable templating
        • Template formatting functions
      • Copy-pasting form content
      • Content library
    • Conditions and logic
      • Logical operator reference
      • Advanced logic
    • Variables (answers)
      • Variables from questions
      • Externally provided variables
      • Calculated variables
      • API lookups
      • System Library variables
      • Orphaned variables
    • Schemas
      • JSON Schemas
      • Validating flow schemas
    • Redirects
    • Styling and themes
      • CSS Reference
      • Overriding theme styling
      • Custom CSS overrides
      • Content area
      • Animations and transitions
      • Form Layout
      • Typography
        • Adobe Fonts
        • Hosting custom fonts
      • Color variables
      • Dimension variables
      • Question containers
      • Assets
      • Form Buttons
        • Select buttons
      • Inputs and dropdowns
      • Checkmarks
      • Tables
      • Sliders
      • Divider lines
      • Progress bar
      • Comparison cards
    • Variant settings
      • Form behavior for returning responders
      • Group ranking API
    • Publishing and versions
      • Preview window
      • Deploying
      • History
  • ๐Ÿ’พHandling data
    • Philosophy and data retention policy
    • Viewing form answers
    • Responder UUIDs
    • Environments
      • Loading different environments
    • Passing data in
      • URL parameters
      • POST body
      • Embed query parameters
    • Custom validators
    • Form answers and events
      • Analytics events
      • Signed requests
      • Event payload shape
      • Submission frequencies
      • Runtime error reporting
      • Admin API
      • Flow content data format
    • Integration reference
      • Amplitude
        • Amplitude cross domain tracking
      • BigQuery
      • FullStory
      • Google Analytics
        • Updating from Universal Analytics to GA4
      • Google Cloud Storage
      • Google Sheets
      • Google Tag Manager (GTM)
        • JavaScript triggered by flow events
      • Hubspot
      • Jornaya
      • Optimizely
      • PostgreSQL
      • Redshift
      • Rudderstack
      • S3
      • Salesforce
      • Segment
        • Segment Setup
        • Segment cross domain tracking
      • Stripe
      • TrustedForm
      • Webhooks
        • Zapier
  • ๐Ÿ“บGoing live
    • Custom domains
    • Built-in analytics
    • Embedding
      • Web-Embed API
        • React-embed
      • Adding authentication
      • Embedding forms in iOS and Android
      • Setting up a dev environment
    • Split testing
    • Preflight checklist
  • ๐ŸขTeams
    • Accounts
      • Roles and permissions
    • Events subscriptions
    • Workspace domain detection
Powered by GitBook
On this page
  • Setting up dynamic group ranking
  • Expected response
  • Notes and suggestions

Was this helpful?

  1. Building flows
  2. Variant settings

Group ranking API

Dynamically reorder groups at runtime

PreviousForm behavior for returning respondersNextPublishing and versions

Last updated 1 year ago

Was this helpful?

In the standard use of Formsort, steps can be placed into for organizational purposes; the steps will then appear in the order of their parent groups. Groups and steps can be re-arranged by dragging and dropping, but once they are published they will always be seen by the responder in the fixed order.

Using the Group ranking API, it's possible to re-arrange groups dynamically. This allows for you to decide on-the-fly which content to show the responder, in which order.

One example use case would be a flow with many different offers that are shown to responders. Based on information gathered within a flow, some offers might be more likely to be relevant to the responder: the group ranking API allows for showing those first, and delaying (or hiding entirely) less-relevant groups.

Setting up dynamic group ranking

To reliably refer to groups in the dynamic ranking, we first need to define unique group IDs. To do so, set the Group ID with a group selected on each group that you want to reorder.

The group ranking API is configured by adding a URL to the Variant settings.

Like most URLs within Formsort, the URL can be templated with answers that are present within the flow: the URL will be fetched any time one of the inputs is changed.

Expected response

The group ranking API expects a JSON response that is an object with string keys corresponding to the group ID, and values corresponding to their rank, which will be used to sort the groups.

  • Groups with a lower rank will appear before groups with a higher rank

  • Groups that are defined within the flow but that are not present in the ranking, or do not have a group ID defined will be given a ranking of 0.5.

  • Groups given a ranking of -1 will be hidden in the flow

  • The sort is stable - if a ranking contains multiple groups each with the same rank, the groups will appear in the order that they were originally defined.

  • Groups that have already been completed or entered by the responder will not be re-ranked.

For example, imagine a flow with four groups: Intro, About You, About Your Pet, and "Bonus Content". Let's look at the following ranking response

{
  "intro": 0.1,
  "about-you": 0.9,
  "bonus-content": -1
}

This would result in a flow with three groups, in this order:

  1. Intro (has a low rank of 0.1)

  2. About your pet (it does not appear in the ranking, so it is given the default rank of 0.5)

  3. About you (has a high rank of 0.9)

The Bonus content group would not appear in the result since it was given a rank of -1.

Notes and suggestions

Be careful about conflicting sources of truth when it comes to determining which groups are enabled. If a group is disabled according to conditions and logic defined within the flow itself, it will always be hidden, even if the group appears in the ranking response.

Don't return orderings that would violate dependencies between groups, such as a group that uses an answer collected in a previous group. Such invalid configurations may lead to problems and should be avoided.

๐Ÿ—๏ธ
groups