Toan Huynh

Technical Evangelist

Wallet Support and

In App Purchasing in

Windows Phone 8

Topics

• Wallet Overview

• Applications and wallet storage

• Wallet capabilities

• Creating and using a membership card

• Creating the card

• The Wallet Background Agent

• Creating and using a payment instrument card

• In App Purchases

• Adding products to your application

• Durable and Consumable items

• The purchase lifecycle

• The Application Programmer Interface

• Finding products

• Purchasing products

• Using product receipts

Wallet Overview

3

Windows Phone Wallet

• The Wallet is implemented as part of the Windows Phone

operating system

• The Wallet acts as a container for applications that can

store membership information and transaction data for

paid services

• The wallet provides an additional launching point for an

application

• The launch can be via a deep link to a page describing a

particular offer or service

8/14/2013‹#›

Wallet Storage

• Wallet information is held on a per-application basis

• An application can only interact with its own wallet

storage

• Each application will store information relating to the

services provided via that application

• Special offers

• Transactions

• Membership information

• Custom fields for that particular application

8/14/2013‹#›

Opening the Wallet

• The Wallet is supplied as part of the Windows Phone

• Users can store details of membership cards in the wallet

• These are linked to “wallet aware” applications on the phone

• The membership cards can be credit or debit cards, or any form

of membership tracking that you wish to add to your

application

• This includes transaction support and also allows you to alert

the user to any special offers or promotions associated with a

card

Storing data in the Wallet

• Users can store details of their cards inside the wallet

• They can add as many sets of card details as they like and the

wallet will store the details securely

• Each card is associated with an application that manages

transactions on that card

• They can PIN protect access to the wallet

• The wallet PIN can also be used to control access to Windows

Phone Store purchases

Navigating the Phone Wallet

• When the user opens the wallet they are shown a list of

all the cards that have been placed in there

• Each of the cards is bound to the application behind it

• When the card is opened the user has the option to start

the application behind that card

• This provides another way in which your application can

get started

• Uses can open their wallet, find your membership card

and run your application from there

8/14/2013‹#›

Using a Card

• When a user opens a card they can view the data for the card and

see their account information

• This is displayed by the Wallet

• They can also open the application from the Wallet entry

• A player could enter your multiplayer game from their wallet,

which would be the place you would store their user credentials

• The wallet also displays app supplied fields, for example balance

information

• This is text provided by the application behind the wallet

• It can also display transaction information for cards which are

payment instruments8/14/20139

Adding a New Card

• The user can add a new card by tapping the + in the

application bar

• They can also search for existing cards in the wallet

• Each card is identified by the first six digits of the card

number

• Once you have created a card you can then search for

applications that can perform transactions on that card

• If an application is found the card is then bound to that

application

8/14/201310

Adding a New Card via an Application

• Cards are only useful once they have been bound to

applications

• Card providers can create applications that are bound to

cards in the wallet

• The Wallet program provides a menu of applications from

“well known” card providers

• A user can create a card from one of these applications

• Your applications can also create cards for storage in the

wallet

8/14/201311

Adding Cards from within Applications

• Cards are linked with the applications that use them

• The app code must create and populate a

WalletTransactionItem instance and pass that to the

AddWalletItemTask which handles the storage in the

Wallet

• A WalletTransactionItem object contains a number

of standard fields

• Applications can add their own custom fields for their

own use

• Only the application that is bound to a card can access

the information in the card8/14/201312

Adding Cards from within Applications

• It is not possible for a card to be added to a wallet

without the user approving the action

• This prevents applications from “spamming” the wallet

with large numbers of cards

• The wallet also provides a means by which a user can

delete a card that they no longer use

8/14/201313

Wallet Enabled Applications

• A wallet application does not have to just manipulate money

• It could be any kind of club membership

• The wallet could contain membership details and any custom data about the club

• Each wallet entry can also store customised data for that application

• Achievements in a game, permission levels, responsibilities, etc

• Once an application is registered with the wallet it will appear alongside all the other

applications in the wallet

8/14/201314

Creating and using

a membership card

15

Wallet Applications and Capabilities

• If an application just wishes to use the Wallet to

store membership details and transaction logs it

just needs to enable the ID_CAP_WALLET

capability

• Any application can do this

• To use the payment instruments and store secure

elements in published applications you will have to

have those permissions added to your account

• Contact the Dev Center Support team to do this

8/14/201316

Creating a Wallet entry for an application

8/14/201317

WalletTransactionItem membershipItem;membershipItem = new WalletTransactionItem("Membership");membershipItem.IssuerName = issuer.IssuerName;membershipItem.DisplayName = issuer.IssuerName + " Membership Card";membershipItem.IssuerPhone.Business = issuer.IssuerPhone;membershipItem.CustomerName = details.CustomerName;membershipItem.AccountNumber = details.MembershipNumber;membershipItem.BillingPhone = details.PhoneNumber;membershipItem.IssuerWebsite = new Uri(issuer.IssuerWebSite);membershipItem.DisplayAvailableBalance = "1000 points"; membershipItem.Logo336x336 = new BitmapImage(new Uri("/images/BrSml.png", …));membershipItem.Logo159x159 = new BitmapImage(new Uri("/images/BrMed.png", …));membershipItem.Logo336x336 = new BitmapImage(new Uri("/images/BrLge.png", …));

AddWalletItemTask addWalletItemTask = new AddWalletItemTask();addWalletItemTask.Item = membershipItem;addWalletItemTask.Show();

Simple Wallet Use

• If you just want to store and manage membership information for your application the

wallet is a good way to do this

• Users can find and run your application from the Wallet

• The application can update the wallet membership properties to display information about

the status of the user

• This can be done simply by updating the text properties of the wallet information

• This will then be reflected in the wallet display

8/14/201319

The Wallet

Background Agent

20

The Wallet Background Agent

• Applications that use the wallet can also create a

Background Agent that can update the wallet on the phone

when the application is not being used

• The agent will also run when the user refreshes the card

from the Wallet

• Your application can use this in lots of different ways

• Update a list of transactions

• Inform the user of special offers

• Manage membership expiry

8/14/201321

Special Offer Display

• Special offers are displayed right next to the card details

• If the user activates the offer it will perform a deep link

activation of the application that can take the user directly

to the page for that offer

• The deep link is set by the background agent, so that the

application can identify the offer that has been made

8/14/201322

Creating a Wallet Agent

• A Wallet Agent works in a very similar way to other background tasks

• There is no template for the creation of the agent project

• Instead you have to create the agent as a class library and add it to the application

solution

8/14/201323

The Wallet Agent Project

• This is added to the solution just as with other agents

• The project output also needs to be added to the references of the application

8/14/201324

Adding the Wallet Background Task

• To link the agent to the application you need to modify the WMAppManifest.xml file for

the application

• The ExtendedTask item needs to be added, which sets the type of the agent and

identifies the assemblies to be used when it runs

8/14/201325

<Tasks><DefaultTask Name="_default" NavigationPage="MainPage.xaml" /><ExtendedTask Name="BackgroundTask">

<BackgroundServiceAgent Specifier="WalletAgent" Name="WalletAgent"Source="JumpstartWalletAgent" Type="JumpstartMembersClub.MyWalletAgent" />

</ExtendedTask></Tasks>

The Wallet Background Class

• This is the code that implements the agent

• The OnRefreshData method is called by the Windows Phone operating system to refresh

the wallet content

• It could use a web service to contact the host and do this

8/14/201326

public class MyWalletAgent : WalletAgent{

protected override async void OnRefreshData(RefreshDataEventArgs args){

// Update the wallet items supplied in the args parameterNotifyComplete();

}}

Adding a Special Offer on refresh

8/14/201327

protected override async void OnRefreshData(RefreshDataEventArgs args){

foreach (WalletItem item in args.Items) {WalletTransactionItem card = item as WalletTransactionItem;if (card != null) {

if (card.Id == "Membership") {card.Message =

"Cheese sale with special deals on Edam. Tap here for more details";card.MessageNavigationUri = new Uri("/CheeseDealsPage.xaml",

UriKind.Relative);await card.SaveAsync();

}}

}NotifyComplete();

}

Using the Special Offer

• The special offer text is displayed next to the card in the

wallet

• If the user taps the offer the application will be launched at

the page specified

• This works in the same way as a launch from any other deep

link

8/14/201328

Page Destination

• The background agent can define different entry pages

depending on the offer being made

• It can also include Query data in the URL which can be picked up

by the page and used to select particular behaviours

8/14/201329

Refreshing the Card

• The card will be refreshed before it is used for the first

time

• It can also be refreshed manually by the user

• When the refresh action is performed the

OnRefreshData method is called in the card agent

• The user can also delete the card and unlink it from the

application

8/14/201330

Deleting the Card

• The user can also delete the card and unlink it from the

application

• Unlinking is only a useful thing to do if other

applications can make use of that card

• The user can edit the card information, this will be

picked up by the application when it next uses those

card properties

• If the card has custom properties added by the

application they can be changed only by the card

application

8/14/201331

Simple Wallet Use in Applications

• You can use these methods to make any user of your application a “card carrying member”

• The card can hold custom information for users and also provide alerts about new services

• The card will appear in the wallet on the Windows Phone, which provides another point of

access to your application

• While you can perform “transactions” on a membership card these only affect the balance

displayed on the card

• There is no transaction storage in this form of card

• You can however manage a balance display for the card user

8/14/201333

Creating and using

a payment

instrument card

Payment Instrument Cards

• If you want to create a card that tracks transactions you need to create a

PaymentInstrument to hold the card information

• This manages a list of transactions that your application can add to and search through

• It is created and used in exactly the same way as the membership card

• To create a PaymentInstrument the ID_CAP_WALLET_PAYMENTINSTRUMENTS capability

must be set for the application

• The card serves only as a container for the application data

• The application must provide all the business logic to update and manage the card data

8/14/201335

Creating a PaymentInstrument

8/14/201336

PaymentInstrument accountItem;accountItem = new PaymentInstrument("Credit");accountItem.PaymentInstrumentKinds = PaymentInstrumentKinds.Credit;accountItem.IssuerName = issuer.IssuerName;accountItem.DisplayName = issuer.IssuerName + " Bank Card";accountItem.IssuerPhone.Business = issuer.IssuerPhone;accountItem.CustomerName = details.CustomerName;accountItem.AccountNumber = details.AccountNumber;accountItem.BillingPhone = details.PhoneNumber;accountItem.IssuerWebsite = new Uri(issuer.IssuerWebSite);accountItem.ExpirationDate = details.Expires;accountItem.DisplayAvailableBalance = "1000";accountItem.DisplayCreditLimit = details.CreditLimit.ToString("C");accountItem.DisplayAvailableCredit = details.AvailableCredit.ToString("C");

Creating a PaymentInstrument

• There are more properties to be set when a PaymentInstrument is created

• These must include the type of the card being made

• When working with payment information you need to be mindful of currency formatting in

the locale and culture where the phone is used

• An application can add this information to the payment instrument so that it can

customise the information display appropriately

• The example application on Windows Store shows how this is done

8/14/201337

Creating a transaction: Finding the Wallet

• The first stage in performing a transaction is finding the wallet to use

• The FindItem method will return null if the card is not found

8/14/201338

// Find the payment instrument to use PaymentInstrument walletPay;

walletPay = Wallet.FindItem("Credit") as PaymentInstrument;

if (walletPay == null){

MessageBox.Show("Wallet not found");return;

}

Creating a transaction: Setting the transaction details

• These transaction properties are required – shown here as hard-coded examples

• For your application they will reflect the actual action performed

• Note that the amounts are specified as strings

• They are textual descriptions of the actions performed

8/14/201339

// Create the transactionWalletTransaction transaction = new WalletTransaction();

transaction.DisplayAmount = "10";transaction.Description = "Cheese Purchase";transaction.TransactionDate = DateTime.Now;

Creating a transaction: Storing the transaction

• The TransactionHistory property of a PaymentInstrument is implemented as a

dictionary that is indexed on a transaction identifier string

• Each identifier string must be unique or the Add action will fail

• The SaveAsync method commits the action to the actual wallet

• It is an asynchronous operation and so the method performing this action must be made

async

8/14/201340

// Add the transaction to the walletwalletPay.TransactionHistory.Add("Cheese Purchase " + DateTime.Now, transaction);

await walletPay.SaveAsync();

MessageBox.Show("Transaction stored");

Viewing Transactions

• Transactions are stored in the wallet and can be

viewed in along with the card data

• The transaction list is only displayed once some

transactions have been added

8/14/201341

Demo

Demo 3: Using a Payment Instrument

Payment Instruments

• A payment instrument can be used as a store for credit and debit card details and

transactions that have been performed on them

• However, the card does not implement any of the banking behaviours as such

• The application must perform the management of the account information

• The Wallet infrastructure will provide a display mechanism and bring all the account

management activity into one place

8/14/201343

In-App Purchases

In-App Purchases

• In Windows Phone 7.x it was only possible to sell an application at a fixed price through

the Windows Phone Marketplace (now the Windows Phone Store)

• This was the only way you could get paid for the application

• The Windows Phone 8 application environment allows the developer to create an

application that contains paid content

• The Microsoft Store will issue licences for items that have been purchased by the users of

your application

• You can use this to activate application features or provide in-application resources, such

as items in games

8/14/201345

Build apps with higher and recurring revenue

opportunity

Customize

Add and modify different paid

options for different user

segments

Extend reach

Attract a larger user base with

free baseline experience

Upsell

Upsell users to purchase paid

digital goods and services that

enhance or extend the app

experience in the app itself

In-App Purchase

In-App Purchase used for digital content

Offer digital assets

Durables: buy once & own forever, e.g. new game levels, maps, game items

Consumables: game currency, movie rentals, access to digital magazines for 6 months, etc.

Integrate In-App to app experience

Manage, monitor and respond

In-App Purchase: sell items in your app

Putting Products into the Microsoft Store

• As well as submitting applications to the store it is also possible to submit products for

purchase by users

• These will be purchased in just the same way as games, using the same payment

mechanism

• Products can then be assigned to a particular application

• This is performed using the Windows Phone Store Dashboard for that application

• The application can initiate purchases of the products

• The Microsoft Store retains licence information for the products that a user can purchase

• The application can determine which products have been purchased

8/14/201349

Creating an Application that uses products

• The developer creates the application and submits it to the Windows Store

8/14/201350

Developer

Application

Windows

Store

Submit app

Creating an Application that uses products

• The developer creates the list of products that can be sold alongside applications

8/14/201351

Developer

Application

Windows

Store

Submit app

Submit products

Creating an Application that uses products

• When the application runs it can request a list of products that are associated with that

application

• This list can be used to drive in-app purchasing options

8/14/201352

Developer

Application

Windows

Store

Submit app

Submit products

Get product list

Creating an Application that uses products

• The user can initiate the purchase operation

• This is managed in just the same way as Windows Store purchases

8/14/201353

Developer

Application

Windows

Store

Submit app

Submit products

Get product list

Purchase Products

Creating an Application that uses products

• When the application starts, and after a purchase operation, it can activate the purchased

feature or load the purchased content

8/14/201354

Developer

Application

Windows

Store

Submit app

Submit products

Get product list

Purchase Products

Get licences

Creating an Application that uses products

• The store will also supply a digitally signed receipt that can be used to manage access to

external resources provided to the user via the application

8/14/201355

Developer

Application

Windows

Store

Submit app

Submit products

Get product list

Purchase Products

Get receipt

Product Provision

• If the purchase relates to an in-application durable or consumable it is the responsibility of

the application writer to ensure that access to this is managed correctly and securely

• If the user buys the “Save” option for the program this should be enabled after the

purchase and each time they run the application

• If the player buys 1,000 health points it is up to the application to ensure that the health

is adjusted accordingly

• If the player buys a digital item (image, music) the application should ensure that this is

delivered to the application

• This may mean that the application must use the purchase receipts in conjunction with

their own systems

8/14/201356

Enumerating Listings for in game products

• The creator of this game has added two products, “Special Cheese” and “Ultra Cheese”

which can be used in the game

• These products have been assigned to this game

• The game can then request listing information for these items that will be used to manage

the purchase of the items

• The ids for these products are given in an array to the load method

• Once the items have been purchased the application can then validate this against the

store8/14/201357

ListingInformation listings = await CurrentApp.LoadListingInformationByProductIdsAsync(

new string[] { "Special Cheese", "Ultra Cheese" });

Making an in-application purchase

• This statement purchases the “Special Cheese” product

• The second parameter (in this case false) determines if a receipt is

to be provided for the purchase

• This is an asynchronous operation

8/14/201358

await CurrentApp.RequestProductPurchaseAsync("Special Cheese", false);

Using a Digital Receipt

• An application can request a digital receipt for a particular purchase

• The receipt is provided as a string of XML containing the transaction details

• This can be used to authenticate resources access on another service operated by the

application

8/14/201359

string receiptXml = await CurrentApp.GetProductReceiptAsync("Cheese Music");

Checking if a licence has been purchased

• This is the code used to determine if the product has been purchased

• The application reports that the purchased item has been delivered to the user by calling

the ReportProductFulfillment method and identifying the purchased item

• If the product is a consumable it can be purchased again

• The application must securely store the new status setting8/14/201360

var productLicenses = CurrentApp.LicenseInformation.ProductLicenses;var licence = productLicenses["Special Cheese"];

if (licence.IsActive){

// enable Special Cheese PowerCurrentApp.ReportProductFulfillment("Special Cheese");

}

Managing the state of a consumable

• A consumable item can be purchased multiple times

• Each time it is purchased the application must make the appropriate changes to the status

and report that it has been delivered

8/14/201361

var productLicenses = CurrentApp.LicenseInformation.ProductLicenses;var licence = productLicenses["Cheese Power Points"];

if (licence.IsConsumable && licence.IsActive){

// add the extra pointscheesePower = cheesePower + 200;CurrentApp.ReportProductFulfillment("Cheese Power Points ");

}

In-App Purchases

• In-App purchases provide a very powerful way of monetising an application

• It is now possible to move from “Trial Mode” to “Full Version” without needing the user

to download a new application

• Remember however that the responsibility for managing the in-application products

purchased is yours

• It is important that the application protects the purchases that have been made by users

of the program

8/14/201362

Review

• Applications in Windows 8 can use the Wallet to manage membership information for users

• The Wallet Agent allows an application to update special offers and other information

automatically

• The Payment Instrument mechanism provides a way that transactions can be stored and

viewed on Windows Phone

• Applications can now provide a menu of products which can be purchased from within the

program

• These can be consumable (can be bought multiple times) or durable (are bought once)

• The Windows Store will track licences that have been purchased for an item and provide

receipts that can be used to authenticate resource access

63

The information herein is for informational

purposes only an represents the current view of

Microsoft Corporation as of the date of this

presentation. Because Microsoft must respond

to changing market conditions, it should not be

interpreted to be a commitment on the part of

Microsoft, and Microsoft cannot guarantee the

accuracy of any information provided after the

date of this presentation.

© 2012 Microsoft Corporation.

All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries.

MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION

IN THIS PRESENTATION.