Alexa is a voice control service developed by Amazon that pairs with devices such as the Echo, Echo Dot, and Tap. In addition to high quality text-to-speech and a wide variety of voice enabled integrations called “skills,” Amazon has also released the Alexa Skills Kit, enabling developers to quickly create their own skills. The skills kit includes a clear SDK, ample documentation and example tutorials like this one.
As an emerging platform with potential for digital advertising, Alexa was of particular interest to OpenX Labs, a small engineering team tasked with testing ad-tech innovations. Thanks to the comprehensive Alexa learning materials and tight integration with Amazon’s serverless AWS Lambda platform, Labs was able to develop a minimal skill—it answers some basic questions about programmatic advertising and OpenX—within a matter of weeks. We submitted our skill for approval, and were excited to release it and share it with our partners, and then… it was rejected by the Alexa team!
It turns out that Alexa skills have a strict verification process. Fortunately, the email we received from the Alexa team included all the requirements we didn’t meet and clear directions for how to fix them. In the end, we were able to successfully re-submit the skill after a couple of days. In the interest of helping first-time Alexa skill developers, this post shares a few of the points we missed.
1. Choose the Right Invocation Name
An invocation name is the word or phrase spoken by a user that will trigger your Alexa skill. There are two ways to invoke your skill:
Alexa, {start command} {invocation name}.For example, “Alexa, ask OpenX”.Alexa, {some action} {start command} {invocation name}.For example, “Alexa, order a car from Car Fu.”
Some examples from the OpenX Skill:
Choosing a right invocation name is important, because there are a lot of ways to go wrong. Be careful not to use a reserved word, like “start” in your invocation name. Additionally, one word invocation names are not allowed unless it’s unique to your brand or intellectual property. The full list of invocation name constraints is available here.
2. Make Your Cards User-friendly
Alexa-enabled devices like the Amazon Echo are always used with a companion smartphone app called Amazon Alexa. This allows the user to have greater degree of control over Alexa’s setup and behavior. When a custom skill responds to a user intent, an associated graphical “card” can be displayed in the app. It’s easy to forget to define your card, and accidentally present stubbed-out code snippets to the user instead! So remember to remove all code references from your card definition. It will look better to your user, and you won’t accidentally leak the internals of your skill. More on this in the submission checklist.
3. Ensure all Alexa Built-in Commands Still Work
An intent is a construct that maps to a specific response or process in your skill. For skills that declare many intents and sample utterances, Alexa might not be able to detect some built-in intents like “Cancel.” We found that this does not always happen, but it’s a good idea to check before submitting your skill. If a built-in intent does not work as expected, you can explicitly re-declare it in your sample utterances, for example, AMAZON.StopIntent cancel.
4. Include Example Phrases in Sample Utterances
In the configuration section of your Alexa skill, there’s a place for declaring Example Phrases that are used to describe the skill before a user installs it:
It is required that example phrases be listed in the Sample Utterances section, which looks like this:
Always including your example phrases in the sample utterances ensures your skill works as advertised. For example, if you have the example phrase “What is OpenX?” then your sample utterance should contain someIntent What is OpenX.
5. Use the Developer Forums if Necessary
The Alexa Skills Kit is still a relatively new developer platform. When submitting your skill, don’t be surprised if you discover a new situation that the Alexa team hasn’t seen before. We uncovered a corner case in which Alexa was forced to pronounce the name “OpenX” incorrectly, and were able to file a ticket for it on the Amazon Developer Forums.
Conclusion
These were some of the reasons our initial submission of the OpenX skill was rejected. Hopefully this information allows you to publish your skill more quickly! And as a final general principle, if the Alexa documentation mentions “You should…”, this usually means “You must….”
