This article explains how to send lock screen notifications to iPhone users when a value on their pass changes. These notifications are triggered by updates to a pass in Apple Wallet, such as a change in points, balance, or other information. The message displayed on the lock screen is determined by the template you set up, and it can be customized to include dynamic values (e.g., "You now have 15 points!").
Key Things to Know
Lock Screen Notifications Are Triggered by Value Changes
A lock screen message will only appear when a value on the pass changes (e.g., points, balance, or other data).
The message is not sent like an SMS or WhatsApp message. Instead, it’s triggered by a push notification from Apple Wallet when the pass is updated.
Lock Screen Notifications Are iPhone-Only
Only iPhone users with passes saved in Apple Wallet will see lock screen notifications.
Android users with passes saved in Google Wallet will not receive lock screen messages, even though their passes will update.
Critical Requirement: The %@ Placeholder
To trigger a lock screen notification, the Apple Lock Screen Message field in your template MUST include the %@ placeholder.
Why is %@ required?
The %@ placeholder tells Apple Wallet to it with the updated (e.g., a new point balance). Without it, Apple Wallet cannot generate a dynamic message for the lock screen.
Example 1: Change a Value on a Single Pass
Setup:
The Apple Lock Screen Message on the template for the points field is set to:
"You now have %@ points!"A pass holder currently has 0 points.
You update the person's points from 0 to 20.
What Happens:
When the points value is updated, Apple Wallet detects the change and sends a push notification to the pass holder’s iPhone.
The
%@placeholder in the Apple Lock Screen Message is replaced with the new value (20).The pass holder receives a lock screen notification that says:
"You now have 20 points!"
Example 2: Changing a value on a pass template
Setup:
The Information field currently says
"Show your pass and get 5% discount"The Apple Lock Screen Message on the template for the Information field is set to
"%@"You update the value of the information field to
"Show your pass and get 10% discount"
What Happens:
When the Information value is updated, Apple Wallet detects the change and sends a push notification to the pass holders iPhones.
The
%@placeholder in the Apple Lock Screen Message is replaced with the new value.The pass holder receives a lock screen notification that says:
"Show your pass and get 10% discount"
Key Takeaway
Always include %@ in the Apple Lock Screen Message if you want to trigger a lock screen notification when the field is updated. This ensures the updated value is displayed to the pass holder.
What Happens If You Forget %@?
If the Apple Lock Screen Message does not include %@, the pass will still update, but no lock screen notification will be triggered. For example: If the Apple Lock Screen Message is set to "Your points have been updated!", the pass holder will not receive a notification, even though the Points field has been updated.
How Lock Screen Messages Work
When a value on a pass changes, Apple Wallet sends a push notification to the user’s iPhone. The message displayed on the lock screen is determined by the template you set up.
For example, If your template includes the message "You now have %@ points!", and the you change the user’s points to 50, the lock screen will display:
"You now have 50 points!"
The %@ symbol is a placeholder that gets replaced with the actual value (e.g., the new point balance).
Set Up the Lock Screen Message in Your Template
You can set up the lock screen message using either the PassKit Portal or the PassKit API.
Option 1: Using PassKit Portal
Go to Design > Apple Design.
Select the field you want to update (e.g., First Row or Points).
Set the Apple Lock Screen Message (e.g.,
"You now have %@ points!").
⚠️ Remember: The message must include %@ to trigger a lock screen notification.Save your changes.
You can also set a lock screen message for fields on the back of the pass (e.g., an Information field). Use %@ to dynamically display the updated value.
Option 2: Using the API
Use the
PUT /templateendpoint.Locate the field you want to update (e.g., Points).
Set the
changeMessageproperty underappleWalletFieldRenderOptions.⚠️ Remember: The
changeMessagemust include %@ to trigger a lock screen notification.
Update a Value and Send a Notification to a Single Member
Option 1: Using PassKit Portal
Go to Members and select the member you want to update.
Navigate to Details > Points.
Change the point balance and click Update.
This will trigger a push notification to the member’s iPhone, and the lock screen message will appear (if %@ is included in the template).
Option 2: Using the API
Use the
PUT /members/memberendpoint to update the member’s point balance.Make the API call and send the payload
If the member uses Apple Wallet and the template includes %@, the lock screen message will appear on their iPhone.
Update a Value and Send a Notification to All Members in a Tier
Option 1: Using PassKit Portal
Go to Design > Apple Design > Details.
Locate the field you want to update (e.g., Information).
Change the Default Value and save your changes.
This will trigger a lock screen message for all members in the tier who use Apple Wallet (if %@ is included in the template).
Option2: Using the API
Use the
PUT /templateendpoint.Locate the field you want to update (e.g., Information).
Change the
defaultValueproperty.Make the API call to send the payload
Members in the tier who use Apple Wallet will see the lock screen message.
Troubleshooting
If some passes haven’t updated in Apple Wallet, check the following:
Ensure the pass has been properly registered for push notifications.
Verify that the user has enabled notifications for Wallet in their iPhone settings.
Check that the Apple Lock Screen Message field includes %@. Without it, no lock screen notification will be triggered.
Check for errors in the API request or template configuration.
For more detailed troubleshooting steps, refer to this article.
Frequently Asked Questions (FAQs)
What does %@ mean?
%@ is a placeholder that gets replaced with the actual value when the pass is updated. For example, if you set the message to "You have %@ points!" and the user’s points change to 20, the message will display as "You have 20 points!".
Can Android users receive lock screen notifications?
No, lock screen notifications are only available for iPhone users with passes saved in Apple Wallet. Android users with Google Wallet will not receive lock screen messages, but their passes will still update.
Why isn’t my lock screen notification appearing?
The most common reason is that the Apple Lock Screen Message field does not include %@. Without %@, the pass will update, but no lock screen notification will be triggered.
By following these steps, you can easily send lock screen notifications to iPhone users when their pass values change. If you have any further questions, feel free to reach out to our support team!
Related articles: