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 must include the escape value %@, which is replaced by the field value when that 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 you want to 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 future 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 for the sample below 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. In some cases, passholders may not recognize this name as the issuer of the pass, so you may want to change it. You can set a custom title for change messages by adding a changeMessageTitle field to your template. The default value set for the field becomes the new title of change message notifications.

To set a custom change message title for your template:

1. Click Add a Field or Add Another Field. You can place the field anywhere, but we recommended adding it to the back of your pass template so that it is unobtrusive.
2. Enter changeMessageTitle for the field ID, and click Add custom changeMessageTitle field.
3. Set the Field Type to Text.
4. Change the Label Text to Issuer.
5. Enter a recognizable sender name for the Default Value. This value will be the title of all change message notifications for passes created from this 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",
      "label": "Issuer",
      "fieldType": "back"
   }
 }

Send a 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 Update Pass API or by publishing changes in 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.