Instance specific elements
A Service Provider might want to display information about the contents of an
instance of their app, instead of always presenting the same information to
the users. For example a public transport organization might want to show a
user the list of tickets that are available only on that user's Fidesmo
device. For this Fidesmo has created the instanceSpecificElements
object.
The structure of the object that the client expects is a JSON document of
instanceSpecificElements each consisting of two optional
values:
| Parameter | Explanation |
|---|---|
| image | An optional URL string pointing to a JPEG or PNG image that the Fidemso user interface should show. |
| description | An optional description in markdown format that the Fidesmo user interface should show. |
While the fields are optional to Fidesmo user interfaces and the design might differ between them there are generally two places where the instance specific elements could be shown:
- The app screen
- The finishing screen of a Service Delivery.
The app screen
By default, the mobile client will display the same information for apps:
A title, a description and an image (see Branding).
However, the Service Provider may want to display information specific to the
instance of their app on a device. For example a public transport organization
might want to declare a list of tickets so that the user can see which tickets
are on their Fidesmo device when viewing the app in a Fidesmo user interface.
For this Fidesmo offers the instanceSpecificElements API. The
Service Provider publishes an endpoint on their backend and provides the URL
through the instanceSpecificElements API. When a Fidesmo user
interface wants to it can request the elements through the Fidesmo backend to
the Service Provider endpoint providing only the CIN of a device. The service
provider then decides which elements it wants to respond with and they are
funneled through the Fidesmo backend to the Fidesmo user interface.
The structure of the call to this endpoint is as follows:
[configured instanceSpecificElements endpoint]/[Fidesmo CIN]
The Fidesmo CIN in the above call is the Fidesmo Card Identification Number. See the CIN page for more information.
While this API is open to any Service Provider most should not need to use
it. There are more simple app states, like installed and
suspended which should fulfill most use cases.
Example with image and text
This result would be achieved by the following input:
{
"instanceSpecificElements": [
{
"image":"https://smartlockmanufacturer.com/image/keyhome.png",
"description":"**Home key**
Created 2019-01-01"
}, {
"image":"https://smartlockmanufacturer.com/image/keyoffice.png",
"description":"**Office key**
Created 2019-02-02"
}
]
}
Example with text
This result would be achieved by the following input:
{
"instanceSpecificElements": [
{
"image":"",
"description":"**Pay as you go**
€12,84"
}, {
"image":"",
"description":"**3 month ticket**
Expired in 14 days"
}
]
}
The finishing screen of a Service Delivery.
Once a delivery has been finished a Service Provider might want to tell the
user what has been put on the device. For example a public transportation
organization might want to show the user the ticket that was just loaded onto
the Fidesmo device. The Service Provider can provide
instanceSpecificElements as a parameter through the
/service/completed API.
Example with image and text
This result would be achieved by the following input:
{
"instanceSpecificElements": [
{
"image":"https://super-pto.com/image/ticket.png",
"description":"**30 day ticket**
Valid through 13-12-2018"
}
]
}