# SmartWallet Document Cards
:::info
Needed `web-agent` version: `~0.3.1-rc`
Needed `SmartWallet` version: `~2.2.0-50`
:::
:::info
This document assumes familiarity with the Agent's API
:::
:::warning
The new *Document card* designs are currently in *Alpha*, which means you may encounter UI bugs.
:::
## Rendering cards
:::warning
**Warning**: If an offer has a lot of fields, it may be that no QR code will be returned. Instead the agent will only return the JWT. The reason for that is that the such an amount of data cannot be fit into a scannable QR code. This will be fixed in future iterations, where the QR codes will not increase based on the data they include.
:::
### Types of cards
#### Offer card
When the issuer offers the holder a *Verifiable Credential*, it will be represented in the SmartWallet as an *Offer card*. The card doesn't display any values, only the labels, the name of the credential and the issuer's name.
<img src=https://i.imgur.com/VNUWZx4.jpg width="50%" style="border-radius: 14px; margin-bottom: 20px">
#### Share card
When the verifier requests a *Verifiable Credential*, it will be displayed in the SmartWallet as a *Share card*. In contrast to the *Offer card*, it shows the values of the preview fields, as well as the holder's name and photo *(if available)*.
<img src="https://i.imgur.com/rcjCbOL.jpg" width="50%" style="border-radius: 14px; margin-bottom: 20px">
#### Document card
After the issuer's offer was accepted by the holder, the issued *Verifiable Credential* will be displayed in the *Documents* section of the SmartWallet. The *Document card* itself shows the all the available stylings/information, such as: *issuer icon*, *document name*, *holder name*, *holder photo*, *preview fields*, *context icons*, *background color*, *background image*, etc. Furthermore, all the fields contained in the *Verifiable Credential* can be seen in the *Document detailed view*, which can be accessed by either pressing on the card or going through the *Kebab menu (header)* -> *Info* -> *Document detailed view*.
<img src="https://i.imgur.com/2fN5lWG.jpg" width="50%" style="border-radius: 14px; margin-bottom: 20px">
![]()
### Issuer icon
<img src="https://i.imgur.com/L5g9CFL.jpg" width="50%" style="border-radius: 14px; margin-bottom: 20px">
All *cards* can have an issuer icon which is displayed in the header by the *credential name*. Nevertheless, this icon is not defined during the issuance process. Instead, the issuer has to upload a *public profile* associated with their identity. To do this, the issuer has to send a *POST* request to the agent's `/tenant/{did}/profile` endpoint with the following body *(replaced with actual values)*:
```json=
{
"name": "string",
"logoUrl": "string",
"websiteUrl": "string",
"description": "string"
}
```
As such, the SmartWallet will use the `logoUrl` property from the *public profile* to render the issuer icon on the card.
:::warning
The SmartWallet is caching the `public profiles` the first time the holder interacts with the issuer. As such, further updates to the issuer's logo will not be reflected after the holder was already issued a credential. As a result, it's recommended to set the issuer logo as the first step. Furthermore, this issue will be fixed in further iterations by allowing to set the issuer logo in the template.
:::
### Preview fields
<img src="https://i.imgur.com/SOTf59f.png" width="50%" style="border-radius: 14px; margin-bottom: 20px">
When defining a credential, the issuer has the possibility to define which fields would be previewed on the card by using the `showInPreview` property when defining a template. Furthermore, when offering or sharing a credential, the preview fields allow the user to visually identify the credential (e.g. in a cinema ticket this could be the venue, the row and the seats; in a driving license - birth date, driving privileges, etc.). Additionally, fields can have a `label` property, which would be shown on top of the value and should be a human-readable label for the field. An example of a template (and offer) and how it looks like on the card can be seen below.
:::info
If the value of the first field in the row is longer than 14 characters *(may be subject to change)*, the second field in the row will not be rendered. Instead, the first field's value will take up the remaining space.
:::
:::info
If no preview fields are defined, all the fields will become preview-able in the order defined in the template.
:::
:::info
When defining the offer, the `includeValueInPreview` property defines whether the value will be included in the offer. Nevertheless, the value will not be shown in the *Offer card* for the time being. Instead, a placeholder will be used. As a result, it's recommended to keep `includeValueInPreview` false in order to not increase to size of the QR code unnecessarily.
:::
```json=
// Template
{
{...},
"name": "Preview fields",
"claimsProperties": [
{
"name": "preview_field_1",
"label": "Preview field 1",
"type": "text",
"isOptional": true,
"showInPreview": true
},
{
"name": "preview_field_2",
"label": "Preview field 2",
"type": "text",
"isOptional": true,
"showInPreview": true
},
{
"name": "preview_field_3",
"label": "Preview field 3",
"type": "text",
"isOptional": true,
"showInPreview": true
},
{
"name": "non_preview_field_1",
"label": "Non-preview field 1",
"type": "text",
"isOptional": true,
"showInPreview": false
},
]
}
```
```json=
// Offer
{
{...},
"templatesInfo": [
{
"templateId": "6c49fa44-a0fb-49b7-92c8-40eb684c0fca",
"claimPropertyToValueMap": [
{
"property": "preview_field_1",
"value": "Preview value",
"includeValueInPreview": true // Whether to preview the value in the offer
},
{
"property": "preview_field_2",
"value": "Preview value",
"includeValueInPreview": true
},
{
"property": "preview_field_3",
"value": "Preview value",
"includeValueInPreview": true
},
{
"property": "non_preview_field_1",
"value": "Non-preview value",
"includeValueInPreview": true
}
]
}
]
}
```
### Holder photo
<img src="https://i.imgur.com/Lp9Dl1D.jpg" width="50%" style="border-radius: 14px; margin-bottom: 20px">
Rendering the holder photo on the Document card can be achieved by having a claim in the Verifiable Credential with the `photo` property. As such, when defining the template, the `type` of the property has to be `base64` if the image is a base64 encoded `png/jpg`. In case the image is hosted remotely behind a url, the `type` must be `text`. An example of a template with the claim definition for the `photo` can be seen below.
```json=
// Example of a claim definition in a template
{
{...},
"claimsProperties": [
{
"name": "photo",
"label": "Photo",
"type": "base64",
"isOptional": true,
"showInPreview": true
},
{...}
]
}
```
```json=
// Example of an offer containing a photo property
{
{...},
"templatesInfo": [
{
{...},
"claimPropertyToValueMap": [
{
"property": "photo",
"value": "data:image/png;base64,iVBORw0KGgoAAAA...",
"includeValueInPreview": false
}
]
}
]
}
```
### Image fields
<img src="https://i.imgur.com/QIBaZPd.jpg" width="50%" style="border-radius: 14px; margin-bottom: 20px; margin-right: 50px;">
<img src="https://i.imgur.com/3wG5Rxk.jpg" width="37%" style="border-radius: 14px; margin-bottom: 20px">
Similarly to the holder's photo, the issuer can include other image fields in the properties which the SmartWallet can render. To do so, when defining the field properties in the template the issuer can set the `type` to `base64`. As a result, the image will be rendered in the *Document details* screen. Additionally, the *Document card* will add an icon to the footer which will indicate whether the document has any images included.
```json=
{
"name": "Image fields",
{...},
"claimsProperties": [
[...],
{
"name": "barcode",
"label": "Access barcode",
"type": "base64",
"isOptional": true,
"showInPreview": false
}
]
}
```
### Holder name
<img src="https://i.imgur.com/Rr28usz.jpg" width="50%" style="border-radius: 14px; margin-bottom: 20px">
The holder name can be shown on the card in two ways. First, by using the property names `givenName` and `familyName`, the SmartWallet will render the holder's name with a highlighted font in a special field, as can be seen above. Second, if other property names are used (e.g. `firstName/lastName`, `name`, etc.), they will be rendered as ordinary fields on the card (if previewed). This section focuses on the first way. As such, the card includes the concatenated `givenName` and `familyName` properties. A template example of the first way can be seen below.
:::info
In future iterations, property names such as `firstName`, `lastName`, `name`, etc. may be used for rendering the holder's name on a special field.
:::
:::info
If the holder's name overflows to the second line, less preview fields will be rendered.
:::
```json=
// Template example
{
{...},
"claimsProperties": [
{
"name": "givenName", // Erika
"label": "Given name",
"type": "text",
"isOptional": true,
"showInPreview": true
},
{
"name": "familyName", // Mustermann
"label": "Family name",
"type": "text",
"isOptional": true,
"showInPreview": true
}
]
}
```
### Background color
<img src="https://i.imgur.com/DIdKX8C.jpg" width="50%" style="border-radius: 14px; margin-bottom: 20px">
*Document cards* can be enhanced with a background color. This can be defined in the template with the `backgroundColor` style property. The value should be either a hex (e.g. `#000000`) or rgb/rgba (e.g. `rgb(0,0,0)`) color.
:::info
The background color may result in less preview fields rendered on the card.
:::
:::info
The `backgroundImage` style property will always override the `backgroundColor`, if both are defined in the template.
:::
```json=
{
"name": "Background color preview",
"credentialStyles": {
"backgroundColor": "#101010"
},
{...},
"claimsProperties": [...]
}
```
### Background image
<img src="https://i.imgur.com/0FhViAK.jpg" width="50%" style="border-radius: 14px; margin-bottom: 20px">
Similarly, *Document cards* can be enhanced with a background image. This can be defined in the template with the `backgroundImage` style property. The value should be either a hosted image *(url)* or a *base64* encoded image *(currently not recommended since the size of the offer will not fit into a QR code)*.
:::info
The background image may result in less preview fields rendered on the card.
:::
```json=
{
"name": "Background image preview",
"credentialStyles": {
"backgroundImage": {
"uri": "https://jolocom.io/wp-content/uploads/2022/02/Jolocom-consulting-identity-management.png",
"alt": "Document background"
}
},
{...},
"claimsProperties": [...]
}
```
### Context icons
<img src="https://i.imgur.com/mTPVBWu.jpg" width="50%" style="border-radius: 14px; margin-bottom: 20px">
*Context icons* allow the issuer to add some visual hints to the *Document card's* footer. There can be at most 2 icons in the footer, both of which have to be hosted images *(url)*. As such, to add *context icons* to the card, the issuer can use either the `thumbnailImage` or `heroImage` style properties. Currently, the SmartWallet doesn't distinguish between them, both being rendered in a similar way. A template example with *context icons* can be seen below.
```json=
{
"name": "Context icons preview",
"credentialStyles": {
"heroImage": {
"uri": "https://jolocom.io/wp-content/uploads/2022/02/Jolocom-Products-icon01-150x150.png?crop=1",
"alt": "Hero image"
},
"thumbnailImage": {
"uri": "https://jolocom.io/wp-content/uploads/2022/02/Jolocom-Products-icon02-150x150.png?crop=1",
"alt": "Thumbnail image"
},
{...}
},
{...},
"claimsProperties": [...]
}
```
Sign in with Wallet
Connect another wallet