Terminology
Barcode Payload
This is the actual data encoded within the barcode. Think of it as the hidden information that the barcode scanner reads. This data can be unique to a single digital pass or the same for many passes.
PassKit Portal
The PassKit web application that allows you to create and manage digital passes, including the configuration of barcode messages.
Pass ID (${pid})
A unique identifier for each individual pass. When using apps like PassReader or CodeREADr, including the short code ${pid} in the barcode payload is crucial for the app to correctly identify the specific pass.
SKU (Stock Keeping Unit)
A specific code used by businesses to identify and track their products for inventory purposes.
Point of Sale (POS)
The hardware and software used to process transactions, like the checkout counter in a store. Barcode scanners are often connected to POS systems.
Alternative Message
Optional text that appears directly underneath the barcode. This is often used to display a human-readable version of the barcode data or another identifier for manual entry if scanning fails.
Barcode Payload
The PassKit Portal allows you to choose from the available Barcode encoding formats, and will adjust the Pass layout accordingly. You provide a payload that will be encoded within the Barcode. This can be:
This is used for things like membership cards (identifying a specific member), loyalty cards (tracking an individual's points), event tickets (unique entry for one person), boarding passes (specific passenger details), or store-valued cards (individual card balance). Essentially, anything where you need to know who is using the pass or what specific details are associated with that particular pass.
Common for each Pass
This is useful for things like coupons. Here, the barcode might just contain the SKU (Stock Keeping Unit) of the discounted item. When scanned at the Point of Sale, the system recognizes the product and applies the discount, regardless of which customer is using the coupon.
How Barcodes Work (Simplified)
At its core, a barcode is a visual representation of data. It uses a series of parallel lines of varying widths and spacing (for 1D barcodes) or a pattern of squares (for 2D barcodes like QR codes) to encode information.
Data Input by the User: You decide what data to include as the barcode payload for each digital pass. This data could be simple text, numbers, or more structured information depending on your needs.
Barcode Format Selection: Within the PassKit Portal, you choose the specific type of barcode you want to use (e.g., Code 128, QR Code, etc.).
Transmission to Wallets: When you issue a pass, PassKit transmits the barcode payload you provided and the barcode format you selected to Apple Wallet and Google Wallet.
Dynamic Generation by Wallets: Apple Wallet and Google Wallet, upon receiving the payload and format, contain the logic and algorithms to dynamically generate the actual barcode image (the specific pattern of bars and spaces or squares) on the user's device, based on the provided payload and the rules of the chosen barcode format. It's the wallet that takes your raw payload and encodes it into the visual barcode according to the selected format.
Scanning: A barcode scanner emits a light beam (usually red) onto the barcode. The dark bars absorb the light, while the white spaces reflect it back.
Decoding: The scanner has a sensor that detects the pattern of reflected light. This pattern of light and dark is translated back into the original data according to the specific barcode format's rules.
Processing: The decoded data (the barcode payload) is then sent to a computer system (like a POS system or the PassKit server), which can then take the appropriate action based on the information encoded in the barcode (e.g., identify a product, validate a ticket, look up a user's membership).
Message encoding
The message encoded in the Barcode is just data, there’s nothing that limits you from using it to carry additional information.
If you plan to use the PassReader scanning app, you must include the Pass ID using the shortcode ${pid}$ within your barcode payload. This allows the app to correctly identify and process the specific digital pass.
For example, suppose you need to scan a pass when network access is not possible (perhaps onboard a ship). This would make it impossible to communicate with the PassKit server in real time. You can sign the data you need with a private key, and use the result as a barcode. Although this approach doesn’t let you impose a one-time-use pass, it could be useful where passes are valid for a predictable period of time.
Text Below Barcode
You have the option to add text that appears directly below the barcode. This is useful for:
Displaying the raw barcode payload in a readable format.
Showing a unique identifier that staff can manually type into a Point of Sale system if the barcode scanner isn't working.
Important Note for Google Wallet: If you don't provide any "Alternative Text," Google Wallet will automatically display the raw content of the barcode payload below it.
Common Misunderstanding
Misconception: PassKit sends a barcode or barcode image to Apple Wallet and Google Wallet.
Correction: This is incorrect. PassKit doesn't send a picture of the barcode. Instead, you provide the raw data (the "Barcode Payload") and specify what type of barcode it is (the encoding format). Apple Wallet and Google Wallet then use this data to create the actual barcode image on the user's device. This approach is better because it ensures the barcode works correctly on different phones and allows the platforms to manage how the barcode is displayed efficiently.