Change Message Tutorial

Alert your Apple Wallet passholders when pass content has been changed.

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."

Note

  • If you don’t specify a change message, the passholder isn’t notified when the field value changes.
  • Setting a change message will not trigger sending a notification — the notification is triggered when you change the field value.
  • When multiple fields with change messages are updated at the same time, we cannot control the processing order. That is handled by Apple.

What You'll Do

In this tutorial, you will:

  1. Open your project.
  2. Navigate to the Templates menu.
  3. Select a template.
  4. Set a field's change message.
  5. Save your changes.

You can also set a change message via the API.

Steps

Dashboard

  1. Open your project from the dashboard, then click 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 the Edit Design button.
  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 the Save button.

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."

Important

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

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

Change Message Title (iOS Only)

By default, the title of change message notifications for iOS is the "company name" associated with your Reach 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.
  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"
    }
  }

Next Steps

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 Publish.

Note

Publish will only update fields on the back of a pass. If you intend to send pass updates via Publish, add a "Messages" field to back of the pass template, include a change message, and use the field for your change notifications.

User Experience

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 Reach account, unless you set a custom Change Message Title for the template.

Best Practices

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.

Tutorials