This article explains the core concepts, constraints, and best practices for implementing location-based messages for digital passes. These messages, which are displayed on a user's lock screen when they are near a relevant location, are a powerful way to make your passes easily accessible and useful in the real world.

The most crucial thing to understand about location-based messages is their fundamental "passive" nature. Unlike a traditional push notification or a text message, you are not sending a message to a user when they are at a specific location. The process is entirely initiated by the user's device, not by you.

Here's a breakdown of the core concept:

When you create a pass, you embed specific location data (GPS coordinates or Beacon UUIDs) and the associated message directly into the pass file itself. This data becomes a part of the pass and resides on the user's device after they have added it to their wallet app.

The user's device, whether an iPhone or Android, has its own built-in location services (GPS, Wi-Fi, Bluetooth). It is the device's responsibility to monitor its own geographical position.

The wallet app on the device periodically and efficiently compares the device's current location with the location data stored within all the passes on the phone.

If the device determines that it is within the proximity of a relevant location specified in one of the passes, it will then automatically display that pass on the lock screen. The message you pre-loaded into the pass is what is shown to the user.

In short, you are not tracking users or receiving a notification when a user enters a location. The entire process is a self-contained, privacy-respecting function of the user's own device.

It is important to understand that a location-based message has only one purpose and one destination: to guide the user to the pass itself. When a user taps on the message displayed on their lock screen, the experience is simple and direct:

You cannot use a location message to redirect a user to any other destination. This means you cannot open a URL, a map, or a specific page within a separate application. The entire user experience remains contained within the Wallet app, ensuring a consistent and streamlined interaction.

A Wallet pass can have up to 10 relevant locations (either GPS coordinates or iBeacon UUIDs). This is a fixed constraint for two key reasons:

The process of adding location-based triggers is straightforward and is done from your end as the pass creator.

You will use either the PassKit Portal or the PassKit API to create or edit your pass design.

Within the design settings, you will specify the relevant locations. This can be done in one of two ways:

For each location you add, you must also provide the short message text that will be displayed on the user's lock screen. This message is saved directly within the pass file along with the location data.

Since Apple Wallet has a 10-location limit, you must strategically choose which locations to include. You can use your account management system to allow customers to add their favorite or most-frequently visited stores. Alternatively, relevance data can be changed when a pass is updated, so you can dynamically provide locations tailored to the user’s behavior over time.

The message you create should be concise and directive. While there is no specific character limit, longer messages may be truncated on the lock screen, cutting off crucial information.

For Apple Wallet, using iBeacons with a single UUID across a large number of physical locations is a clever way to bypass the 10-location GPS limit. You can use major and minor identifiers to further refine your relevancy text and differentiate between various departments or areas within a single store. The system uses the relevancy text from the most-specific matching beacon (the beacon matching the most of the UUID, minor, and major identifiers).

The relevant text should describe why the pass is useful at that location, such as “Store nearby.” Avoid including your organization name, as it's already displayed on the pass. Also, do not include instructions like "Redeem this pass at XYZ." The goal is simply to remind the user of the pass’s relevance.

One of the most powerful uses of a dynamic pass is to change the message based on specific times or promotional periods. You can update the message in the PassKit Portal or via the API to reflect a current offer. For example, your location message could be "Monday to Wednesday, earn double points," and then for Thursday through Sunday, it can be changed back to "Use your loyalty card to earn points." It is crucial to remember to change the message back once the promotional period ends to avoid confusing the user or advertising an expired offer.

It is critical to remember that the end-user has ultimate control over whether these location-based messages appear. A lock screen message will only appear if three conditions are met:

Ultimately, the consumer decides if they want to see a location message. This makes it essential to create messages that are genuinely useful and not "annoying." By providing timely and relevant information, you can ensure that users choose to keep these features enabled, improving their experience and your engagement.

Location-based messages are a powerful and elegant feature for enhancing the utility of digital passes. By understanding their passive, device-driven nature and working within the established constraints, you can create a seamless and helpful user experience. The key is to think of the pass as an intelligent tool that knows when and where it is relevant, allowing users to effortlessly access the information they need at the perfect moment. This not only improves customer engagement but also provides a non-intrusive way to remind them of the value of your brand or service.