Linking Your App to the Wallet
So Windows Phone has an integrated wallet experience, but why would you want to link it to your app? Well if you’re a financial institution of course you might want to enable payments with your cards. But even if you’re not a bank and your app offers deals, coupons, a membership or even stored value, integrating with the wallet give the user increased visibility to your offers. Oh, and did I mention free promotion in the wallet app – even if your app isn’t installed?
Adding Wallet support is actually quite easy, especially if the app doesn’t need to update the wallet when it’s not running.
The first step is to add the wallet capability to the app. This can be done by double-clicking on WMAppManifest.xml (under Properties), switching to the Capabilities tab and checking the ID_CAP_WALLET checkbox.
Don’t check the other two wallet-related boxes unless you want to add real payment options (e.g. Visa credit cards) that can be used to buy music, apps, etc. These boxes don’t need to be checked for membership cards (like a Starbucks card).
Note: If a financial app does want to add payment cards it will need to pass a few extra certification requirements with the Windows Phone store.
Next we need to register our app as an extension to the wallet. Unfortunately there isn’t a way to do this in the UI so we’ll need to save our work, right click on WMAppManifest.xml and choose ‘View Code’. After the closing </Tokens> tag, add an Extensions block like this:
ConsumerID and TaskID will never change – they’re always those values. But ExtensionName might change depending on how you want to interact with the wallet. The choices are:
- Wallet_app_other – for non-specific Wallet items
- Wallet_app_loyalty – for loyalty cards
- Wallet_app_membership – for membership cards
- Wallet_app_transit – for transit cards
- Wallet_app_payment – for payment cards
Wallet_app_membership is a good choice for most applications, and if you want to register support multiple extensions you could do it like this:
Now save WMAppManifest.xml and when you submit your app to the store it will start getting promoted in the wallet app. That’s a tremendous advertising advantage!
The last thing we need to do is have our application add a card to the wallet. Up to this point we’ve given the app the ability to interact with the wallet and gotten our application advertised there, but there’s still no link from the wallet back into our app once it’s installed. Don’t worry, the card you create can simply be a membership card. It doesn’t have to report a live credit balance (though it can if you want it to). You might just want to display a logo and give the user the ability to launch the app. Of course this is a great place to add customer support information like e-mail addresses and phone numbers, and you might want to display a QR code for example to identify the user at a retail store. It’s up to you how much information you want to add, but the WalletTransactionItem documentation gives you a listing of what’s possible.
When your app adds the card is up to you, but a good place to ask is on application launch. Of course if the user declines the card we don’t want to ask again (though we probably want to give them the option to add it later via a button or menu item). Also keep in mind that the membership card might have already been added so we want to make sure it doesn’t exist before we try to add it again.
Finally, there are some slightly unusual requirements we need to knowing about the card logo image. First of all, the card actually needs three image sizes (336×336, 159×159 and 99×99). Luckily we can supply one large image for all three sizes and the system will resize it for us. The more important requirement is that the image has to be fully loaded before the request is made to add the card. Most people don’t know that passing a URI into the constructor of BitmapImage doesn’t load it right away. It kicks off a background task to load the image and you’ll get an exception if you try to add your card before this task completes.
There are a couple of workarounds but the easiest one is to store the image as a resource and load it as a stream. Don’t forget to set the Build Action in the property window to ‘Embedded Resource’ instead of ‘Content’, which is the default.
Here is one possible method for adding a membership card:
We also need the event handler for when the task completes. This is so we can inform the user if something went wrong and it’s also a good place to store a flag if the user chooses to decline the card:
Now we can call EnsureMembership from the page Loaded event or from a button click. In the loaded event we only want to call it automatically if the user hasn’t declined the card before.
And finally, we can call the same method from a button click without checking for a previous decline (since the user is actually making the request).
These are the basic steps needed for wallet integration and the sample code can be downloaded here. If you’d like to know more about the wallet like payment cards and updating the wallet in the background, I highly recommend this video on Channel 9.