Learn

Design an Apple digital pass template

An Apple digital pass template is required to format a Compact or Compact Semantic Credential as an Apple digital pass. This guide will show you how to design an Apple digital pass template. The design is similar whether you are creating a Compact or a Compact Semantic Apple digital pass template.

You can download the following sample files to better understand how to structure your own templates as you follow along this guide:

Apple digital pass template structure

You must bundle your digital pass assets into a file named template.zip which includes the following components:

  • pass.json: This required JSON file contains pass information and identifiers.

  • footer.png: displayed on the front of the pass near the barcode. Only available on boarding passes.

  • icon.png: Displayed in notifications and in emails that have a pass attached, and on the lock screen. When it is displayed, the icon gets a shine effect and rounded corners.

  • thumbnail.png: Displayed on the front of the pass. Only available on generic passes. For example, on a membership card, the thumbnail could be used for a cardholder picture.

  • logo.png: Displayed on the top-left corner of the front of the pass.

  • strip.png: Displayed behind the primary fields on the front of the pass. Only available on store cards, event tickets and coupons.

  • Different sized images (e.g. @2x, @3x) can be included in the bundle.

  • The maximum bundle size is 1MB.

Read more about the visual layout of Apple digital passes and suggested design guidelines here.

pass.json

The contents of pass.json are described in detail on this page and are shown in the following example:

json
Copy to clipboard.
1{
2  "formatVersion": 1,
3  "organizationName": "Advanced Safety Training",
4  "description": "HS.278 Working at Heights Certification",
5  "labelColor": "rgb(45, 45, 45)",
6  "foregroundColor": "rgb(45, 45, 45)",
7  "backgroundColor": "rgb(202, 202, 202)",
8  "sharingProhibited": true,
9  "voided": false,
10  "barcode": {
11    "format": "PKBarcodeFormatQR",
12    "messageEncoding": "iso-8859-1",
13    "message": "{{encoded}}",
14    "altText": "Exp: {{ date decoded.expiry 'dd MMM yyyy' }}"
15  },
16  "storeCard": {
17    "headerFields": [
18      {
19        "key": "codeHeader",
20        "label": "Certification",
21        "value": "{{ decoded.code }}"
22      }
23    ],
24    "primaryFields": [],
25    "secondaryFields": [
26      {
27        "key": "nameSecondary",
28        "label": "Name",
29        "value": "{{ decoded.name }}"
30      },
31      {
32        "key": "certificationLevelSecondary",
33        "label": "Certified for",
34        "value": "{{ decoded.certificationLevel }}"
35      }
36    ],
37    "auxiliaryFields": [],
38    "backFields": [
39      {
40        "key": "nameBack",
41        "label": "Name",
42        "value": "{{ decoded.name }}"
43      },
44      {
45        "key": "certificationNameBack",
46        "label": "Certification",
47        "value": "{{ decoded.certificationName }}"
48      }
49    ]
50  }
51}

  • formatVersion (required): File format version. The value must be 1.

  • organizationName (required): Name of the organisation that created and signed the pass.

  • description (required): Pass description, used by iOS accessibility technologies.

  • labelColor (optional): Label text color, specified as a CSS-style RGB triple. When omitted, label color is automatically determined.

  • foregroundColor (optional): Foreground pass color, specified as a CSS-style RGB triple. When omitted, label color is automatically determined.

  • sharingProhibited: Set to false to disable the Share Pass option

  • voided: Indicates that the pass is void. For example, a one time use coupon that has been redeemed. The default value is false.

  • barcode:

    • format: Must be set to PKBarcodeFormatQR.

    • messageEncoding: Must be set to iso-8859-1.

  • Style Keys: A style key is required and corresponds with the pass's style. Can be either storeCard (as shown in the example above), generic, eventTicket, coupon or a boardingPass. Each style key has different components. Below is an example of a storeCard pass structure:

    • headerFields: Fields to be displayed in the header on the front of the pass. Use header fields sparingly; unlike all other fields, they remain visible when a stack of passes is displayed.

    • primaryFields: Fields to be displayed prominently on the front of the pass.

    • secondaryFields: Fields to be displayed on the front of the pass.

    • auxiliaryFields: Additional fields to be displayed on the front of the pass.

    • backFields: Fields to be on the back of the pass.

    • transitType: this is required for boarding passes and not allowed otherwise. Must be one of the following: PKTransitTypeAir, PKTransitTypeBoat, PKTransitTypeBus, PKTransitTypeGeneric, PKTransitTypeTrain.

    • Each field must contain a set of standard field dictionary keys:

      • key: the key must be unique within the scope of the entire pass.

      • label: label text for the field.

      • value: the value of the field.

What's next?

After designing your template locally, use it to create a MATTR VII Apple digital pass template.