Quickstart: Creating and distributing Wallet item packages (.mswallet files)

This topic describes how to create Wallet item packages that can be distributed to users.

A Wallet item package is a zip container, with the .mswallet file extension, containing images and metadata (XML) that fully describes a personalized Wallet item that can be added to Wallet, such as a boarding pass, membership card, ticket, deal, payment instrument or a general card. Instead of adding items using the Wallet APIs, you can define these packages and your users can import them into Wallet. The added benefit of this approach is that the user doesn't have to have a particular app installed in order to add Wallet items from you into their Wallet.

Prerequisites

How a Wallet item package is imported into Wallet.

There are multiple ways a package can be imported into Wallet. The following table describes each scenario.

Files in a Wallet item package

Wallet item packages are stored as a zipped package with the .mswallet file extension (ex. "BlueYonder.mswallet") and have the mime type application/vnd.ms.wallet. The following files must be placed at the root level of the package.

Note  The files must be named as they are shown in the table.

When creating a Wallet item package, create the files described in the preceding table and add them to a Zip file and make sure the file is given the extension .mswallet. To test your package, send it to yourself as an email and when the email arrives on your phone, click on the attachment to import the package into Wallet.

WalletItem.xml

The definition of the Wallet item is contained in a file called WalletItem.xml in your package. This is an XML file that describes the type of item, the colors you want to use and various other properties. This XML file must adhere to the WalletItem.xsd schema. The schema can be downloaded from here. The following table describes the elements that can be defined in a WalletItem.xml file.

Example WalletItem.xml file

The following XML file shows an example WalletItem.xml file that defines a boarding pass for a fictitious airline called BlueYonder.

<?xml version="1.0" encoding="utf-8"?>
<WalletItem>
  <Version>1</Version>
  <Id>5609</Id>
  <WebServiceUrl/>
  <AuthenticationToken/>
  <ProductId />
  <Kind>BoardingPass</Kind>
  <DisplayName>Blue Yonder Airlines</DisplayName>
  <IssuerDisplayName>Blue Yonder Airlines</IssuerDisplayName>
  <Barcode>
    <Symbology>QR</Symbology>
    <Value>e.g. 012345678</Value>
  </Barcode>
  <DisplayMessage />
  <HeaderColor>#d4edff</HeaderColor>
  <BodyColor>#006fbf</BodyColor>
  <HeaderFontColor>#00094d</HeaderFontColor>
  <BodyFontColor>#fbfcfe</BodyFontColor>
  <LogoText />
  <DisplayProperties>
    <Header>
      <Property>
        <Key>Hd1</Key>
        <Name>Gate</Name>
        <Value>A2</Value>
      </Property>
    </Header>
    <Primary>
      <Property>
        <Key>Pr1</Key>
        <Name>New York City</Name>
        <Value>NYC</Value>
      </Property>
      <Property>
        <Key>Pr2</Key>
        <Name>Seattle</Name>
        <Value>SEA</Value>
      </Property>
    </Primary>
    <Secondary>
      <Property>
        <Key>Bp1</Key>
        <Name>BOARDS</Name>
        <Value>7:50A</Value>
      </Property>
      <Property>
        <Key>Bp2</Key>
        <Name>DEPARTS</Name>
        <Value>10:20A</Value>
      </Property>
      <Property>
        <Key>Bp3</Key>
        <Name>Flight</Name>
        <Value>1503</Value>
      </Property>
      <Property>
        <Key>Bp4</Key>
        <Name>ZONE</Name>
        <Value>4</Value>
      </Property>
    </Secondary>
    <Footer>
      <Property>
        <Key>Ft1</Key>
        <Name>Passenger</Name>
        <Value>Darrin DeYoung</Value>
      </Property>
      <Property>
        <Key>Ft2</Key>
        <Name>Seat</Name>
        <Value>20C</Value>
      </Property>
    </Footer>
  </DisplayProperties>
</WalletItem>

Tip  To set the Name or Value fields of a property to blank, use a non-breaking space. This is illustrated in the following XML examples.

Setting the Name field of a property to be blank

<!-- Setting the Name to blank -->
<Property>
  <Key>17</Key>
  <Name>&#160;</Name>
  <Value>MyValue</Value>
</Property>

Setting the Value field of a property to be blank

<!-- Setting the Value to blank -->
<Property>
  <Key>17</Key>
  <Name>My name or label</Name>
  <Value>&#160;</Value>
</Property>

Multi-language support

Wallet item packages support multiple languages so that the user will be a able to view your card in the language they've chosen for their phone. Localized content is located within locale-specific subdirectories of the package. Each locale folder can contain a single strings.txt file, which follows the text resource format. For more information, see Resources in Text File Format. Let's consider the following property element from BlueYonder boarding pass that was described in the preceding section, Example WalletItem.xml file.

<Property>
  <Key>Bp3</Key>
  <Name>Flight</Name>
  <Value>1503</Value>
</Property>

When a user has their phone set to German and views this card, it would be a better experience if the labels and values for all properties on the card were displayed in German. For example, we'd like to display the Flight label as Flug in this example. To enable this scenario in the Wallet item package, perform the following steps.

1. Create a folder in the package with the name de-DE. This is the BCP-47 directory name for German.

2. In the folder you just created, add a text file called strings.txt. This is the text file that will contain the translations for this language.

3. Open strings.txt in your favorite text editor and add the following lines.

       ; Label for the flight property
        Flight=Flug 
   

   The first line in the preceding example is an optional comment that you can add to clearly identify the intent of the translation.

4. Save strings.txt.

   Note  If you want to save and use German characters, save your text file using Unicode encoding rather than using a specific ANSI code page.

5. Repeat steps 1 to 4 for every language you want to support.

Locale folders can also contain locale-specific versions of any of the images for the item. The images must have the same name as the images in the root folder, for example \de-DE\Logo99x99.png. If a locale-specific image asset is not found for the current locale, the image in the root folder will be used instead.

Localized content is contained under separate subdirectories of the root of the Wallet item package, in BCP-47 directory names. The closest match to the user's current language settings are used. For example, if only es-ES is supplied in the package and the current locale is es-MX then es-ES will be used.

Associating a Wallet item package with your app

In the BlueYonder boarding pass that was described in the preceding section, Example WalletItem.xml file, the ProductId element was empty. This means that when the card is imported into Wallet it will not be associated with an app. This is advantageous, on one hand, because it means you don't have to have an app on the user's phone in order to promote your brand in Wallet. On the other hand, if the user has your app installed, the app will not be able to manage this boarding pass because it is not associated with your app. To link the card to your app, the ProductId element has to be set with the Id of your app. You can find that value in the Package.appxmanifest file of your app project. The following shows what this line looks like in a Package.appxmanifest file.

<mp:PhoneIdentity PhoneProductId="7cc7ccfd-973c-49b4-b7ca-1b05cd725705" PhonePublisherId="00000000-0000-0000-0000-000000000000" />

Updating a Wallet item package

Whenever Wallet is opened by the user or the user taps refresh, the phone will attempt to update the contents of each card that has a WebServiceUrl and AuthenticationToken defined. This is done by making a GET request to the RESTful web service service identified by the WebServiceUrl of the Wallet item. The following is an example of a request the phone makes to get an update for an item.

https://WebServiceUrl/1/walletitems/id

WebServiceUrl is the value of the WebServiceUrl property on the Wallet item and Id is the Id of the item to be updated. The AuthenticationToken that was provided in the WalletItem.xml file for this item will be automatically added as a header in the GET request. The web service should verify that this header value is valid when handling each request from Wallet.

If the above request is successful, the updated Wallet item package will be downloaded by the phone and the Wallet item will be updated. The following table lists the HTTP responses that the web service should provide.

Important  Wallet stops making any further requests for updates from the web service if it receives 100 service failure responses, HTTP codes of 300 or greater, and if it has received service failures for 30 consecutive days from this web service At that point, you will not be able to deliver new updates for Wallet items that were affected and must instead supply new Wallet item packages with new Ids.

Error codes when manually importing a package

If an error occurs when a user tries to import a .mswallet package manually, the UI will display an error message. The following table lists the possible HRESULT error codes that will be displayed to the user.

Summary and next steps

To see Wallet item packages in action, you download the following packages and email them to the account associated with your phone. You an then tap on the attachment in the email and import that package into Wallet.

• Blue Yonder example Wallet item package.
• Adventure Works example Wallet item package.
• Tailspin Toys example Wallet item package.
• Northwind Traders example Wallet item package.
• Coho Winery example Wallet item package.

Related topics

Quickstart: Using the Windows Phone 8.1 Wallet APIs

WaletItem.xsd schema definition