Wallet for Windows Phone Store apps (Part 1): a wallet app developer perspective
Why I wrote this
My primary motivation is to just learn all the ways the Windows Phone 8.1 wallet can interact with a third party wallet application. I have found some MSDN articles about developing a wallet extension application, but what they did not have things that I want to find out: how can the wallet in Windows Phone provide values for my wallet application!
So I developed a sample wallet app (the source is available in github). In this app, I experimented every wallet item kind in the windows phone wallet, including adding/deleting an item, experimented its layout in the wallet UX. My journey is to find out:
- What do different wallet items look like in the Wallet application
- What are all the interfaces between the Wallet UX and the third party application
- What are the niche functionalities that the Wallet support?
The anatomy of a wallet item, expanded edition
In MSDN, there is an article about the Wallet where it discussed how a WalletItem is laid out in the Wallet app. What it fails to mention, are what a developer need to know the most: how to map each property of the wallet to a position on the wallet UI? What should I expect a “Deal” wallet item look like, and is it different from membership card? Or my boarding pass?
My investigation is set to find out these answers…
First of all, a wallet item can have a number of CustomProperties — you can see them as just any key/value pair of a Wallet item. Under a CustomProperty, you can specify its “SummaryViewPosition” or its “DetailViewPosition”. You can look at the documentation for more details.
What the doc didn’t tell, is for each DetailViewPosition maps to a location in the wallet front-of-card view layout. I experimented with every kind of DetailViewPosition to find out mapping, but then I found out the official layout specification in one of the older decks. You can see it below:
Difference in layout
It turns out that all 6 types of WalletItemKind use the same layout as above. So in appearance, there are no difference in any wallet items, with the minor exception of BoardingPass type.
On a boardingPass “front-of-card” layout, the layout has is an arrow between the PrimaryField1 and PrimaryField2. The intent is to use Primary1 field of a boardingpass item as the “origin, and Primary2 field as its “destination”
The API specifies that if the value of a WalletItemCustomProperty resembles a link that the phone OS recognizes, such as phone number, Uri, or an address, you can set the AutoDetectLinks property to “true”, and the value would be rendered as a link. If a user clicks on it, the link is actionable and would invokes the IE browser, the dial pad, or the Map app!
I struggled a while to make a property on a boarding pass item “actionable”, until I figured that actionable properties are only allowed in the “back-of-card” page. But the only way a property can be at the back-of-card page, is that it does not appear in the front-of-card page! The way to achieve this is to NOT specify the DetailViewPosition of a WalletCustomProperty. It would appear at the back-of-card instead.
How to make your item stand-out, when it is expiring soon, or a relevant date is approaching?
A WalletItem has three interesting properties, namely “RelevantDate”, “RelevantLocations” and “ExpirationDate”. The spec does not mention if/how the Wallet app would check these properties when rendering the wallet items.
What I found was not quite what I expected:
- ExpirationDate was not respected by the app — it does not differentiate an expired wallet item from the rest.
- The Wallet app takes into account of the RelevantDate or RelevantLocation of a wallet. If the RelevantDate of a WalletItem is approaching (e.g. RelevantDate == DateTime.Now), then the Wallet app would place it at the top of the list, and magnifies the logo. However, only one WalletItem would be placed at the top at any given time. Please see image below.
I have not tested the RelevantLocation functionalities but I expect a similar behavior
What about a WalletItem that was added by a Silverlight application?
For WalletItem that are added by a Silverlight phone application, the behavior is quite different:
- The Wallet does not render the “front-of-card” page for these items. Instead, it only render the back-of-card page.
- The barcode image of the WalletItem seems to be broken in the upgraded Wallet app.
Considering that most Phone applications were developed using Silverlight, that would potentially break many wallet extension apps.
What is next in part 2.
I will explore all the possibilities of how the Wallet app interacts with other apps on the Phone, such as the store app, or the wallet extension app.