# Client Specification
# Version 2.0.0
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 (opens new window) when, and only when, they appear in all capitals, as shown here.
# Introduction
This document defines how dashboard or mobile application (later just client) should communicate with server. Whole interaction is divided into two flows:
# Definitions
# Application
An application is 3rd system that want embed a content into Client.
# Client
A client is frontend responsible for rendering addons. In context of smartsupp it can be Dashboard or Mobile App.
# Section
A section is place in frontend where addon can be rendered. Addons and components MAY be visualized differently for every section or section MAY not be able to render all components and can skip rendering. Sections MUST be described and defined how to interact with components.
# Addon
An addon is a group of components described by an Application and rendered by a Client.
# Component
A component is well typed JSON definition of some UI part like buttons, headers, tables, grids, etc. A Client is responsible for rendering of components. Different part of UI can render components differently. That means, an Application define structure and a Client define how to present it in product.
# Config Flow
Client MUST initiate config flow at least once per load by calling endpoint /list. List endpoint returns all available addons with configurations.
When request failed client SHOULD consider all addons as not installed.
When some addon contains non-empty property errors then other properties SHOULD be ignored and MUST be considered as not installed.
# Config Request
Client MAY optionally send query parameters lang or timezone.
# Config Response
# Property sections
Defines which parts of dashboard an addon MUST be rendered.
# Property title
Should be used as addon's title if title should be rendered for some section. Server is responsible to always provides title, even not specified by app.
# Property name
Name of the application. Should not be used as title, because this string is not translatable.
# Render Flow
Client MUST initiate render flow for every addon that have enabled specific section and section is supported by client. Client decide where section should be
rendered. To get render data client MUST call endpoint /{id}/render/{section}.
# Render Request
Client MAY optionally send query parameters lang or timezone.
# Property context
Request MUST contain context object with values specific for every section.
# Property state
Request MUST contain state returned from last call of render call of some addon or in case of first call state must be empty object {}. Client MUST NOT
modify or use this object. State object is key-value structure where value MAY contain boolean, number, string, null
, object or array of those types.
# Property action
Request MUST contain action when user execute notification-based action and MUST contain name of the action.
# Render Response
In case of non-success response with status other than 200, if its appropriate client SHOULD render some warning or MAY not render addon at all. Client MAY show reload button performing call render method again.
# Property errors
When response contains non-empty array errors all other properties SHOULD be ignored. Client MAY render some general error or don't render addon at all.
# Property redirect
Allows to an Application perform redirection to some page, can be used to implement frontend OAuth.
When response contains property redirect client MUST perform redirect to given page. If redirect is performed in same page then other properties can be
ignored otherwise response MUST be processed by specification.
# Property components
List of objects that client should properly render.
When errors or redirect is not present client MUST perform render based on received components. If components is empty array then client SHOULD hide addon
and don't render any content or wrapping box. Empty array MUST NOT be considered as error.
When client receive components that are not supported or client don't know how to render then, client MUST skip rendering ONLY for unsupported components. Other supported components MUST be rendered.
# Property state
An application may return state object and expecting that state object will be delivered back to app in next re-render call.
Data in property state must be stored within rendered addon, and when is needed to perform render again a state MUST be unchanged send back to render
request.
Client MUST NOT modify or use this object. State object is key-value structure where value MAY contain boolean
, number, string, null, object or array of those types.
# Property context
Represent partial data of context sent in request. This data which Application sending back represents important values for addon's content and in case of
change of this data addon must perform re-render. In other words changes requires content invalidation.
When context is not null client MUST consider this object as values that in case of change a render method MUST be called again.
Data in this object is usually returned as partial of data that was sent in request. Client MUST execute re-render only for changes of this object, not whole context of addon.
# Property events
TODO:
# Sections
TODO:
# chat_info_panel
TODO:
# chatbot_action
TODO:
# visitor_info_panel
TODO: