A user interaction request is composed by an array fields. Each element of fields is described in the following table:

And finally, this is the list of type and format supported:

Data validation

The application that the user is using is expected to validate the context to at least match the expected return format and size as per the above table.

API

The Service Provider should POST a JSON formatted request to the /userInteraction endpoint similar to the following structure:

{
          "fields": [{
            "label": {
              "en": "English label",
              "se": "Swedish label"
            },
            "id": "any_field_id",
            "type": "edit",
            "format": "number"
            ...
          }],
          "encrypted": "false"
        }

Result

The userInteraction request will yield an operationId and UUID. After some time (the user is filling in the required information) the Service Provider will receive the ID of the operation, a status code and the results. The result will be in JSON and formatted like for example:

{
          "operationId": "0276F6A6-E21C-4307-B63C-1F70D6C36045",
          "sessionId": "C4D14B40-8F1C-456C-A7E2-4069B5F8CBBC",
          "statusCode": 200,
          "fields": {
            "any_field_id": "field_string_value"
          }
        }

Encryption

It is possible to specify that the data submitted by the user travels encrypted from the mobile client to the Service Provider, so that sensitive data such as payment card details cannot be compromised.

Encrypted user interactions are done with a combination of symmetric and asymmetric encryption. An ephemeral AES key is generated by the client and used to encrypt the /userInteraction data. Then, this key is encrypted with the public key of the Service Provider. The client returns the ephemeral-key encrypted data, and the public-key encrypted ephemeral key. Upon receival, the Service Provider decrypts the ephemeral key with its private key, and then, with the newly decrypted ephemeral key, decrypts all the data.

To activate encryption the Service Provider needs to pass a public key as a certificate along with the service description:

{
          "title": "The encrypted userInteraction service",
          "description": "This is an encrypted userInteraction service.
          Keep out of reach from children.",
          ...
          "certificate": [A X.509 certificate encoded as ASN1.DER]
        }

To encrypt a /userInteraction the Service Provider must also set the encrypted flag to true like for example:

{
          "fields": [{
            "label": {
              "en": "English label"
            },
            "id": "any_field_id",
            "type": "edit",
            "format": "number",
            ...
          }],
          "encrypted": "true"
        }

The encrypted data together with the encrypted ephemeral key will be sent back as previously described in the Result section but with the fields being encrypted and the additional field "ephemeralKey":

{
          "operationId" : "0276F6A6-E21C-4307-B63C-1F70D6C36045",
          "sessionId" : "C4D14B40-8F1C-456C-A7E2-4069B5F8CBBC",
          "statusCode": 200,
          "fields": {
            "any_field_id": [byte array in a hex form]
          },
          "ephemeralKey": [byte array in a hex form]
        }

The "ephemeralKey" is encrypted using RSA/OAEP algorithm with a SHA512 for hashing and MGF1 Padding (RSA/NONE/OAEPWithSHA512AndMGF1Padding). To obtain field data one needs to decrypt the "ephemeralKey" first and then using the obtained key to decrypt each field separately using AES/CBC algorithm with a PKCS7 padding (AES/CBC/PKCS7Padding). As initialization vector an array with 16 zero bytes can be used.

Action

By sending list of action to the client the Service Provider can make the client perform a sequence of actions or a single action, for example make a call. The structure of the action object is described in the following table:

When the client receives an action it will complete it to the best of it’s ability, however, sometimes the client is unable to complete the action. For example a UI client running on the user’s phone will have no problem calling a phone number, however, a tablet UI client might not be able to do the same if it can’t do calling. In this case the tablet UI client will instead show the user the description text as well as any passed parameters, so that the user can compete the action on another device.

Names

API

The Service Provider should POST a JSON formatted request to the /userInteraction endpoint similar to the following structure:

{
          "actions": [{
            "description": {
              "en": "English description",
              "se": "Swedish description"
            },
            "name": "any_action_name",
            "parameters": {
              "parameter-name-1": "parameter_value",
              "parameter-name-2": "parameter_value"
            }
          }],
          "encrypted": "false"
        }

Call example

{
          "actions": [{
            "description": {
              "en": "Call this number +46XXXXXXXXX"
            },
            "name": "phonecall",
            "parameters": {
              "number": "+46XXXXXXXXX"
            }
          }]
        }

The result would be that the UI client calls the number +46XXXXXXXXX.

Android app example

{
          "actions": [{
            "description": {
              "en": "Open XYZ app"
            },
            "name": "open-android-app",
            "parameters": {
              "package": "com.example.xyz",
              "qualified-app-name": "com.example.xyz.XyzApp",
              "extra-text-value": "example1234"
            }
          }]
        }

The result would be that the UI client opens the XyzApp with the extra-text-value attached if the app is installed. Otherwise the UI client would search any available app stores for com.example.xyz and ask the user to install the app.