Article

Supporting Semantic Tags in Wallet Passes

Allow the system to offer Wallet passes to users intelligently by adding machine-readable metadata.

Overview

The user-visible information on Wallet passes can be augmented with machine-readable metadata known as semantic tags. The metadata in semantic tags helps the operating system better understand Wallet passes and offer relevant installed passes to the user.

Semantic tags can be added to all types of Wallet passes, but some tags are only applicable to specific types such as event tickets, boarding passes, and store cards. For a full list of all tags and their associated pass types, see Supported Semantic Tags.

For general information on creating a pass and working with pass.json, see the Wallet Developer Guide.

Add Semantic Tags

Add machine-readable semantic tags to Wallet passes with an optional semantics dictionary. This dictionary can be added at the root of pass.json or as a top-level key contained in the headerFields, primaryFields, secondaryFields, auxiliaryFields, or backFields dictionaries.

The operating system uses the semantic tag data to offer a pass at the most appropriate time. For example, semantic tags added to a movie pass could take effect when the user arrives in the theater at the scheduled time by showing a Siri suggestion to enable Do Not Disturb mode for the duration of the film.

In order for the system to send the suggestion to set Do Not Disturb, the eventType must be set to indicate that the pass is a movie ticket and the silenceRequested, eventStartDate, eventEndDate, and venueLocation tags must be added.

Semantic tag data may be added entirely in one semantics dictionary to the root of pass.json, like this:

"semantics": {
    "eventType": "PKEventTypeMovie",
    "silenceRequested": true,
    "eventName": "Animated Movie",
    "eventStartDate": "1995-11-22T19:00-08:00",
    "eventEndDate": "1995-11-22T20:21-08:00",
    "venueName": "Steve Jobs Theater",
    "venueLocation": {
        "latitude": 37.330886,
        "longitude": -122.007427
    },
    "seats": [
        {
            "seatRow": "7",
            "seatNumber": "4",
            "seatIdentifier": "R07S04"
        },
        {
            "seatRow": "7",
            "seatNumber": "5",
            "seatIdentifier": "R07S05"
        }
    ]
}

Alternatively, semantic data can be added to enhance the individual fields in a pass. For example, the eventType and silenceRequested keys could be added to a semantics dictionary in the root of pass.json:

  "semantics": {
    "eventType": "PKEventTypeMovie",
    "silenceRequested": true
  }

Then, because the primary field on this movie ticket pass shows the event and venue details, the eventName, venueName, and venueLocation keys could be added to the semantics dictionary in primaryFields:

"primaryFields": [
    {
        "key": "event",
        "label": "Steve Jobs Theater",
        "value": "Animated Movie",
        "semantics": {
            "eventName": "Animated Movie",
            "venueName": "Steve Jobs Theater",
            "venueLocation": {
                "latitude": 37.330886,
                "longitude": -122.007427
            }
        }
    }
]

Finally, a secondary field on this pass shows the length of the movie. Add the eventStartDate and eventEndDate to represent that semantically:

"secondaryFields": [
    {
        "key": "runtime",
        "label": "Run Time",
        "value": "1:21",
        "semantics": {
            "eventStartDate": "1995-11-22T19:00-08:00",
            "eventEndDate": "1995-11-22T20:21-08:00"
        }
    }
]

The functionality of semantic tags is not affected by whether the semantic tags are added to the root of the pass, or to one of the field dictionaries. Add the semantic tags wherever is most convenient when generating your passes.

To provide users with the best experiences after installing your passes, add as much semantic data as you have for the list of all possible semantic tags below.

Supported Semantic Tags

Below is a full list of key names and value types for all available semantic tags. All keys are optional and the types are defined in Value Types for Semantic Tag Keys.

Semantics for All Passes

totalPrice

Type: currencyAmount. The total price for the pass.

Semantics for Boarding Passes and Events

duration

Type: number. The duration of the event or transit journey, in seconds.

seats

Type: array of seat dictionary. Seating details for all seats at the event or transit journey.

silenceRequested

Type: boolean. Request the user's device to remain silent during a the event or transit journey. This key may not be honored and the system will determine the length of the silence period.

Semantics for All Boarding Passes

departureLocation

Type: location. The geographic coordinates of the transit departure, suitable to be shown on a map. If possible, precise locations are more useful to travelers, such as the specific location of the gate at an airport.

departureLocationDescription

Type: string. A brief description of the departure location. For example, for a flight departing from an airport whose code is "SFO", "San Francisco" might be an appropriate description.

destinationLocation

Type: location. The geographic coordinates of the transit destination, suitable to be shown on a map.

destinationLocationDescription

Type: location. A brief description of the destination location.

transitProvider

Type: string. The name of the transit company.

vehicleName

Type: string. The name of the vehicle being boarded, such as the name of a boat.

vehicleNumber

Type: string. The identifier of the vehicle being boarded, such as the aircraft registration number or train number.

vehicleType

Type: string. A brief description of the type of vehicle being boarded, such as the model and manufacturer of a plane or the class of a boat.

originalDepartureDate

Type: date. The original scheduled date and time of departure.

currentDepartureDate

Type: date. The updated date and time of departure, if different than the original scheduled date.

originalArrivalDate

Type: date. The original scheduled date and time of arrival.

currentArrivalDate

Type: date. The updated date and time of arrival, if different than the original scheduled date.

originalBoardingDate

Type: date. The original scheduled date and time of boarding.

currentBoardingDate

Type: date. The updated date and time of boarding, if different than the original scheduled date.

boardingGroup

Type: string. A group number for boarding.

boardingSequenceNumber

Type: string. A sequence number for boarding.

confirmationNumber

Type: string. A booking or reservation confirmation number.

transitStatus

Type: string. A brief description of the current status of the vessel being boarded, such as "On Time" or "Delayed". For delayed statuses, provide currentBoardingDate, currentDepartureDate, and currentArrivalDate where available.

transitStatusReason

Type: string. A brief description explaining the reason for the current transitStatus, such as "Thunderstorms".

passengerName

Type: personNameComponents. The passenger's name.

membershipProgramName

Type: string. The name of a frequent flyer or loyalty program.

membershipProgramNumber

Type: string. The ticketed passenger's frequent flyer or loyalty number.

priorityStatus

Type: string. The priority status held by the ticketed passenger, such as "Gold" or "Silver".

securityScreening

Type: string. The type of security screening that the ticketed passenger will be subject to, such as "Priority".

Semantics for Airline Boarding Passes

flightCode

Type: string. The IATA flight code, such as "EX123".

airlineCode

Type: string. The IATA airline code, such as "EX" for flightCode "EX123".

flightNumber

Type: number. The numeric portion of the IATA flightCode, such as 123 for flightCode "EX123".

departureAirportCode

Type: string. The IATA airport code for the departure airport, such as "SFO" or "SJC".

departureAirportName

Type: string. The full name of the departure airport, such as "San Francisco International Airport".

departureTerminal

Type: string. The terminal name or letter of the departure terminal, such as "A". Do not include the word "Terminal".

departureGate

Type: string. The gate number or letters of the departure gate, such as "1A". Do not include the word "Gate".

destinationAirportCode

Type: string. The IATA airport code for the destination airport, such as "SFO" or "SJC".

destinationAirportName

Type: string. The full name of the destination airport, such as "San Francisco International Airport".

destinationTerminal

Type: string. The terminal name or letter of the destination terminal, such as "A". Do not include the word "Terminal".

destinationGate

Type: string. The gate number or letters of the destination gate, such as "1A". Do not include the word "Gate".

Semantics for Train and Other Rail Boarding Passes

departurePlatform

Type: string. The name of the departure platform, such as "A". Do not include the word "Platform".

departureStationName

Type: string. The name of the departure station, such as "1st Street Station".

destinationPlatform

Type: string. The name of the destination platform, such as "A". Do not include the word "Platform".

destinationStationName

Type: string. The name of the destination station, such as "1st Street Station".

carNumber

Type: string. The car number.

Semantics for All Event Tickets

eventName

Type: string. The full name for the event, such as the title of a movie.

venueName

Type: string. The full name of the venue.

venueLocation

Type: location. The geographic coordinates of the venue.

venueEntrance

Type: string. The full name of the entrance to use to gain access to the ticketed event, such as "Gate A".

venuePhoneNumber

Type: string. The phone number for enquiries about the venue's ticketed event.

venueRoom

Type: string. The full name of the room where the ticketed event is taking place.

eventType

Type: string. The event type. The value must be one of the following: "PKEventTypeGeneric", "PKEventTypeLivePerformance", "PKEventTypeMovie", "PKEventTypeSports", "PKEventTypeConference", "PKEventTypeConvention", "PKEventTypeWorkshop", or "PKEventTypeSocialGathering".

eventStartDate

Type: date. The date and time the event starts.

eventEndDate

Type: date. The date and time the event ends.

artistIDs

Type: array of string. The Adam IDs for the artists performing, in decreasing order of significance.

performerNames

Type: array of string. The full names of the performers and opening acts, in decreasing order of significance.

genre

Type: string. The genre of the performance.

Semantics for Sports Event Tickets

leagueName

Type: string. The unabbreviated league name for a sporting event.

leagueAbbreviation

Type: string. The abbreviated league name for a sporting event.

homeTeamLocation

Type: string. The home location of the home team.

homeTeamName

Type: string. The name of the home team.

homeTeamAbbreviation

Type: string. The unique abbreviation of the home team's name.

awayTeamLocation

Type: string. The home location of the away team.

awayTeamName

Type: string. The name of the away team.

awayTeamAbbreviation

Type: string. The unique abbreviation of the away team's name.

sportName

Type: string. The commonly used local name of the sport.

Semantics for Store Card Passes

balance

Type: currencyAmount. The balance redeemable with the pass.

Value Types for Semantic Tag Keys

The value types for the semantic tag keys are defined as follows:

string

A JSON string, which may be localized.

number

A JSON number.

date

An ISO 8601 formatted date represented as a JSON string. An example might look like this: "2018-09-12T09:41:00-08:00"

currencyAmount

A dictionary consisting of an ISO 4217 currency code in the currencyCode key and an amount in the amount key. Both values must be JSON strings. An example might look like this: {"currencyCode:"USD", "amount":"12.50"}

location

A JSON dictionary consisting of a location specified as two JSON numbers with the keys latitude and longitude. An example might look like this: {"latitude":37.334887, "longitude":-122.008996}

personNameComponents

A JSON dictionary with keys that will be provided as components to NSPersonNameComponents. All keys are optional. An example might look like this: {"givenName":"John", "familyName":"Appleseed"}

seat

A dictionary with one or more of the following JSON string keys. Valid keys are: seatSection, seatRow, seatNumber, seatIdentifier, seatType, seatDescription. An example might look like this: {"seatRow":"1", "seatNumber":"A", "seatType":"Economy"}

See Also

Passes

class PKPass

An object that represents a single pass.

class PKPassLibrary

Provides an interface to the user’s library of passes.

class PKTransitPassProperties

The properties of a transit pass.

class PKSuicaPassProperties

The properties of a Suica pass.

class PKObject

An opaque type that acts as the superclass for the PKPass class.