Adaptivecards: Rating control (stars)

[productboard-ac]

Proposal: Adaptive Cards Feedback Controls

Summary

Feedback control features should be implemented in the Adaptive Cards framework. Specifically, the framework should allow for binary feedback (i.e., thumbs up/thumbs down functionality), as well as the traditional star-rating feedback. These controls should be flexible enough to fit the needs of any card author.

Rationale

• Several customers have directly expressed interest in tools allowing users to easily send feedback, such as a star-rating system or a thumbs up/thumbs down system. Customers are currently finding workarounds to this functionality, but a native feature would improve usability for both users and developers.
• User feedback and customer data are key for companies to gauge success and explore avenues for improvement. Feedback control functionality for Adaptive Cards would facilitate easier collection of feedback and data points.
• Both the traditional star-rating control as well as a separate thumbs up/thumbs down control are necessary due to the different use cases between the two controls. A binary system may be better suited for situations in which a company values quantity of responses (a user may be more inclined to respond with fewer options). In fact, Netflix recently made the switch to a binary feedback system after finding that this type of system received 200% more user responses than the traditional star-rating system. On the other hand, a company that values more engaged feedback, such as Yelp or Amazon in the case of restaurant and product reviews, may find that a star-rating system better suits its needs.

Scope

| Capability | Priority |
| :---------- | :------- |
| This proposal will allow card authors to gather user feedback on an Adaptive Card, both on a 5-point and binary (2-point) scale | Must |
| This proposal will allow card authors access to customization features for feedback control, including the ability to change rating icons, rating scale, and rating labels | Should |
| This proposal will allow end users to see dynamic card changes in response to actions like hover and click | Should |
| This proposal will allow card authors display-only capabilities for their ratings | Could |
| This proposal will allow card authors to create a slider rating | Could |

Important Notes

• Example 1: Medical survey
  

  • Features of note:
    
    
    
    • Labels for options
    
    
    • Flexible quantity of options
    
    
    • Icon customization
    
    

• Example 2: Yelp restaurant feedback
  

  • Features of note:
    
    
    
    • Dynamic hover changes rating icons
    
    
    • Dynamic hover changes elements outside of rating; once an option is clicked, this could potentially lead to further input options based on the initial rating option (e.g., a bad rating will lead to an optional text box appearing asking the end user to explain their rationale)
    
    
    • Basic five-point rating system
    
    

• Example 3: Simple 5-star rating
  

• Example 4: Rating sliders
  

• Example 5: Binary controls
  

Open Questions

• Should default rating icons should be native to the host? If so, this may add an extra burden to the host
  

  Adaptive Cards-specific Considerations

Schema

https://github.com/microsoft/AdaptiveCards/compare/master...specs/3054-2

Introduce a new Input.Rating element.

{
    "type": "AdaptiveCard",
    "body": [
        ...
        {
            "type": "Input.Rating",
            "id": "userRating"
        }
    ],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.0"
}

Customizing the number of stars

Say they want 6 stars...

{
    "type": "AdaptiveCard",
    "body": [
        ...
        {
            "type": "Input.Rating",
            "id": "userRating",
            "maxValue": 6
        }
    ],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.0"
}

Customizing the icons

{
  "type": "AdaptiveCard",
  "body": [
    {
      "type": "Input.Rating",
      "id": "userRating",
      "icons": {
        "unselected": {
          "type": "Image",
          "url": "https://yelp.com/icons/unselectedStar.png"
        },
        "selected": {
          "type": "Image",
          "url": "https://yelp.com/icons/selectedStar.png"
        }
      }
    }
  ],
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.0"
}

Host Config

There should not be any changes to the host config.

Down-level impact

If the authors were using work arounds for previous versions, they could choose move to the simpler version of having native feedback controls.

Host burden

It is possible that the host would have to configure how they would like stars to show up in terms of color and style, but they could just render as default stars.

[productboard-ac]

Link to feature: https://adaptivecards.productboard.com/feature-board/planning/features/1711065

[dclaux]

Thanks for writing.

I think this should be folded into the existing Input.ChoiceSet rather than being introduced as a new Input.Feedback input:

• There is nothing that inherently would make Input.Feedback reserved for "feedback" scenarios; it's just an input
• Input.ChoiceSet already has 90+% of all that's needed and is a more generic approach

Here is what I think we should do:

Enhance Input.ChoiceSet

New iconUrl on Choice

• The Choice type used in the Choices collection already has title and value; title is the equivalent of labels in the proposal, and value is missing from the original proposal.
• iconUrl is better off being co-located with the choice rather than living in a separate collection IMO

• Quantity isn't necessary, as the total number of choices is determined from the number of items in the Choices array

  New supported styles: rating and slider

• rating: render using the typical star rating model

• slider: render as slider

• isMultiSelect is ignored for styles rating and slider, just like it is ignored for the style compact

  New isReadOnly property

• A new isReadOnly property is added. In many cases, star ratings are used to simply display a rating without letting the end user modify it

Notes

• iconUrl can also be displayed in styles default and compact, increasing the visual richness of the existing ChoiceSet styles
• iconUrl is always repeated on all choices instead of being specified once. I do not believe that is a problem, but we could use the first iconUrl found on choices that may not have one psecified if necessary
• A single iconUrl doesn't seem to be enough. Editable star ratings use at least two icons for each "star"
• Using a second icon to represent the other state of a "star" dosn't make it possible to render decimal values. Often ratings are 4.2 and the decimal is important (think of app stores.) The contro should have the ability to visually represent the decimal value. For instance (from the Windows Store):
  

Example

{
    "type": "AdaptiveCard",
    "version": "1.3",
    "body": [
        {
            "type": "Input.ChoiceSet",
            "id": "example",
            "quantity": "5",
            "style": "rating",
            "title": "Please rate your experience",
            "choices": [
                { "title": "Bad", "value": "0", "iconUrl": "https://compass-ssl.microsoft.com/assets/7f/65/7f65967d-1413-4ce9-a32a-e444182a7092.svg?n=Xbox.svg" },
                { "title": "OK", "value": "1", "iconUrl": "https://compass-ssl.microsoft.com/assets/7f/65/7f65967d-1413-4ce9-a32a-e444182a7092.svg?n=Xbox.svg" },
                { "title": "Fine", "value": "2", "iconUrl": "https://compass-ssl.microsoft.com/assets/7f/65/7f65967d-1413-4ce9-a32a-e444182a7092.svg?n=Xbox.svg" },
                { "title": "Good", "value": "3", "iconUrl": "https://compass-ssl.microsoft.com/assets/7f/65/7f65967d-1413-4ce9-a32a-e444182a7092.svg?n=Xbox.svg" },
                { "title": "Great", "value": "4", "iconUrl": "https://compass-ssl.microsoft.com/assets/7f/65/7f65967d-1413-4ce9-a32a-e444182a7092.svg?n=Xbox.svg" }
            ]
        }
    ],
    "actions": [
        {
            "type": "Action.Submit",
            "title": "Submit"
        }
    ]
}

[andrewleader]

Feedback from 6/14/2019 proposal review meeting

David: Would prefer expanding Input.ChoiceSet. Input.Feedback also seems to imply that you couldn't really use it for just a rating. Add readOnly property. Color hue changing as selections increase seems nice-to-have, but we should explore ways to enable that in the future.

Andrew: Agrees about exploring using Input.ChoiceSet. Disagrees about readOnly property

Peter: Using Input.ChoiceSet seems like a good option, only thing is whether the slider and hover would be possible. Might need ability to toggle and hide checkboxes.

Alberto: Host config allow choosing the background of the selected item. Also sometimes when you click the item, sometimes authors want that to instantly submit.

David: Would be nice if each renderer implementation could have built-in stars. What would it take to have a library of icons across all renderers, that authors could choose from?

Shalini: Loop in Jacklyn for default presentation of the rating controls

[andrewleader]

Here's my proposal...

Introduce a new Input.Rating element.

Spec proposal: https://github.com/microsoft/AdaptiveCards/compare/master...specs/3054-3

{
    "type": "AdaptiveCard",
    "body": [
        ...
        {
            "type": "Input.Rating",
            "id": "userRating"
        }
    ],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.0"
}

Customizing the number of stars

Say they want 6 stars...

{
    "type": "AdaptiveCard",
    "body": [
        ...
        {
            "type": "Input.Rating",
            "id": "userRating",
            "maxValue": 6
        }
    ],
    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
    "version": "1.0"
}

Customizing the icons

{
  "type": "AdaptiveCard",
  "body": [
    {
      "type": "Input.Rating",
      "id": "userRating",
      "icons": {
        "unselected": {
          "type": "Image",
          "url": "https://yelp.com/icons/unselectedStar.png"
        },
        "selected": {
          "type": "Image",
          "url": "https://yelp.com/icons/selectedStar.png"
        }
      }
    }
  ],
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "version": "1.0"
}

Why use adaptive elements for the icons?

• When we introduce the SVG element, people will want to use that
• Maybe there's other properties on the image that people will want to use, like the proposed new tint property
• Maybe people want to use a textblock with a glyph as the icon

How to support changing color as value increases?

This could be enabled with a separate feature. We know we need the ability for cards to change when the user selects a value, we could also provide ability for authors to change the card when the user hovers over a value. Authors could then simply change the selected icons out upon each hover.

For research purposes, UWP's rating control only has the following properties

        // Summary:
        //     Gets or sets the rating value.
        public double Value { get; set; }

        // Summary:
        //     Gets or sets the rating that is displayed in the control until the value is changed
        //     by a user action or some other operation.
        public double PlaceholderValue { get; set; }

        // Summary:
        //     Gets or sets the maximum allowed rating value. The default is 5.
        public int MaxRating { get; set; }

        // Summary:
        //     Gets or sets info about the visual states of the items that represent a rating.
        public RatingItemInfo ItemInfo { get; set; }

        // Summary:
        //     Gets or sets the value that determines if the user can change the rating.
        public bool IsReadOnly { get; set; }

        // Summary:
        //     Gets or sets the value that determines if the user can remove the rating. The default
        //     is **true**.
        public bool IsClearEnabled { get; set; }

        // Summary:
        //     Gets or sets the initial set rating value. The default is 1.
        public int InitialSetValue { get; set; }

        // Summary:
        //     Gets or sets the text label for the control.
        public string Caption { get; set; }

Concerns about expanding ChoiceSet...

• The name ChoiceSet is unintuitive for authors. They're trying to get a rating from a user, not let them pick choices. I believe having a dedicated Input.Rating will be much less ambiguous for authors and easier to discover.
• Authors have to manually provide all 5 choices just to get a basic rating

Basic rating with dedicated Input.Rating

{
  "type": "Input.Rating",
  "id": "userRating"
}

If we expanded Input.ChoiceSet

{
  "type": "Input.ChoiceSet",
  "id": "userRating",
  "style": "rating",
  "choices": [
    {
      "value": "1"
    },
    {
      "value": "2"
    },
    {
      "value": "3"
    },
    {
      "value": "4"
    },
    {
      "value": "5"
    }
  ]
}

• Some properties don't apply to rating style...
  
  
  
  • Input.ChoiceSet.wrap property isn't applicable, rating style doesn't display titles
  
  
  • Input.ChoiceSet.isMultiSelect property is ignored when in rating style
  
  
  • I know this is already currently true for compact style, but it's easily imagined that in the future, we WILL support multiselect+compact (a couple people have actually asked for it), whereas a multiselect rating just doesn't exist
  
  
  • Input.Choice.iconSelected and unselected will seemingly be ignored in compact style choice sets, but maybe it's applicable to expanded radio/checkbox icons?
  
  
  • Specifying selected/unselected icons on the choices themselves means redundantly specifying a bunch of icons
  
  
  • This could be resolved by promoting those properties to the ChoiceSet itself
  
  

Concerns about Input.Feedback

• The name Feedback isn't intuitive to me, are there other examples where platforms have called rating controls "Feedback"?
• I think supporting style: horizontal makes more sense as a new feature to ChoiceSet rather than a feedback control that also has rating
• I'm not a fan of having a choices array where authors have to specify out each individual choice, as that makes it verbose just like seen above with the ChoiceSet proposal, and having to specify value: 1, value: 2, etc, becomes redundant and error prone.

[andrewleader]

Meeting notes from proposal review meeting on 6/24/2019

Attendance

• Shalini
• David
• Becky
• Joseph
• Alberto
• Peter
• Utsav
• Brook
• Andrew
• Chigusa (from XAML team)

Chigusa - XAML doesn't have thumbs up/down, just uses two buttons

David - Believes automatic fallback is critical

Andrew - Believes rating is

Jacklyn - Believes there should be a specific control for each specific type

Shalini - Would we end up with weird properties with trying to overgeneralize, with properties that wouldn't apply

David - Yes, but we would have the added capability of the automatic fallback

Becky - Wouldn't they still complain that the rating didn't work? Wouldn't they be unhappy?

David - We should ask the customers what they'd want

Becky - Agrees it's cool that fallback works automatically but not sure that makes designing the element against

Mike - Discoverability is a concern, readOnly is displaying vs disabled is just you can't click on it. Discoverability, it isn't intuitive, are we overgeneralizing?

Becky - Having all those choices on ChoiceSet is a lot for the author

Chigusa - Which works best for customizing?

David - For horizontal, we should use something more semantic

Becky - What would that semantic name for that be?

David - Thinks rating is the correct term for the "horizontal"

David - Thinks "feedback" is a good name for the top horizontal scenario

Becky - But that boxes us in, if you wanted to display menu choices and want them horizontal

Becky - We have ChoiceSet with style compact/expanded, maybe we could do it with a separate alignment that defaults to vertical but can be set to horizontal and then a rating style makes sense, but I don't like having to specify all the choices, and then it's not discoverable

Shalini - Why not have both, improve ChoiceSet with horizontal and have a separate Rating control

Becky - Agreed

David - Introducing Input.Rating doesn't sound right to me, we ruin it even more by adding a separate control.

David - ChoiceSet should include all the layouts, what you want is for the user to select a value, the visual representation is important in some cases. We'd be introducing a separate control just because the visual is different. Input.Number is different since it's different on the schema level.

Shalini - But won't there be some properties that are only applicable to choice set vs rating

Shalini - We could have the customer ask which they prefer

David - In my opinion, when we add a new feature we always should look if we can use existing elements and only if we've established if what we're introducing isn't that close, then we introduce something new

Shalini - I agree that we should be mindful but not at the cost

Becky - Should consider where we're at, are we going to have lots of more users in the future that we shouldn't worry too much about the back compat since there's more potential in the future

Alberto - I kind of agree with David that it has a bunch of similarities, mainly the rating system with the faces or menus, that can be abstracted to the choiceset, but I do think that the rating system like the Input.Rating makes sense as separate.

Shalini - Consider per-platform, how we'd implement it on other platforms, and whether ChoiceSet vs a new control would affect how it feels

David - I don't think the design has any impact on the implementation

Chigusa - What do developers coming from other platforms like Android, what expectations would they have

Shalini - Whatever customer says should have a lot of weight and trump our decision

Chigusa - We just shipped basic rating and so far hasn't had a need to expand

Let's get a pulse of everyone's opinions... Options are...

• Expand ChoiceSet to be able to express a rating
• Introduce dedicated Input.Rating as seen in the most recent comment

Joseph - Both choices seem to be solid, good with either

Utsav - Separate rating

Peter - What I think, I think a new control would be better, just for the fact that we could expand on different options than expanding from ChoiceSet

Shalini - I would also go from the separate control

Brook - Abstaining

Alberto - Like dedicated

Chigusa - I was thinking from developer trying to look up document, I would probably look for rating

Becky - Agree with that, dedicated rating

David - Clearly everyone seems to be for rating, but I disagree with that and would vote for expanding ChoiceSet

Alberto - For the color config, if Teams wants to theme it, makes sense to have colors in host config

David - One conversation we should have is around the goal of host config. The goal was to have config of a host to be shareable across hosts. But so far, all our platforms don't use host config to share across platforms. There are many styling options that'd be better as CSS and having them in host config

[matthidinger]

What if there were a some way to achieve both goals: offering a semantic, simple, discoverable type (Input.Rating), while still achieving backwards compat? For example, what if the designer auto-generated a fallback to a Input.ChoiceSet with the rating properties, or we had some other means of creating fallbacks for new elements, as long as said fallbacks had a reasonable experience?

[dclaux]

@matthidinger having the designer generate fallback is an interesting thought, but one of the arguments I've heard to go with Input.Rating was that there was no forced fallback (which apparently was desirable because the fallback experience was simply not as good.) If we did force a fallback, that would be yet another reason IMO to stick with ChoiceSet instead of introducing another control.

Also, I am still unclear what the benefits of introducing Input.Rating actually are over reusing ChoiceSet. One argument from Bill yesterday was that Input.Rating's values could be numbers instead of strings, and that could be helpful in the future to author binding expressions (for instance {myInputRating.value > 2}) but the thing is, not everyone will want to use Input.Rating and ChoiceSet will continue to be used extensively; people will likely also want to write such binding expressions against the value of a ChoiceSet, which is a string.

Unless I'm mistaken, the main argument for Input.Rating is "discoverability." I personally don't buy that. We can make things discoverable via the designer regardless of whether we introduce Input.Rating or if we enhance Input.ChoiceSet. And this is just a one time thing that people have to learn.

I am very, very much for reusing ChoiceSet.

[shalinijoshi19]

@matthidinger, I love it! And from what I understand the fallback scenario is going to be an issue for every new feature or control we introduce going forward, so maybe this may even be a good time perhaps to revisit this notion of a "Default fallback" generation more broadly ?

[msftbot[bot]]

This issue has been automatically marked as stale because it has not had any activity for 5 days.

[shunyh]

Hi, can you tell me how to use the Input.Rating type in .Net bot framework SDK?

[shunyh]

I don't get any Input.Rating info on this page: https://adaptivecards.io/explorer/Input.ChoiceSet.html.

[shalinijoshi19]

Hi @shunyh this feature is still in development and has not yet been released for any platform.

[shunyh]

Well noted with thanks, @sha1painkiller

[mutanttech]

Any timelines on when this can be materialized in Production.

[archanag51]

Yeah , please do let know when will this feature be available in production

[yschang]

Hello, is there any update on this feature?

[PawelHaracz]

@shalinijoshi19 Any updates on this feature? I would like to use a rating on my bot.

[mutanttech]

@shalinijoshi19 is this released in 1.3. Are there any example to refer to implement this using C# and render on WebChat control?
Will it work on older versions of WebChat?

[kp101090]

This feature will be really helpful for our business critical workflow. Is this feature being actively worked on? If yes, is there any timeline for release?

[bleekbless]

Any update ?

[birix]

any update? I am implenet a chat bot in MSTeams, i need something like this.

[mohitkoul]

Lack of support responsible for death of Adaptive Card.