Configure credential branding

Introduction

This guide will demonstrate how to customise a web credential with your branding using MATTR VII. This includes adding images and nested data that can be displayed by MATTR Mobile Wallet app to improve the user experience for the wallet holder. 

Prerequisites

Before you can customise your credential payload. You will need

  1. Your intended brand colour

  2. URLs of images for your logo, icon and watermark

Branding configuration

To apply branding to a web credential, a set of attributes can be optionally included in the credential request payload.

issuer block

Include a logoUrl and iconUrl attribute to define the logo and icon displayed on a credential in the wallet.

These attributes must be a publicly accessible URL to image files that are either .svg files (vector format) or .png/.jpg (raster format). We strongly recommend using vector images. Raster images, whilst supported, are currently displayed at 1x resolution and may look pixelated on some devices. Transparencies are allowed for svg or png images.

json
Copy to clipboard.
1"issuer": {
2    "id": "{Issuer DID}}",
3    "name": "{{Issuer Name}}", // this is the issuer name not the name of the credential
4    "logoUrl": "{{logo_image_url}}",
5    "iconUrl": "{{icon_image_url}}"
6},

credentialBranding block

Add a credentialBranding block to the credential payload to define the backgroundColor and watermarkImageURL.

json
Copy to clipboard.
1"credentialBranding": {
2    "backgroundColor": "{{colour_hex_value}}",
3    "watermarkImageUrl": "{{watermark_image_url}}"
4},

The following table outlines the full set of attributes utilised to render the credential branding correctly in the wallet.

The credential name and description are attributes that should be included at the root level of the credential.

Parameter

Purpose

Accepted data type and specifications

name

Credential Type:
To categorise the credential

String [1]

description

Credential Title:
A short, identifier label

Short string ~120 characters [2]

backgroundColor

Brand colour:
Colour of your credential card

Hex code

watermarkImageUrl

Watermark:
The pattern to be included in the card

full URL with scheme

245 × 150 px (.svg / .png / .jpg)

logoUrl

– or –

issuerLogoUrl

at root when using OIDC issuance

Issuer Logo:
Image of the issuer Logo

full URL with scheme

140 × 42 px (.svg / .png / .jpg)

iconUrl

– or –

issuerIconUrl

at root when using OIDC issuance

Issuer Icon:
Image of the Icon to be displayed in the card

full URL with scheme

32 × 32 px (.svg / .png / .jpg)

[1] 18 characters for 1 line, 36 characters for 2 lines when full array of credential feature icons are showing. Truncation occurs at any greater character string.

[2] 1 line max, 38 characters. Truncation occurs at any greater character string.

Example request

http
Copy to clipboard.
1POST https://YOUR_TENANT_SUBDOMAIN.vii.mattr.global/core/v1/credentials
json
Copy to clipboard.
1{
2    "issuer": {
3        "id": "did:key:z6MkndAHigYrXNpape7jgaC7jHiWwxzB3chuKUGXJg2b5RSj",
4        "name": "Zealopia Business Institute",
5        "logoUrl": "https://static.mattr.global/credential-assets/zealopia/web/logo.svg",
6        "iconUrl": "https://static.mattr.global/credential-assets/zealopia/web/icon.svg"
7    },
8    "name": "Course Credential",
9    "description": "Diploma in Management",
10    "credentialBranding": {
11        "backgroundColor": "#6303FF",
12        "watermarkImageUrl": "https://static.mattr.global/credential-assets/zealopia/web/watermark.svg"
13    },
14    "@context": [
15        "https://www.w3.org/2018/credentials/v1",
16        "https://schema.org"
17    ],
18    "subjectId": "did:key:z6MkfxQU7dy8eKxyHpG267FV23agZQu9zmokd8BprepfHALi",
19    "type": [
20        "VerifiableCredential",
21        "CourseCredential"
22    ],
23    "claims": {
24        "givenName": "Chris",
25        "familyName": "Shin",
26        "educationalCredentialAwarded": "Diploma in Management"
27    },
28    "persist": false,
29    "revocable": false
30}


Here is what the credential card looks like with and without branding in the MATTR Wallet:

Branded (left) and Unbranded (right) Credentials

Generate a web credential

The above branding configuration can be applied to Web Credentials generated through the MATTR VII platform.

Follow one of these tutorials alongside the branding configuration above to issue a Web Credential that includes your chosen branding: