Group ranking API

Dynamically reorder groups at runtime

In the standard use of Formsort, steps can be placed into groups 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.