Deploying a PhoneGap app to Windows Marketplace

After Deploying a PhoneGap application to iTunes (App Store) and Deploying a PhoneGap app to Google Play articles, here comes the time to deal with Windows Mobile platform and Windows Marketplace. This article should provide you with all the necessary information on how to successfully submit your .xap file (compiled locally or through Phonegap Bulid) to Windows Marketplace.

Running your application on mobile device

Before we actually begin, let’s deal with this one. There are many tutorials, that claims, that all you need to install a .xap file on any Windows Phone system, is to copy this file to SD card of your phone, navigate to Market place application and select Install Local Apps from it’s context menu. To be honest: this is all a bull-shit! Out of all of these tutorials, this one points out the key information (point 9), saying:

If the .xap file does not map to anything already in the Marketplace, the installation will be terminated.

So, as you can see, you can install only .xap files downloaded from Marketplace, using offline installation link. There is absolutely no way to install PhoneGap Build’s generated file using this approach. Period. You must publish your application to Windows Marketplace to be able to install it on any device!

Sign up for a Windows developer account

Start with sign up page, then:

1. Click on Join Now and pick your country and/or region.
2. Pick account type (most likely it will be Individual) and click on Enroll now.
3. Fill out long form. If you selected an individual account type, which is best for single developer or small group of enthusiasts, then you must provide your real name and other stuff (shouldn’t be public), but you should be able to pick your group name as developer’s public name.
4. Accept terms and pay for your membership. You can pay through PayPal or by directly providing credit card details. One-time registration fee is only 19 USD (including applicable taxes and fees), which is the lowest registration fee among “the big three”.
5. Once your payment is confirmed, you will be asked to which dashboard you want to continue — to either publish an app to Windows Dev Center or Windows Phone Dev Center.

Even though registration fee is one-time payment, Marketplace enforces you to configure your credit card or PayPal account in a recurring payment mode. Be careful, because any additional payments may be executed without your prior agreement. If you have any doubts about this, go to Payments Hub and remove your payment method set there. However, if this is your only one payment method, you must provide another one or contact support.

Once more, to make you sure, the Windows Dev Center fee has been changed from annual to one-time on September 17, 2014. You can additionally verify this here, where it is clearly said:

Developer accounts don’t expire. You won’t need to renew your account in order to keep your apps in the Store.

However, it seems that, however, one years wasn’t enough to fix payments settings and you’re still obligated to accept a recurring payments scheme, when enrolling to this developer program. The same goes for all confirmation emails, which still claims, that you have paid for just a one year registration fee.

Set up payment account and tax profile

You may, of course, omit this section, if you’re going to publish free applications only.

If you want to charge users for your applications or offer in-app purchases, you need to setup payment account and tax profile right now. You will have to do exactly the same (separate pair of forms) if you want to display ads in your Windows application (using Microsoft Advertising platform, also known as pubCenter). However, since I’m using (and strongly suggesting) [AdMob ads with AdMob Plugin Pro](Displaying ads in pure-Javascript PhoneGap Build-only application with AdMob Plugin Pro.txt), I won’t discuss this matter.

Go directly to “Set up your payment account” or pick Set up payment account icon in your developers console. Microsoft allows to use PayPal account for collecting incomes, which is much easier than fillng entire form for bank wire transfers. I do have (and like to use) PayPal account, so I won’t discuss latter option. See for yourself, if you need to setup payments to be sent to your bank account instead. Read more here about collecting money earned by your applications.

Keep in mind, that you have provide information exactly as it is set in PayPal. If, for example, PayPal recognizes you with two first names, you must put both into First name field, when setting your payment account. Adding only first first name will most likely fail.

Now, follow to Set up your tax profile page to… set up your tax form. Fill up all the necessary forms. Microsoft is much more tough (serious) about taxes. Where (at Android and many other services) all you need to do is to provide your VAT number, here you have to answer a lot of strange questions and fill up different forms. For example, as a non-US citizen, I had no bloody idea, what should I pick at “Select W-8 form type” screen. I picked W-8BEN, because it was selected by default. You’ll need a PIN code, emailed to you during process, to finish this forms, so pay close attention to messages comming from cticompliance.com (operates tax-related issues on behalf of Microsoft) and optionally add this domain to your white-list.

Note, that sometimes, after pressing Sumbit you get redirected to a blank page and after comming back to your Dev Center’s home page, you learn, that your tax form wasn’t actually submitted. For this purpose, make use of Save button everywhere it is possible, to avoid need of reentering data.

Also note two thing about publishin paid apps. First of all, it can take significant amount of time since you set up your payment account and tax profile until you’ll be able to pick a price for your app. In my case, it was nearly 24 hours. Second of all, you can’t enter a free-hand price for your app, as you’re limited only to certain fixed prices, ranging from .99 USD to 999.99 USD, including around 25-30% Microsoft commission (and taxes?), and already recalculated for your local currency. So, for example, for Poland-based app submitters, the lowest possible price (as of writing this) was 4.50 PLN, which equals to 1.29 USD, which is 0.99 USD of your true earning plus 0.3 USD commission (and taxes?).

Sign your Windows apps in PhoneGap Build

On contrary to Android and iOS, for signing application build by PhoneGap Build you don’t need any kind of certificate or signing key. You only need your Publisher ID. You’ll find it in Account settings > Account details section of Windows Dev Center section in your Dev Center page.

Pick Edit account from menu that appears, when you click your avatar next to Adobe logo in top-right corner and go to Signing Keys section. Click add a publisher ID ... button below Windows Phone. Enter any title (used only to identify this key for you, in case you’d be using more than one) and publisher ID. Finally, hit the submit key button to confirm.

Go to your selected application screen, select your newly added publisher ID from No key selected dropdown menu. Immediately after that your application will be rebuild. Once this is done, you can download your .xap file. It should be ready for an app submission to Windows Marketplace.

Prepare yourself for an app submission

This is a long journey through many sections filled up with a lot of form fields and placeholders for file uploads. Don’t sit down to this task, when you have 15 minutes or you’ll most likely fail. Reserve at least 1-2 hours. Hopefully, you’re doing this only once for each application (you don’t need to repeat most of these steps when publishing an update) and you can reuse information provided here, when publishing application to other app stores.

As of writing this, you need following “resources” to get your app published to Google Play:

• title,

• store description (up to 5000 characters),

• hi-res icon in 300×300 px dimensions (note, that transparency actually looks ugly, so don’t use it),

• at least 1 screenshot (and up to 8 screenshots) per each of three resolutions:

  • WXGA 1280×768 px,

  • 720p 1280×720 px and

  • WVGA 800×480 px), but

  • you have an option (default) to auto-generate last two (smaller) basing on first (biggest).

Never use screenshots captured on other device or system (i.e. Android or iOS) and only edited to fit above dimensions. If you do so, then most likely your application submission will fail with feedback, that screenshots must contain direct captures of the Windows application.

If your application’s impression page supports many languages in Windows Marketplace, you need to prepare all these in all languages!

Since image submission is quite slow in Windows Dev Center, consider using Upload all link and selecting all files at once. They’ll be correctly positioned to proper placeholders, basing on their dimensions. Note, that all graphic files must be .pngs.

There are some additional images, you can provide for your application. You can also provide up to six exact search keywords, that will point users using search mechanism to your application. See for yourself.

There are two key differences, you need to consider, when preparing yourself to publish your application to both Google Play and Windows Marketplace:

1. Providing your valid email address is optional in Windows Marketplace. If you don’t publish a support email address, you will still be able to receive all user reviews, only they’ll be available in Reviews tab of your app details screen and won’t be pushed to your email. On Google Play, providing a valid email address is required and this address is always public, printed out below your application impression at Google Play.
2. Think carefully in how many languages you want provide description for your application in Windows Store. Because you must declare all these language in your application before you prepare your *.xap file and because each change to this will require you to provide screenshots and descriptions of your app in all languages it support.

Before you begin, choose carefully, which browser you’re going to use for the purpose of app publishing. App uploading and describing (second step, see below) is based on Microsoft Sliverlight technology, which isn’t supported by most browsers. For example, newest versions of Chrome (42 and up) does not support Silverlight anymore and you need to either choose another compatibile browser or follow workaround steps described here. I don’t like Internet Explorer and Silverlight, but I even more don’t like Google NPAPI-compatible plugins support removal from newest Chrome. So, for a sake of time, I dropped Chrome and went to Internet Explorer.

Publish your first app

Now, it is time to go to Apps section and make use of Submit app button.

As you can see, submission process seems much simpler than in case of Google Play. You have only two sections required (general app information plus description and showcase of your app) and three optional (in-app advertising, if you’re not using an external source like AdMob plus market selection and pricing plus map services, if you’re not using an external provider like Google Maps API or leaflet.js).

In first of required sections (App info) you register your new application name and provide basic information like app name, category, it fits in, and basic pricing (actually, one general price, which can be further tuned up in one of optional sections). Make sure, that app name, you reserve in this screen, matches exactly name defined in config.xml in <name> field or else, you won’t be able to submit your app. You’ll see error saying, that this package uses name, that has not been reserved for it instead.

In second of two requires sections (Upload and describe your package) you build your app experience for end user, which includes descriptions, search keywords, screenshots and other images. Refer to previous section for a list, what you should have prepared.

If is up to you, whether you use Microsoft’s pubCenter and ad mediation services (first of optional sections, Add in-app advertising) or some external source for displaying ads in your mobile apps pushed to Windows Marketplace. However, read this information before making final decision, because not all ad networks are supported and there are significant changes coming in general to ad serving in Windows apps.

Define market pricing, second optional section, lets you set different price for each country, where Marketplace offers purchasing paid apps and exclude certain countries to make your paid app not available at all in that particular market.

In last optional section, Map services, you can get a token required for using Map services in your application. I have never used this section, but I assume, that this token is required only, when you want to use Nokia OVI Maps. If you’re using an external map provider, like leaflet.js or Google Maps API, you shouldn’t be required to visit this section.

Since all should be done and ready at this stage, you may hit Review and submit button to continue. Keep in mind, that review section includes only basic information and does not include your app’s feel and look in Marketplace. Go back to Upload and describe your package (second required) section to verify, that everything is OK, before you hit Submit button.

After clicking that button, you should see “App submission successful” confirmation screen with an information, that for first publication of new apps, it can take up to five business days for certification process, until your app reaches Marketplace. And for updates of already certified apps, it should take no more than few hours. In both cases, on contrary to Android, you should receive a confirmation email, that your app is publicly available in Marketplace (or that you’re now ready to make it public, if you chosen manual app publication).

In the mean time you can read “Understanding app and in-app product submission” article. However, keep in mind, that “mean time” may be really short for you. On contrary to above cited Microsoft statement, it took only 30-40 minutes since initial submission for my application to have Published status. According to above mentioned article, it should take up to 24 hours for the app to show up in the Store. This declaration may be related to when your app will be searchable in Store. Because, nearly right after publication, you should be able to display its page. You’ll find direct link to your app in app details on Details tab (second to the right).

Since introduction of unified dashboard, which allow developers to publish application for both Windows 8 / Windows 10 and Windows Phone. It is called and universal application and you may find more details about this here, if you’re interested.

Glitches

Windows Dev Center and Windows app submission process aren’t that obvious and easy as in case of Android. There are few glitches and strange things, you may expect. Including doubled application (even though your application is published to store, you can see exactly the same copy of it in In-progress submissions group; in this case, simply delete the second copy).

You also should keep in mind, that even if you change few letters in one of app’s description field and nothing else, your app even so will be “hanged” for another review and won’t be available in store. Fortunately, this usually takes no more than 15-30 minutes. To avoid that, proof read every text and double check each field and file before initial submission.

Further readings

That’s all, what I have to say about deploying a PhoneGap app to Windows Phone Store. If you found anything, that needs further clarification or run into some questions without answer, then “Submit your app” article in Windows Dev Center may be your good start-point in seeking for some help or more information.