Completing the Skill Manifest

So far, we’ve barely touched the skill manifest, only tweaking it slightly to enable permissions for accessing a user’s given name, send reminders, and trigger notifications. While developing a skill, the values in the skill manifest aren’t that important. But before we can publish our skill, we need to ensure that the skill manifest completely and accurately describes our skill.

Specifying Publishing Information

The skill-package/skill.json file contains a section under the publishingInformation property that we’ll need to edit to be ready for publication. That section, unchanged from when we first initialized our skill from the “Hello World” template, looks like this:

This section of the manifest describes the skill details as they’ll appear in the Alexa application. Obviously most of what’s there now is just placeholder information (as evidenced by the use of the word “sample”). We’ll want to edit this section to accurately describe our skill so that potential users may discover it, and so actual users may recognize it when it appears in the Alexa application.

The first thing we’ll need to do is flesh out the locales property. Currently, it only contains an entry for U.S. English, although our skill supports all English and Spanish-speaking locales. Even for the “en-US” locale, the information given is just placeholder information.

After updating the locales property to cover both English and Spanish locales, it will look like this:

This is, of course, abridged to only show one locale for each language. The “en-US” entry will be duplicated for “en-AU”, “en-CA”, “en-GB”, and “en-IN”. Likewise, the “es-ES” entry will be duplicated for “es-MX” and “es-US”.

One thing to keep in mind is that the first locale listed will be the first offered in the developer console’s testing tool. Therefore, it’s a good idea to list your default locale first in the locales property so that you won’t have to explicitly select it while testing your skills.

After locales, the next two properties are isAvailableWorldwide and distributionCountries. When isAvailableWorldwide is set to true, it indicates that the skill should be available to all Alexa users in all countries. While it’s easy to leave it as true, if your skill is only intended for specific countries, you can set it to false and then list the supported countries in the distributionCountries property like this:

Each country listed in distributionCountries should be a two-letter country code in ISO 3166-1 alpha-2 format.^[41]

Next is the testingInstructions property. This property should supply any special instructions to the Amazon certification team that will test the skill, including any prerequisites. In the case of the Star Port 75 Skill, we should tell the testers to have a Google Calendar account:

Finally, the category property specifies how the skill will be categorized. This helps potential users find our skill, when browsing skills in the Alexa companion application, and understand what purpose it serves. There are several categories to choose from^[42] but the “NAVIGATION_AND_TRIP_PLANNER” category seems to suit our skill best:

Now that our skill manifest seems to be more fleshed out, we can deploy it and see how it appears in the companion applications. After deployment, it looks a little like this in the browser-based Alexa application:

As you can see, much of what will added in the manifest now appears in the skill’s page in the companion application. We must be ready to publish now, right?

Hold on. Although we’re a lot closer to publishing than before, there’s a little more work to do. If you take a closer look at the skill’s page, you might notice that to the left of the skill name is an empty speech balloon. That empty space is supposed to contain an icon to uniquely brand the skill. We won’t be able to publish the skill without supplying the icon.

Adding an icon to the skill is as easy as providing two URIs—one for a large icon image and one for a small icon image—in the smallIconUri and largeIconUri properties of each locale entry in the skill manifest. For example, for the “en-US” locale, those two properties might be defined like this:

Often, you’ll just use the same icon for all locales, duplicating those properties for each locale entry. But if you wish to define locale-specific icons, you can give different URIs for each locale.

The smallIconUri and largeIconUri properties are required for each locale before publication. But this presents an interesting question: If the “Hello World” template didn’t specify those properties and yet they are required, what other properties are required in the skill manifest prior to publication?

Validating the Skill Manifest

Fortunately, the ASK CLI can help us figure out what’s missing by performing validation on the manifest. Using the ask smapi submit-skill-validation, we can submit our skill for validation like this:

The --skill-id, and --locales parameters are required. In this case, we’re only submitting for validation of the “en-US” locale, but we can submit multiple locales by listing them with comma separation.

The result from ask smapi submit-skill-validation is a JSON response that includes the ID of the validation report and the status of the validation. Validation may take several minutes, so the status will likely always be “IN_PROGRESS” in the response.

As with ask smapi submit-skill-validation, the ask smapi get-skill-validations command requires the --skill-id parameter. It doesn’t require the --locales parameter, but does require the --validation-id parameter, which will be the ID given in response to ask smapi submit-skill-validation.

The response to ask smapi get-skill-validations will be a potentially lengthy JSON document that includes the validation status (in this case, “FAILED”) and a list of validation problems to be addressed. If the status in the response shows “IN_PROGRESS” wait a few moments and try ask smapi get-skill-validations again. When the validation is complete, the status will change to either “FAILED” or “SUCCESSFUL” and the list can be used as a checklist to help you complete the missing pieces of the skill manifest.

There are two kinds of entries in the validations list: locale-specific validations and privacy and compliance validations. Locale-specific validations will have a locale property to tell you which locale needs properties set or changed. Most privacy and compliance validations do not have a locale property unless it is a locale-specific privacy and compliance detail that needs to be addressed. Privacy and compliance validations are addressed by adding or editing sub-properties under a privacyAndCompliance property in the manifest (which we haven’t yet added).

You’ll also notice that the title of each validation includes instructions on how to address the problem by filling in fields via the development console. You’re welcome to address these problems in the development console if you wish. But for our purposes, we’ll edit the skill manifest directly by adding properties in skill.json.

The first failed validation is neither a locale validation problem nor a privacy and compliance validation problem. It is a recommendation that you enable the skill for instant updates. Since we’ve not even published the skill yet, there’s no way we can update it. It is not required that we address this at this time, so for now we’ll ignore this recommendation.

Next, let’s address the locale-specific validations. Two of them are asking us to provide smallIconUri and largeIconUri properties for the “en-US” locale, which we’ve already discussed before.

The other is asking us to specify a URL to a privacy policy page for the skill. This validation is actually a locale-specific privacy and compliance validation. To fix it, we’ll need to add the following privacyAndCompliance property in the skill manifest, as a peer to the publishingInformation property:

The locales sub-property specifies privacy and compliance information for each locale. Here we’re only specifying the location of a privacy policy with the privacyPolicyUrl property. But you may also specify a terms of use document for each locale by setting a termsOfUseUrl property, although that’s not required.

Now let’s look at the remaining privacy and compliance validations:

• “A selection is missing for the question ‘Does this skill contain advertising?’”—This indicates whether or not the skill advertises any products or services. You can fix this validation by adding a containsAds property under privacyAndCompliance and setting it to either true or false.

• “Confirmation for ‘Export compliance’ is missing.”—This indicates that the skill meets the requirements to be exported to any country or region. You can fix this validation by adding a isExportCompliant property under privacyAndCompliance and setting it to either true or false.

• “A selection is missing for the question ‘Does this skill allow users to make purchases or spend real money?’”—This indicates whether or not purchases are allowed through the skill. To fix this validation, add an allowsPurchases property under privacyAndCompliance and set its value to either true or false.

• “A selection is missing for the question ‘Does this Alexa skill collect users’ personal information?’”—This indicates whether or not the skill collects any personal information from the user. This validation can be fixed by setting a usesPersonalInfo property under privacyAndCompliance to either true or false.

• “A selection is missing for the question ‘Is this skill directed to or does it target children under the age of 13?’”—This indicated whether or not the skill’s audience includes children under the age of 13. This validation can be addressed by setting an isChildDirected property under privacyAndCompliance to either true or false.

In the case of Star Port 75 Travel, our skill does not have any advertising and does not target children. It is, however, export compliant, allows purchases, and collects user information. Therefore, the completed privacyAndCompliance section of the skill manifest should look like this:

Now we can redeploy our skill and run the validation check again. If you get any errors in deploying the skill, double-check that the icon URIs and the privacy policy URL point to an actual resource and don’t return an HTTP 404 or any other error response.

Once redeployed, we can run ask smapi submit-skill-validation and ask smapi get-skill-validations again. This time there are several successful validations, along with a few new failures. One of those failures requires attention:

The formatting of the failure’s description may be missing some whitespace that would make it easier to ready, but it seems that the example phrases “schedule a trip to Mars” and “plan a trip to Jupiter” don’t match any of the sample utterances in the interaction model. A quick look at the en-US.json file confirms that we never defined that utterance. So, let’s add a few sample utterances to the interaction model in en-US.json as well as for the other English interaction model JSON files:

Similarly, we’ll need to add the Spanish equivalents to the three Spanish interaction models:

Now, let’s deploy and run validation checks one more time. This time, the results are still lengthy, but all required validations are successful. Most importantly, the overall status is “SUCCESSFUL”:

At this point, we’ve written the code, we’ve run the tests, and we’ve performed pre-publication validation. We’ve done almost everything that can be done to prepare the skill for publication. With no further delay, let’s submit our skill for certification.