Oliver Scheer

Senior Technical Evangelist

Microsoft Deutschland

http://the-oliver.com

Wallet Support andIn 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

04/12/2023‹#›

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

04/12/2023‹#›

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

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

04/12/2023‹#›

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

04/12/20239

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 instruments

04/12/202310

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

04/12/202311

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

04/12/202312

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 card

04/12/202313

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

04/12/202314

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

Creating and using a membership card

15

04/12/202316

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

04/12/202317

Creating a Wallet entry for an application

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();

DemoDemo 1: Creating a Club

04/12/202319

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

The Wallet Background

Agent20

04/12/202321

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

04/12/202322

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

04/12/202323

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

04/12/202324

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

04/12/202325

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

<Tasks> <DefaultTask Name="_default" NavigationPage="MainPage.xaml" /> <ExtendedTask Name="BackgroundTask"> <BackgroundServiceAgent Specifier="WalletAgent" Name="WalletAgent" Source="JumpstartWalletAgent" Type="JumpstartMembersClub.MyWalletAgent" /> </ExtendedTask></Tasks>

04/12/202326

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

public class MyWalletAgent : WalletAgent{ protected override async void OnRefreshData(RefreshDataEventArgs args) { // Update the wallet items supplied in the args parameter NotifyComplete(); }}

04/12/202327

Adding a Special Offer on refresh

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();}

04/12/202328

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

04/12/202329

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

04/12/202330

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

04/12/202331

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

DemoDemo 2: Using a Wallet Agent

04/12/202333

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

Creating and using a payment instrument card

04/12/202335

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

04/12/202336

Creating a PaymentInstrument

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");

04/12/202337

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

04/12/202338

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

// Find the payment instrument to use PaymentInstrument walletPay;

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

if (walletPay == null){ MessageBox.Show("Wallet not found"); return;}

04/12/202339

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

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

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

04/12/202340

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

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

await walletPay.SaveAsync();

MessageBox.Show("Transaction stored");

04/12/202341

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

DemoDemo 3: Using a Payment Instrument

04/12/202343

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

In-App Purchases

04/12/202345

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

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 Purchase8.0

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.

Hand’s OnA test of dexterity

Coffee CupCustom hot beverages

Global ReachA strategy exercise

8.0

Define In-App ItemUse App Hub to define Consumable (bullets) or durable (guns)

Integrate In-App to app experienceUse SDK to sell items

Choose Countries and PricingUse App Hub to define item price; change as frequently as needed

Manage, monitor and respondUse App hub to manage sales reports, by item, region, date

Large Bag of Coins

Use the golden coins to buy food and clothing for your game pet, and help it grow faster!.

Price $1.99

In-App Purchase: sell items in your app8.0

04/12/202349

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

04/12/202350

Creating an Application that uses products

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

Developer

Application

Windows Store

Submit app

04/12/202351

Creating an Application that uses products

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

applications

Developer

Application

Windows Store

Submit app

Submit products

04/12/202352

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

Developer

Application

Windows Store

Submit app

Submit products

Get product list

04/12/202353

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

Developer

Application

Windows Store

Submit app

Submit products

Get product list

Purchase Products

04/12/202354

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

Developer

Application

Windows Store

Submit app

Submit products

Get product list

Purchase Products

Get licences

04/12/202355

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

Developer

Application

Windows Store

Submit app

Submit products

Get product list

Purchase Products

Get receipt

04/12/202356

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

04/12/202357

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 store

ListingInformation listings = await CurrentApp.LoadListingInformationByProductIdsAsync( new string[] { "Special Cheese", "Ultra Cheese" });

04/12/202358

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

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

04/12/202359

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

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

04/12/202360

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 setting

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

if (licence.IsActive){ // enable Special Cheese Power CurrentApp.ReportProductFulfillment("Special Cheese");}

04/12/202361

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

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

if (licence.IsConsumable && licence.IsActive){ // add the extra points cheesePower = cheesePower + 200; CurrentApp.ReportProductFulfillment("Cheese Power Points ");}

04/12/202362

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

63

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

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.