Configure Apple Coupon Properties

Overview

The Apple tab of the Wallet Pass Details screen allows you to configure the Wallet Pass properties for Members using Apple devices. As you make changes to the configuration, the platform displays a preview render of the pass as it will appear on Apple devices.

The Apple tab is organized into the following sections, each of which is described below in more detail:

  • Barcode: Configure the pass's barcode settings.

  • Color & Images: Customize the visual elements of the pass.

  • Front Content: Design the primary view that displays essential information to Members.

  • Back Content: Set up additional details, terms, conditions, and resources.

  • Settings: Optionally enable pass sharing.

  • Test Preview: Preview the pass functionality for Apple devices using a specified Test Member.

Barcode

The Barcode section is used to configure the barcode that appears on the Mobile Wallet Pass.

  1. Select the Barcode tab.

  2. Set the barcode value using one of the following methods:

    • For a fixed number (like a coupon code), type the number directly in the Barcode Value field.

    • For personalized values, enter "@" to bring up a menu of available Content Tokens; select the desired Content Token.

    • Utilize Liquid templating to display Offer or Offer Response information.

A common use case is to use Liquid templating within the Barcode value to display the unique certificate code assigned to a Member. For example:

Copy 
{%- for offer_response in offer_responses -%}
{%- if offer_response.processing_status == 'pending' -%}
{{ offer_response.certificate_codes -}}
{%- break -%}
{%- endif -%}
{%- endfor -%}

  1. From the Format drop-down menu, select a barcode format:

    • QR Code: Best for storing more information

    • PDF 417: Common for boarding passes

    • Aztec: Efficient space usage

    • Code 128: Ideal for numeric data

  2. Optionally, in the Alt Text field, enter alt text for accessibility. As with the Barcode value described above, you can optionally utilize Liquid templating within the Alt Text field to display Offer or Offer Response information.

  3. Click Save Changes.

The preview rendering on the right updates automatically as you make configuration changes.

Color & Images

The Color & Images section is used to customize the visual elements of the pass.

The layout of a wallet pass on an Apple device is as follows:

  1. Under the Apple tab, select the Color & Images tab.

  2. The platform allows you to customize the Background, Label, and Value colors. Label and Value refer to properties of the Front Content fields (see below for details). For each option in the Colors sub-section, you may choose a color using one of the following methods:

    • Enter the desired hex code value.

    • Click the color swatch, and select the desired color from the color picker.

  3. The platform allows you to customize the images used for the Notification Icon, Logo, and Strip. For each option in the Images sub-section, click Choose File. Browse to and select the desired image file. The platform displays a thumbnail image. Click Upload. For each image, please note the following recommendations:

    • Notification Icon: Recommended size of 58x58 pixels. This icon appears in notifications that appear on the Member’s device. Use of a Notification Icon image is required. 

    • Logo: Recommended size of 320x100 pixels. Use of a Logo image is optional.

    • Strip: Recommended size of 750x288 pixels. When choosing this image, consider that the Primary Field text that gets displayed in the Strip area will appear in white. Therefore, be sure to select an image that will make the Primary Field text legible. Use of a Strip image is optional.

  4. Click Save Changes.

The preview rendering on the right updates automatically as you make configuration changes.

Note: The preview may not always render images to size; in particular the Logo may appear smaller and the Strip may appear larger in the preview panel. Always use the Test Preview feature to see the final rendering.

Front Content

An Apple Wallet Pass features a two-sided design, consisting of distinct front and back views. The front serves as the primary display area, showcasing essential information to your Members. For optimal presentation, ensure your content adheres to the standard layout specifications.

The Front Content comprises the following four fields. Each of these fields includes a Label and a Value. Typically the Label is smaller, and contains static text. The Value is larger, and will often contain a dynamic value populated by means of a Content Token or Liquid templating.

  • Header: This field appears at the top-right of the Card. This field also includes a unique text field called Logo Text, which is displayed next to the logo. The colors you selected above in the Color & Images section for Label and Value will be applied to this text.

  • Primary: This field displays within the Strip area and overlays the Strip image. The primary field text color is not configurable, and will always display as white text. If more control is required for color variation and font for the Primary fields, the best practice recommendation is to include the text within the Strip image.

  • Auxiliary: This field displays beneath the Strip area, to the right. The colors you selected above in the Color & Images section for Label and Value will be applied to this text.

  • Secondary: This field displays beneath the Strip area, to the left. The colors you selected above in the Color & Images section for Label and Value will be applied to this text.

The following example shows the basic positions and appearances of the Labels and Values for each field.

To configure the Front Content:

  1. Under the Apple tab, select the Front Content tab.

  2. For each of the available four fields, optionally enter the following details.

    • Logo Text (Header field only): Enter your brand name if not included in your logo. The color you selected in the Color & Images section for Value will be applied to this text.

    • Label: This value appears in a smaller font size than the Value. Enter a static value, or type “@” to pull up a list of Content Tokens, and select a Content Token. You can also utilize Liquid templating to display Offer or Offer Response information.

    • Value: This value represents the main text for this field, and is displayed in a larger font size than the Label. Enter a static value, or type “@” to pull up a list of Content Tokens, and select a Content Token. You can also utilize Liquid templating to display Offer or Offer Response information.

      A common use case is to utilize Liquid templating to populate one of the Front Content Value fields with the Offer Response expiration date. In the below example, the platform will display the expiration date for an Offer Response that has a Pending Status.

      Copy 
      {%- for offer_response in offer_responses -%}
      {%- if offer_response.processing_status == 'pending' -%}
      {{ offer_response.usage_end | date: '%b %d, %Y %I:%M %p' -}}
      {%- break -%}
      {%- endif -%}
      {%- endfor -%}

      The above example will display the expiration date in UTC. The platform does not support the ability to display a date / time value dynamically based on the user’s device. Optionally, you can specify the date / time be displayed in your loyalty program’s main time zone by adding the “timezone” attribute:

      Copy 
      {%- for offer_response in offer_responses -%}
      {%- if offer_response.processing_status == 'pending' -%}
      {{ offer_response.usage_end | timezone: "America/New_York" | date: '%b %d, %Y %I:%M %p'-}}
      {%- break -%}
      {%- endif -%}
      {%- endfor -%}

    • Change Message: A Change Message is a push-style notification that Mobile Wallet Pass holders will receive when the platform detects a change in the Value set above. In the Change Message field, optionally enter the content of this notification. For example, if you’re using a Content Token to display the Member’s point value, you could enter: "Loyalty card balance changed to %@." The "%@" will be populated with the current value of the Content Token in the Value field. Text must be entered in the Change Message field for a change notification to transmit.

    • Text Alignment: Optionally, you can override the default text alignment by selecting an option from this drop-down menu. Select Natural to use the default setting.

    • Date / Time Style: If the Value contains a date / time, use the Date Style and Time Style properties to configure how the date / time is formatted.

      Note: Please refrain from using the Date/Time Style fields until you receive specific instructions.

  3. Click Save Changes.

The preview rendering on the right updates automatically as you make configuration changes.

In the example below, the pass's expiration is displayed in the Secondary Field by means of a Content Token called “stl_token_offer_expiration_hr1”.

Below is the final render of this Wallet Pass.

Back Content

The front of your Apple Wallet Pass serves as a quick-reference display with limited space, requiring concise, high-impact content. The back of the pass offers expanded capabilities, allowing you to include comprehensive information such as detailed terms and conditions, contact information, and web resources for your Members. The back content cannot be previewed within the Loyalty interface.

Please see Apple Back Content Examples for examples of different types of information that can be displayed as back content on an Apple pass.

To configure the back content:

  1. Under the Apple tab, select the Back Content tab.

  2. Optionally, in the Description field, enter a Wallet Pass description, such as a summary of the Pass’s purpose or benefits.

  3. To add a new section to the Card’s back content, click Add New Section.

  4. From the Type drop-down menu, select the content type:

    • Fixed Text: Used for static content like terms and conditions or privacy policies. Supports HTML formatting for clickable links and text styling.

    • Latest Message: Creates a dynamic section that automatically displays your most recent customer communication.

    • Stores / Locations: Help your customers find your nearest stores by showing location-based information.

    • Custom: Create personalized content using Content Sources (Note: Content Sources must be pre-configured in the Advanced Options tab).

  5. In the Header field, enter a descriptive header for this section.

  6. In the Template field, either enter simple text content, or define advanced dynamic content like special offers or account balances, using Liquid syntax. CouponWallet Passes support the use of Liquid templating to display Offer and Offer Response information in the Back Content.

Note: For additional help on creating Liquid templates, a Templating Guide link is displayed within the Back Content tab. This guide provides code samples to support several different use cases, such as displaying the Offer name or description, or a coupon code or expiration date.. If using Liquid templating, please be sure your Content Sources and/or Content Tokens are set up, and all Content Sources have been added in the Advanced Options tab of the Wallet Pass.

  1. Optionally, in the Change Message field, enter the text of a push-style notification that Mobile Wallet Pass holders will receive when the platform detects a change in the Template set above. Text must be entered in Change Message for a change notification to transmit.

  2. Repeat the above steps as needed to add more sections to the Card’s back content.

  3. Click Save Changes.

Settings

The Settings section allows you to control whether users can share passes between user devices. This important security feature helps maintain the integrity of your pass distribution.

Pass sharing is controlled through a flag that was introduced with iOS 11. When configured, this setting determines the visibility of the Share button on the back of the pass. To configure sharing:

  1. Under the Apple tab, select the Setting tab.

  2. From the Sharing Prohibited drop-down menu, select either:

    • True: Removes the Share button, restricting pass sharing

    • False: Displays the Share button (default setting)

  3. Click Save Changes.

Note: This setting affects only iOS 11 and later versions. For earlier iOS versions, the Share button will remain visible regardless of this configuration. Additionally, while this setting can hide the Share button, it can not prevent users from sharing passes through other methods available on their devices.

Test Preview

To properly test your Apple Wallet Pass, you need access to an Apple device. This method provides the most authentic testing experience.

To test this Wallet Pass:

  1. Under the Apple tab, select the Test Preview tab.

  2. From the Test Member dropdown menu, choose your desired Test Member (designating a Member as a “Test Member” is available on the Member Profile screen). The platform  generates a unique QR code specifically associated with this Test Member’s data and configuration settings.

  3. Using your Apple device's camera, scan the displayed QR code. Your device will automatically recognize the Wallet Pass format and prompt you to add it to your Apple Wallet.

Alternative Testing Method

If you need to test an Apple Wallet Pass without immediate access to an Apple device, follow these steps:

  1. Install a Wallet Pass-compatible application on your mobile device.

  2. From the Test Member dropdown menu, choose your desired Test Member (designating a Member as a “Test Member” is available on the Member Profile screen). The platform  generates a unique QR code specifically associated with this Test Member’s data and configuration settings.

  3. Click the Download PKPASS file link beneath the QR code.

  4. Transfer the downloaded .pkpass file to your testing device.

  5. Open the file to view and test the pass in your chosen application.

Note: For the most accurate testing results, the best practice recommendation is to utilize an Apple device, as third-party applications may not perfectly replicate the Apple Wallet experience.