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 as `Translations` data type that the Fidesmo user interface should show. It also supports markdown, see examples below.

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": {
          "en": "**Home key** Created 2019-01-01",
          "sv": "**Hemnyckel** Skapad 2019-01-01"
        }
      }, {
        "image":"https://smartlockmanufacturer.com/image/keyoffice.png",
        "description": {
          "en": "**Office key** Created 2019-02-02",
          "sv": "**Kontornyckel** Skapad 2019-02-02"
        }
      }
    ]
  }

Example with text

This result would be achieved by the following input:


  {
    "instanceSpecificElements": [
      {
        "image":"https://happytransport.com/image/balance.png",
        "description": {
          "en": "**Pay as you go** €12,84",
          "es": "**Saldo prepagado** €12,84"
        }
      }, {
        "image":"https://happytransport.com/image/3month.png",
        "description": {
          "en": "**3 month ticket** Expires in 14 days",
          "es": "**Abono de 3 meses** Caduca en 14 días"
        }
      }
    ]
  }

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": {
          "en": "**30 day ticket** Valid through 13-12-2018"
          "es": "**Abono de 30 días** Válido hasta 13-12-2018"
        }
      }
    ]
  }