Passbook® is a technology created by Apple Inc. for digital representation of passes, coupons, tickets and everything written in short papers on real life. It has a complete ecosystem, defining the whole passes' lifecycle from the creation to the update on redemption. The Passbook Composer also generates a Android Pay compatible object, that will be delivered to an Android device if it tries to download the Passbook. The Messangi platform detects the capabilities of the device downloading the pass and delivers the best format for the platform.

Passes structure

The Passbook passes can be seen in different ways:

  • Visually, a pass has a front side and a back side. In the front side you can see different images, a barcode and the content text. The images are named: logo (upper left corner), icon (for notifications on lock screen), thumbnail (half on pass right), footer (above barcode), background (behind text, barcode and other images) and strip (upper half of the pass). The text written is divided in 5 specific places, named: logo text (upper center), header fields (upper right), primary fields (upper half) secondary fields (bottom half) and auxiliary fields (bottom half). To access the back fields you have to tap on the i button in the bottom right corner of the pass. The front side fields are intended to be short and precise, while back side fields can be as long as needed to things like addresses or terms and conditions.
  • As a file, a pass is a compressed file on zip format with .pkpass extension. The file contains: a JSON (plain text) file with the structure of the pass (text, barcode, metadata), the images on PNG format and a digital signature.
  • As a technology infrastructure, it has four components: a wallet app to display passes (native on iOS, for Android devices an Android Pay compatible pass will be delivered), the pass itself (file .pkpass), a server that emits the passes (Ogangi servers) and a set of third party servers (Apple's and others) that allow PUSH Notifications to update delivered passes, depending on the end user's device platform.
  • As an interactive technology a pass can be time-and-space aware, by setting inside its metadata: a relevant date, an expiration date, associations to a geographical location with its coordinates and / or associations to mobile bluetooth devices known as iBeacons. It allows passes to be shown in the lock screen when the time arrives or when the pass is around a place or near an iBeacon device.

Create a Passbook campaign

For creating a Passbook campaign you require two components: a Passbook template and a subscription or segmentation list with the recipients mobile numbers and their custom data (if needed).

Creating Passbook template

To create a Passbook template go to the left menu and select the option Interactive campaign and then Passbook. You will enter on the Passbook templates list. To create a new template, click on the New Passbook Template button, on the toolbar.

This will open the Passbook template composer. To start creating passes click on Show pass! button; you can click on it again to see the animation when the current pass is opened on a mobile device.

To create a template you have to set: the visual design, the text content, the barcode, the images and the metadata (relevant date, expiration date, iBeacons associated and locations associated).

Some of the elements in the template have the option to have a general value for all the passes delivered or to use a custom value per pass. In the last case, the value will be extracted from the subscription or segmentation list used when doing the delivery.

Also, there are some elements in the template that are optional. So, if you wish to use them you have to checkmark the square beside the name of that features.

There is no pre-established order to construct the template, hence you can do your edition in whatever order. For this manual purposes the steps will be ordered as the menus are presented on screen:

  • In the Instructions tab you only have to read the briefing to have an overview of the task that should be done.

  • In the Identification tab you have to establish a name for the template and a short description about it.

  • In the Content tab you have to write the text of the pass. The pass has a logo text optional, if you want to write it check the checkbox and write its content. To create the rest of the content text you have to use the content fields. First choose the sector where the text is going to be placed (header, primary, secondary, auxiliary or back side), second write its label, third write the general value or mark it as specific value per pass. Finally click on the Add field button. When you add a field you can see it on the iPhone simulator screen.

If you want to go to the back side click on the View back side button or on the i button inside the phone emulator, in the down-right corner (as in iOS). To return to the front side click on the View front side button.

When you wish to modify a field, in the content area or beacon or geolocation, just click on the icon with the pencil to modify such field. The field row will be highlighted in yellow. Once you finish the edition of the field selected, click on the button Add field / beacon / location to update the changes on the form and in the template.

Also, for deleting a field, iBeacon or geolocation just click on the ex icon at the right of the row. The element will disappear from the table and from the template screen or data.

If you wish to know where exactly is located a field area, just click on See field sector and in the emulator on screen you'll see the area highlighted with a red square like this below:

You can use the Place dropdown to change the area highlighted. If you change the Passbook type, the red square can be relocated according to the layout of the type selected. To hide the square click on Hide highlight button.

  • In the Visual design tab, you will: choose the Passbook type, load the images, choose colors for the template and choose the barcode.

There are five types of Passbook passes: Store cards, boarding passes, coupons, event tickets and generic passes (for general purposes).

The background color applies only if there is no background image. All the captions, except the logo text have a label with label color and a value with forecolor.

The images to load correspond to those pointed above. Not all the images are available in all the types of passes, as can be seen in the following table:

Pass style Supported images
Boarding pass logo, icon, footer
Coupon logo, icon, strip
Event ticket logo, icon, strip, background, thumbnail
Generic logo, icon, thumbnail
Store card logo, icon, strip

The logo and icon images are mandatory, while the others are optional. To use an optional image just verify the checkbox beside its name is checked, otherwise mark it. The images you upload can be whatever visual size and up to 10 MB of file size. In the process of creating the template, your images will be scaled (preserving aspect ratio) to fill this allotted space. Images with a different aspect ratio than their allotted space are cropped after being scaled. Just as a reference, the space allotted is as follows:

  • The background image (background.png) is displayed behind the entire front of the pass. The expected dimensions are 180 x 220 points.
  • The footer image (footer.png) is displayed near the barcode. The allotted space is 286 x 15 points.
  • The icon (icon.png) is displayed when a pass is shown on the lock screen and by apps such as Mail when showing a pass attached to an email. The icon should measure 29 x 29 points.
  • The logo image (logo.png) is displayed in the top left corner of the pass, next to the logo text. The allotted space is 160 x 50 points; in most cases it should be narrower.
  • The strip image (strip.png) is displayed behind the primary fields. The allotted space is 375 x 144 points
  • The thumbnail image (thumbnail.png) displayed next to the fields on the front of the pass. The allotted space is 90 x 90 points.

There are three kinds of barcodes available on Passbook: QR, PDF-417 and Aztec. The image below shows these three types:

If you want to set a barcode, checkmark the option barcode. Then select the barcode type you wish to use; set the content and the label, with a general information for all passes or allowing it to be variable, checking the options specific value per pass. In the barcode label you can also choose to use same of encoded message.

  • In the Geolocation tab you can add up to ten different locations associated to the pass. To active this feature mark the Associated locations checkbox. Use the Google Maps widget to locate the place you want to attach by writting its address on the Address to search textbox, or look for it navigating directly the interactive map. Once you are in the right spot, click on Add current coordinates on map button and write a label to such location. Click on Add location to attach it to the pass. If you want to edit a location click the edit button or if you want to remove it click the delete button. As a general strategy to get the right address, write down a well known reference place and then move toward your desired location; use the red circle on the middle of the map to verify you're focusing on the right place. If you want to set the maximum distance for getting notifications from a location, mark the Maximum distance for notifications checkbox and the set a non-zero integer number.

Once the Passbook is delivered to each user and it's downloaded to the device, once the user reaches the fence it will be triggered and will pop-up in the main screen of the phone.

  • In the iBeacons tab you can add up to ten iBeacons associated to the pass. To active this feature mark the Associate iBeacons checkbox. Every iBeacon has an Universal Unique Identifier (UUID) which is related to the company owner of the devices, then they have a major number to identify subsidiaries of the company i.e. branches, stores, resellers, etc. and finally they have a minor number to identify small places indoors e.g. departments, sections, etc. For the associated relevant text you can write a generic message for every pass or set it as specific value per pass.

  • In the Dates tab you can set both relevant and / or expiration dates. To set a date first mark the checkbox beside the label. A relevant date is the date and time when the pass is most important or useful, e.g. the flight time for a boarding pass, the concert time for a event ticket, the offer day for a single-day coupon, etc. The expiration date tells the pass its validity is voided, then the wallet blurs the barcode and labels it “This pass is no longer valid”. Caveat: the expiration date doesn't mean the pass is going to be deleted. The pass will remain in the wallet, because only the end-user is allowed to delete their passes from their wallet app. For these dates you can set a general date for every pass of set it specific per pass. Use the Timezone to specify the local time where it applies.

  • In the Finish tab you only have to read the instructions and click on the Save template button. If don't want to store the template for whatever reason, then you can click on Cancel button.

Sending Passbook passes

Dynamic passes using broadcast tools

To send a broadcast of Passbook passes to your end users, you have to accomplish two main steps.

  1. Create a data source list for recipients and variable data inside passes. That list could be a Segmentation List or a Subscription list for SMS delivery, or Email list for email delivery. That list can be created from a file uploaded or by hand (see Subscription Lists for details). Remember to add on that list all the customized data that will be required to fill in the delivered passes.
  2. Order the broadcast via the Passbook passes broadcaster. The usage of the broadcaster will be given in detail below.

To enter to the broadcaster first go to the list Passbook templates screen, through the left menu, option Interactive Campaigns then Passbook. In the list choose the Send button (in the right column called Tasks with a envelop picture).

Once in the form you have to fill the steps in order to configure the broadcast.

  1. In the first step you have to choose the broadcast delivery channel from the three possible options: SMS, Email or Push Update. For the first case the message will include your text and a link to download the pass. In the second case the mail will include your formatted text and a button linked to the pass below your mail body. For the third case you can use it just after doing at least one broadcast, because it's intended to be used as an update for passes already delivered.
  2. In the second step you have to choose the data source list that's going to be used for the broadcast. Here you can choose between segmentation lists or regular lists. After choosing the list the form will show you the variable fields and dropdown boxes to make the matches between the variable fields on template and the custom data available in the list chosen. Notice that you can choose one and only one list as source data; it's intended to avoid data confusion or contradiction when lists are merged.
  3. In the third step you have to set the text for SMS, the subject and body for email or the log control text for the updates. The text, and the subject for email are mandatory, then they cannot be blank.
  4. In the fourth step you can customize the delivery schedule, in terms of starting date and time, periodicity, restricted hours, restricted days and throttle. If you choose the option (send) Now the delivery will be done once. If you choose the option Periodic you must select the kind of periodicity, i.e., daily, weekly, monthly or yearly with respective parameters. If you want to set how many messages will be sent per second then unselect the checkbox No throttle and set that value; it can be between 1 to 5400 per second.

The process in detail

SMS broadcast steps

Selecting option SMS

Choosing data source list and making matches

Writing the text for the SMS blast

Email broadcast steps

Selecting option Email

Choosing data source list and making matches

Writing subject and body for the email blast

Push update broadcast steps

Selecting option Push

Choosing list to update and resetting the matches

Writing the push control log text

In the fourth step you can assign a schedule for the broadcasted messages; by default the blast is sent inmediately after finishing the settings of sending process. In the SMS broadcast you have also available the option to set the origin shortcode that will perform the delivery. For Update Pushes the scheduling will not apply because pushes are sent once per request and delivered by third party servers (Apple / PassWallet). The broadcast scheduling has the following options:

Send now: if checked the broadcast is sent inmediately. If not choose the day and time to execute the broadcast.

Dayly scheduling: sending the same messages the indicated day rate between a range of dates.

Weekly scheduling: sending the same messages the indicated week rate between a range of dates.

Monthly scheduling: sending the same messages the indicated month rate between a range of dates.

Yearly scheduling: sending the same messages the indicated year rate between a range of dates.

No throttle: if unchecked set the messages per second rate. If checked, rate by default is set (600 messages per second)

No restricted days: if checked no restricted days. If not, check the days when broadcast is not allowed to continue

No restricted hours: if checked no restricted hours. If not, use the selector to set the range of hours when broadcast is not allowed to continue

If you wish to see a preview of the passes that will be delivered, you can click on Preview button in order to display the final resulting passes. They will be filled with the information of the subscription list chosen applied with the structure of the template using and the matching rules set before. This tool is useful to get a pre-delivery feedback of the final design and information that will flow across the broadcast. The preview shows a modal window in the center of the browser tab with the iPhone emulator displaying the resulting pass on screen; the title of the modal window shows the current recipient (phone number or email address) in the title bar and the general purpose URL below the emulator.

You can see the backside by pressing the i button in the bottom-right corner and to return to frontside just click on the same place.

Once you are ready with the settings of the Passbook broadcast proceed with the delivery by clicking the Send button, and then confirm clicking again. The delivery will be executed as it's been set according to these steps.

Updating delivered Passbook passes

If you have changes to apply over the passes after been delivered, you can rely on the Push Notifications mechanism to deliver such changes for the required ones. For those users registered with iOS devices will get APNS while others will get Passwallet pushes. The system will determine whether or not to send the pushes according to the changes made: if the template has changes, all the delivered passes will be notified with pushes; if the template hasn't changed then only those passes which source data has been changed will be notified. Caveat: the Pushes will arrive if and only if the users have the option Automatic updates turned on in the pass itself inside the wallet app.

The update process has also two main steps: changes over passes and push notifications. To perform the first step you can: update the template and/or update the source data. In the second case, you have to go to the respective module to make the required changes and AFTER that go to the Passbook module to send the broadcast of pushes.

First go to Passbook list (Left menu → Interactive Campaigns → Passbook). Once there, click on the Send button for the proper template; select the Push option and click on Next button. In the second step the list dropdowns will be filtered, in order to show you just those lists that have already been used for previous broadcasts. Select the list for the update and then reassign the matches between current passbook template variable fields and information on the selected list. After that go to the next step and write a message to describe briefly the kind of changes made or the purpose of the updates. That information will be stored on database for tracking the operations made over the Passbook campaign. In the last step you have just to click on Send button and the push notifications will start to be delivered.

About the update process: once you send the push notifications, the system will send the new version of the passes to the registered devices that allow the automatic updates. The user will get the updated passes inside the wallet app without any other action more than be online. You can use this feature to update information such as offers, personal data updates, new balances, add or remove information to the pass, renew or correct dates, add or remove locations, iBeacons, etc.

Single pass update

If you want to update just one pass instead of all passes changed on a list, you can rely on the single pass update feature. With this option only the chosen recipient's devices will get the update pushes, what becomes in lesser processing time and a useful way to point exactly the pass you want to be updated.

To update a single pass open the Send Passbook Wizard by clicking on the send button of the template of the target pass.

  1. Select the option Push in the first step
  2. Select the email or SMS subscription list where the recipient of the pass is contented
  3. Checkmark the checkbox “Send to one recipient”
  4. Write in the textbox the telephone or email address. Note that the textbox can autocomplete it with just writing the first characters.
  5. Write a Push text to record that update
  6. Click Send button to finish the operation

After sending that process, all devices using iOS with the pass using the same recipient (telephone or email) will get Apple Push Notifications in order to run the update process, while the Android devices will get automatically the pass updated inside the Android Pay app.

Android Pay compatibility feature

The Passbook functionality in the Campaign Manager has been enhanced to support compatibility for the Google's wallet brand called Android Pay. The Android Pay app can be downloaded from the Play Store in USA, UK and Australia only. This app allows the user to store and pay using his/her debit and credit cards and also store different passes, just like Apple Pay but with different visual layouts.

In Android Pay there are three different templates available: offers, giftcards and loyalty cards. The Passbook type you choose in the system will be translated in Android Pay to one of these three according to the following mapping:

Passbook typeAndroid Pay Template
Boarding Pass Offers
Coupon Gift Card
Event Ticket Offers
Generic Loyalty Card
Store Card Loyalty Card

Android Pay layouts

The layouts in Android Pay have been simplified to find the equivalent layout using Passbook data. When making a wallet cross-platform campaign using the campaign manager be sure to put the data in the right places, using the rules below:

OffersGift CardLoyalty Card
1. Title Image: supplied by Logo Image
2. Title: supplied by Logo Text
3. Issuer Name: supplied with system information of your brand
4. End of valid time interval: supplied by expiration date. Default: July 8th 2024
5. Provider: same as 3
6. Barcode and Card Number: supplied by barcode information and settings
7. Main Image: supplied by strip image
8. Text content: header, primary, secondary, auxiliary and back fields.
1. Program Logo: supplied by Logo Image
2. Balance: supplied by first header field value
3. Balance update time: taken from the current time
4. Merchant Name: supplied with system information of your brand
5. Pin label: supplied by first secondary field label
6. End of valid time interval: supplied by expiration date. Default: July 8th 2024
7. Pin: supplied by first secondary field value
8. Barcode and Card Number: supplied by barcode information and settings
9. Event Number Label: supplied by second secondary field label
10. Event Number: supplied by second secondary field value
11. Main Image: supplied by strip image
12 and 13: Text content: remaining header, primary, secondary, auxiliary and back fields.
1. Program logo: supplied by Logo Image
2. Program name: supplied by logo text
3. Issuer Name: supplied with system information of your brand
4. Points label: supplied by first header field label
5. Rewards tier label: supplied by the first secondary field label
6. Rewards tier: supplied by the first secondary field value
7. Loyalty points balance: supplied by the first header field value
8. Barcode and Card Number: supplied by barcode information and settings
9. Account name label: supplied by the second secondary field label
10. Account name: supplied by the second secondary field value
11. Account id label: supplied by the third secondary field label
12. Account id: supplied by the third secondary field value
13. Main image: supplied by the strip image
14. and 15. Text content: remaining header, primary, secondary, auxiliary and back fields.

Differences and similarities between Passbook and Android Pay

Both wallet apps allow to store passes with text, images, barcodes and metadata. In the following table are listed the characteristics and constraints of them

FeaturePassbookAndroid Pay
Colors Set by user Set by app using the title image's main color (non-black, non-white)
Barcode Formats QR, PDF417 and Aztec, optional Same of Passbook will be used, however they support up to 11 formats else, mandatory
Geolocation metadata Available, up to 10 locations per pass Available, no limit per pass
iBeacon metadata Available, up to 10 iBeacons per pass NOT AVAILABLE
Images From 2 up to 5 (depending on the template) 1 up to 2
Visual orientation Vertical Horizontal
Storage Device's internal memory Cloud, linked with recipients' Gmail accounts
Expiration date Available in all templates, optional Mandatory for Offers and Gift Cards. Not available in Loyalty Cards
Relevant date Available in all templates, optional NOT AVAILABLE
Digital signing Applied, using Apple WWDRCA and .p12 Certificate Applied, using .p12 Certificate

Process of delivery and update

The process to deliver Android Pay passes is exactly the same as the one used for Passbook described in chapters above. The branching point happens in the recipients's devices: if their device uses iOS (iPad, iPod touch, iPhone) the conventional Passbook file will be delivered; in other hand, if their device uses Android OS, the Save to Android Pay button will be shown, the recipient must tap on it in order to authorize the link between Android Pay pass and their Gmail account. The massive updates will check the platform used storing passes and according to them will send programatically the proper pushes.

System requirements for Android Pay

The recipient who gets the link for Android Pay needs to have installed the Android Pay app. It requires Android 4.4 or above to be installed and the device must support NFC connection. Also, the recipient needs to have a Google account associated to the device that will be used for storage on cloud of the pass information.