Add customer satisfactory (CSAT) card

[compulim]

Related #3702. Related #3621. Related #3620.

Fixes #2770.

Changelog Entry

Added

• Resolves #2770. Added customer satisfactory (CSAT) card, by @compulim, in PR #4899

Customer Satisfactory Card (CSAT card)

This is related to PR #4899.

Description

Power Virtual Agents and many customers implemented customer satisfactory (CSAT) cards using Adaptive Cards. However, as Adaptive Cards is designed for general purpose. Thus, the accessibility experience is not great for CSAT cards.

We are adding new attachment renderer for CSAT cards by leveraging https://schema.org/ReviewAction.

Design

We are using https://schema.org/ReviewAction for the representation of the CSAT card. The following is excerpt of the activity containing the CSAT card.

{
   "type": "message",
   "attachments": [
      {
         "content": {
            "@context": "https://schema.org",
            "@type": "ReviewAction",
            "actionStatus": "PotentialActionStatus",
            "description": "Great! Please rate your experience.",
            "resultReview": {
               "@type": "Review",
               "reviewRating": {
                  "@type": "Rating",
                  "ratingValue-input": {
                     "@type": "PropertyValueSpecification",
                     "valueName": "rate"
                  }
               }
            },
            "target": {
               "@type": "EntryPoint",
               "actionPlatform": "https://directline.botframework.com",
               "urlTemplate": "ms-directline-postback:?value={rate}"
            }
         },
         "contentType": "application/ld+json"
      }
   ]
}

Explanation of fields

Property	Description
content['@context']	Must be "https://schema.org".
content['@type']	Must be "ReviewAction".
content.actionStatus	If value is "CompletedActionStatus", the card is submitted. Otherwise, the card is ready to submit.
content.description	Text of prompting the user for rating.
content.resultReview['@type']	Must be "Review".
content.resultReview.reviewRating['@type']	Must be "Rating".
content.resultReview.reviewRating.ratingValue	Initial value of rating, must be 1 to 5 or undefined, default to undefined.
content.resultReview.reviewRating['ratingValue-input']	How ratingValue should be used as "input" parameters (a.k.a. request body). See https://schema.org/docs/actions.html for details.
content.resultReview.reviewRating['ratingValue-input']['@type']	Must be "PropertyValueSpecification".
content.resultReview.reviewRating['ratingValue-input'].valueName	The name used in URL template.
content.target	Must be URL or thing of "EntryPoint".
content.target['@type']	Must be "EntryPoint".
content.target.actionPlatform	Must be "https://directline.botframework.com".
content.target.urlTemplate	RFC 6570 URL template to send the action, see below.
contentType	Must be "application/ld+json".

Current designs and limitations:

• Subclasses are not supported. resultReview must be thing of "Review". "UserReview" and other subclass of "Review" is not supported
• Rating must be 1 to 5 stars. resultReview.reviewRating.bestRating and resultReview.reviewRating.worstRating are ignored
• If actionStatus is CompletedActionStatus, it indicates the review is submitted, thus, target is optional. Otherwise, review should be submittable and target must be specified
• Despite target could be a non-templated URL, it is highly recommended target is a thing of EntryPoint

Target URL

Currently, only ratingValue-input is supported. In the future, all fields in the Thing will be supported.

When the user change the rating, it will change the resultReview.reviewRating.ratingValue. In Schema.org actions, the ratingValue-input will be used to describe how the ratingValue is used in the request body of the action.

In the example payload, ratingValue-input.valueName is rate. When filling the target.urlTemplate, it will replace the variable rate with the user rating.

If the user rated 4, the URL template will be expanded as by replacing variable rate with 4:

- ms-directline-postback:?value={rate}
+ ms-directline-postback:?value=4

Thus, the postback activity payload will become:

{
   "channelData": {
      "postBack": true
   },
   "text": "4",
   "type": "message"
}

Note: when using postback for a string value, it will send via text field.

Followings are supported protocol and their query parameters:

Protocol	Parameters	Description
ms-directline-postback:	value	If valuetype is application/json, will send as JSON via activity.value, otherwise, will send as string via activity.text.
ms-directline-postback:	valuetype	If value is a complex object, specify "application/json". This is not recommended because non-compliance with Direct Line protocol.
ms-directline-imback:	title	Send as string via activity.text.
ms-directline-imback:	value	If title parameter is not specified, will send this value as activity.text.
ms-directline-messageback:	value	Send as complex object via activity.value.
ms-directline-messageback:	text	Send as string via activity.text.
ms-directline-messageback:	displaytext	String to display as in the sent message.

http:/https: are not supported at the moment.

For details of parameters, please refer to Direct Line Activity spec.

Specific Changes

• Added Customer Satisfactory attachment and its middleware
• Added useOpenURL for internal use on ms-directline-*: protocol
• Fixed bugs in RovingTabIndexProvider
  • END should set the focus on the last element in the list
• OrgSchemaThing should not typed out type: type is strictly for entities only
• Added docs/CUSTOMER_SATISFACTORY_CARD.md

• I have added tests and executed them locally
• I have updated CHANGELOG.md
• I have updated documentation

Review Checklist

This section is for contributors to review your work.

• Accessibility reviewed (tab order, content readability, alt text, color contrast)
• Browser and platform compatibilities reviewed
• CSS styles reviewed (minimal rules, no z-index)
• Documents reviewed (docs, samples, live demo)
• Internationalization reviewed (strings, unit formatting)
• package.json and package-lock.json reviewed
• Security reviewed (no data URIs, check for nonce leak)
• Tests reviewed (coverage, legitimacy)