Condividi tramite

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

  • Articolo

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.

Scenario Description
User selects a .mswallet item from a website The user will be prompted to add the item to Wallet.
User selects a .mswallet item from an email The user will be prompted to add the item to Wallet
The phone fetches an updated .mswallet item from a 3rd party service The item will be downloaded from the 3rd party service without prompting the user. This happens when the user opens Wallet or when they tap refresh. The system will try to download an update for each package that has a WebServiceUrl and AuthenticationToken defined.
An app adds Wallet item package using the Wallet APIs. The app uses the ImportItemAsync method to process a Wallet item package. The package must be associated with the app. The API will prompt the user whether they want to add & review if it’s a new item as appropriate. This scenario is demonstrated in the Wallet Quickstart sample. For more information about the Wallet APIs, see Quickstart: Using the Windows Phone 8.1 Wallet APIs.

 

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.

File Name Required Description
WalletItem.xml Required An XML file that describes the item.
Logo99x99.png Required Small logo of the Wallet item.
Logo159x159.png Required Medium logo of the Wallet item.
Logo336x336.png Required Large logo of the Wallet item.
Logo.png Optional The logo of the issuer of this item.
HeaderBackground.png Optional The image to display behind the header of the item.
BodyBackground.png Optional The image to display behind the body of the item.
PromotionalImage.png Optional The image to display on the back of the item.
Locale folders Optional Each folder can contain localized string and image assets. For more information, see Multi-language support

 

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.

Element Name Required Description
Version Required Version number of the Wallet item package. Only a value of 1 is supported.
Id Required Identifier of the Wallet item. This value is only required if you are enabling updates of the item through a web service and you have therefore supplied a value for WebServiceUrl and AuthenticationToken.
WebServiceUrl Required for updates. URL of the 3rd party service from which updates will be pulled by the phone. Must be https:// unless the device is developer unlocked.
AuthenticationToken Required for updates. Used for authenticating the item with the 3rd party service.
ProductId Optional Id of the application associated with the item.
Kind Required Identifies the type of the item. The following list defines all valid values for this element.

Deal General PaymentInstrument Ticket BoardingPass MembershipCard
DisplayName Required
IssuerDisplayName Required
HeaderColor Required Specify color in #rrggbb format.
BodyColor Required Specify color in #rrggbb format.
HeaderFontColor Optional Specify color in #rrggbb format.
BodyFontColor Optional Specify color in #rrggbb format.
LogoText Optional This is displayed at the top of the item's details view beside the logo image, if one was provided.
ExpirationDate Optional W3C date as a string.
Barcode\Symbology Optional Specifies the format of the bar code image to generate. The following list defines all valid values for this element.

UPCA UPCE EAN13 EAN8 ITF CODE39 CODE128 QR PDF417 AZTEC
Barcode\Value Optional The data to encode using the specified Barcode\Symbology.
DisplayMessage Optional The message that will be shown in the item's details view.
IsDisplayMessageLaunchable Optional Determines whether tapping on the DisplayMessage will launch the app associated with this item. This is only applicable if the ProductId element has been set.
DisplayProperties\Header\* Optional Possible parent elements of one or more Property elements. Each element can only appear once. The number of child Property elements that are allowed for Header, Primary, Secondary, Center and Footer is determines by the WalletItem schema.
DisplayProperties\Primary\* Optional Possible parent elements of one or more Property elements. Each element can only appear once. The number of child Property elements that are allowed for Header, Primary, Secondary, Center and Footer is determines by the WalletItem schema.
DisplayProperties\Secondary\* Optional Possible parent elements of one or more Property elements. Each element can only appear once. The number of child Property elements that are allowed for Header, Primary, Secondary, Center and Footer is determines by the WalletItem schema.
DisplayProperties\Center\* Optional Possible parent elements of one or more Property elements. Each element can only appear once. The number of child Property elements that are allowed for Header, Primary, Secondary, Center and Footer is determines by the WalletItem schema.
DisplayProperties\Footer\* Optional Possible parent elements of one or more Property elements. Each element can only appear once. The number of child Property elements that are allowed for Header, Primary, Secondary, Center and Footer is determines by the WalletItem schema.
DisplayProperties\Property\Key Optional The property key.
DisplayProperties\Property\Name Optional The display name, or label, of the property.
DisplayProperties\Property\Value Optional The value of the property.
DisplayProperties\Property\NumberFormat Optional If the value of the property is a number, you can define the number format to use. The following list defines all valid values for this element.

Decimal Percent Exponential Currency
DisplayProperties\Property\CurrencyCode Optional ISO 4217 currency code. Element cannot be used with NumberFormat or DateTimeFormat.
DisplayProperties\Property\DateTimeFormat Optional

Format of the property value as a DateTime. The following list defines all valid values for this element.

FullDateTime LongDate LongTime MonthDay ShortDateTime ShortDate ShortTime YearMonth .
DisplayProperties\Property\AutoDetectLinks Optional Makes any property value that looks like a phone number, address or URL clickable.
DisplayProperties\Property\SummaryViewPosition Optional If this element exists, it indicates the property to display in the list view and the order that property appears in the list view. The value is an integer and can be either 0 or 1 which determines whether the property is displayed in the first or second position. If set, the value of the property is displayed in the list view without the label. If two properties have this element set, then the values are displayed in “{0}, {1}” format.
IsMoreTransactionHistoryLaunchable Optional Determines whether an option to see more transactions is available in the item transactions view. Clicking this option launches the app with an applicable activation event.
TransactionHistory\TransactionItem\Description Optional A description of the transaction.
TransactionHistory\TransactionItem\DisplayAmount Optional A string representing the amount of the transaction, for example, "$123.45"
TransactionHistory\TransactionItem\Id Optional A string identifier of the transaction item. A linked app can refer to this transaction using this ID.
TransactionHistory\TransactionItem\DisplayLocation Optional A string representation of where the transaction took place, for example, "Contoso on 3rd Ave."
TransactionHistory\TransactionItem\TransactionDate Optional The XML datetime of the transaction.
TransactionHistory\TransactionItem\IgnoreTimeOfDay Optional Whether to display the time of the transaction, or just the date.
TransactionHistory\TransactionItem\IsLaunchable Optional Whether the user can tap on the transaction item to launch a linked app and get more information. When the linked app is launched in this manner, the will contain the value of the ActionKind property on the WalletActionActivatedEventArgs will be set to Transaction.

RelevantLocations\Location\Latitude

RelevantLocations\Location\Longitude

RelevantLocations\Location\Altitude

RelevantLocations\Location\DisplayMessage

 Optional*

If a Location element is specified, then Latitude & Longitude elements must exist. Other elements are optional.

Zero or more locations where the item is relevant, for example, stores where a loyalty card can be used or the location of a concert where a ticket can be used. All values are doubles, except for Description which is a string.

RelevantDate\Date

RelevantDate\Description

 Optional*

If the RelevantDate element exists then Date must be provided. Description is optional.

Specifies a single date when then item is relevant, for example the date of the concert.

 

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.

HTTP response code Description
200 Success. The response payload contains the updated data for the specified item.
401 Request was not authorized. For example, an invalid AuthenticationToken was supplied in the header of the GET request or the Id of the item is invalid.
304 If the specified item has been updated previously by Wallet, the GET request will contain an If-Modified-Since header. If the web service determines that the item has not been modified since the value specified in this header, it should send a 304 response code.

 

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.

HRESULT error code Description
0x803A0050 The Version element in WalletItem.xml is missing or its value is not 1.
0x803A0051 The ProductId element in WalletItem.xml has an invalid value. Specify a GUID enclosed in curly braces {}.
0x803A0052 The Id element is missing. It must be supplied when a value for WebServiceUrl has been specified. If no value for WebServiceUrl exists, you can omit a value for Id because one will be auto-generated internally. The app can find all items using GetItemsAsync.
0x803A0053 The Kind element in WalletItem.xml has an invalid value.
0x803A0054 A Location element in WalletItem.xml has missing or invalid child elements. Verify that the Latitude and Longitude child elements exist and are valid.
0x803A0055 Verify that the values for all Color elements such as HeaderColor, BodyColor, HeaderFontColor, BodyFontColor. The values should be specified in #rrggbb format.
0x803A0056 The ExpirationDate element in WalletItem.xml contains an invalid value.
0x803A0057 The value of the WebServiceUrl element in WalletItem.xml is invalid. It must start with https:// unless the device is developer-unlocked, in which case it can alternatively begin with http://.
0x803A0058 WalletItem.xml must contain a value for AuthenticationToken, if it contains a value for the WebServiceUrl element.
0x803A0060 The DisplayName element is missing from WalletItem.xml.
0x803A0061 The IssuerDisplayName element is missing from WalletItem.xml.
0x803A0062 The Date or Description child elements are missing from a TransationItem element in WalletItem.xml or the value of a child element of TransactionItem is invalid.
0x803A0063 A child element of the Property element in WalletItem.xml contains an invalid value.
0x803A0064 The Symbology element in WalletItem.xml contains an invalid value.
0x803A0065 The Wallet item package is missing one or more required images - Logo99x99.png, Logo159x159.png or Logo336x336.png.
0x803A0066 A strings.txt file from a locale folder in the Wallet item package could not be parsed.
0x803A0067 A Relevant date element is missing a Date child element or a child element contains an invalid value.

 

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.

Quickstart: Using the Windows Phone 8.1 Wallet APIs

WaletItem.xsd schema definition