Change Message Tutorial

When a change message is posted to a user’s device, the screen displays a title and the pass’s icon image along with the notification. The user’s device will not play a sound or vibrate.

The title displayed with a notification is the company name associated with your Wallet account, unless you set a custom change message title for the template.

Each field object on an Apple Wallet pass can include an optional change message value. A change message is the text that appears in an alert that is displayed when a pass field’s value is changed.

The change message includes the escape value %@, which is replaced when the field’s value is changed. For example, if you enter the change message “Gate changed to %@” and you later change the field value to “A64,” the alert text would be “Gate changed to A64.”

Add a Change Message Using the Dashboard

1. Go to Templates.
2. Click anywhere in a template’s row to see its expanded view. If you have only one template in the project, the initial view is expanded.
3. Click Edit Design.
4. Select a field, click Advanced Options at the bottom of its configuration pane, then check the box for Notify the user when this value changes.
5. Enter the text that will appear in the notification, including the placeholder %@ for the field’s new value.
    Important

   A notification will not be triggered if %@ is not in your change message.

6. Click Save.

Add a Change Message Using the API

The following is an example of a pass field that includes an optional change message value using the key changeMessage. The value of changeMessage is the text that will appear in the notification. The placeholder %@ for the field’s new value is required.

When updating a pass, if the specified value is different than what is currently included on the pass, then the change message will be displayed on the user’s device. The notification, in this case, would be “The value for this field has changed to New text value.”

{
  "fields": {
    "TextField": {
      "changeMessage": "The value for this field has changed to %@",
       "value": "New text value",
       "label": "Text Field Label"
    }
  }
}

Set a Custom Title For Change Messages

By default, the title of change message notifications for iOS is the “company name” associated with your Wallet account. You can set a custom title for change messages by adding a changeMessageTitle field to your template. The Default Value of the field becomes the title of change message notifications.

To set a custom change message title for your template:

1. Click Add a Field or Add Another Field. While this field must be on the template, you can place the field anywhere. It is recommended that you add the field to the back of your pass template, so that it is as unobtrusive as possible.
2. Set the Field ID to changeMessageTitle, select field type Text, and click Next.
3. Set a Default Value for the field. This value will be the title of change message notifications for the template.

You can represent the field in the API as a changeMessageTitle object in the fields object of a template

"fields": {
   "changeMessageTitle": {
      "value": "Title for change messages",
      "fieldType": "back"
   }
 }

Send Pass Update

Now that you have a change message set, the alerts are handled automatically. After you edit the value of a field in a template and save the changes, you then need to give your passholders the latest version of the pass, via the API or the dashboard.

Best Practices for Change Messages

• Message Length: Keep your change messages short. The notification will be truncated if it’s too long, just like other notifications.

• Spam: Do not change field values frequently. Multiple alerts will likely lead to users removing your pass.

• Latest Message: If you plan on sending promotional or marketing messaging to your users, consider including a field on the back of a pass that always displays the latest message. This allows the message to persist even after a user has dismissed the notification. See the note in Send Pass Update.