This article shares how to deliver a message to the iPhone lock screen. You can do this via the PassKit Portal or the PassKit API; this article covers both.

Before we get started, there are 2 very important facts / concepts to note and understand.

Sending push messages via Wallet is not the same as sending a message via SMS or WhatsApp, for example. A lock screen message is only shown by Apple Wallet when a value on the pass changes (when received from the PassKit push notification).
Lock screen Messages are only delivered to iPhone owners. A person who owns an Android device and with a pass saved to Google Wallet will not receive a lock screen message. The Pass will update but Google Wallet does not deliver lock screen messages to inform the user of the change.

A lock screen message only appears when a value on the pass changes.

This article demonstrates how to send Apple lock screen message. We will send 2 lock screen messages

① Send new point balance notification to an individual member

② Send latest news message to all members in the tier

Step 1: Set Apple Lock Screen Message on Template

By Using PassKit Portal

Please go to Design > Apple Design > select field (e.g. First Row) > set Apple Lock Screen Message (You now have %@ points!) > Save.

Likewise, let's set Apple Lock Screen Message for Information field on the back as well. Set %@ will display a message with a new text set on this field.

By Using API

The endpoint is PUT /template. Then we can set the lock screen message text to changeMessage field in the Template object which locates at data > dataFields > go to the field (e.g. Points field) > appleWalletFieldRenderOptions > changeMessage.

Let's set changeMessage on Information field on the back of the pass as well.

What is %@ ?

You might have wondered why we need %@. %@ replaces itself with the value set for a pass holder so that you can customise the message for each pass holder.

For example, member pass has Point field and each member has different point. If you set Apple Lock Screen Message (changeMessage) as "You have %@ points now!" then customerA who just got 15 points will get a message "You have 15 points now!" and customerB who just got 105 points will get a message "You have 105 points now!".

Step 2: Update point balance and send push to a single member

By Using PassKit Portal

Go to Members > select a member > Details > Points. Change Points and click Update button will trigger a push notification to this member.

By Using API

Call PUT /members/member to update the point balance of the individual member. If the member uses Apple Wallet, lock screen message will be shown on the phone.

Step 3 : Update information field to send push to ALL tier members

By Using PassKit Portal

Go to Design > Apple Design > Back > Default Value. Changing the default value triggers Apple lock screen message at Save because Apple Lock Screen Message is set as "%@".

By Using API

Go to template > data > dataFields > go to the field (e.g. Points field) > defaultValue. Change defaultValue value and then call PUT /template. Members who belong to the tier and use Apple Wallet will see a lock screen message.