Creating Products

In-skill purchases enable users to add additional content and functionality to a skill while they are using the skill. For example, a skill that teaches a foreign language might provide some essential language lessons for free, but may offer upgrade packs for additional languages or advanced language usage for 99 cents each.

There are three kinds of ISPs that a skill may offer:

• Entitlements—One-time purchases that add a feature or content to the skill that will be available to the user from the time of purchase going forward

• Consumables—Purchases that enable a feature or content that will be taken away once used and must be purchased again

• Subscriptions—Purchases that enable a feature or content for a specified period of time, after which it must be renewed

All customers of Star Port 75 Travel are able to plan travel to any of the planets in our solar system. But we’re going to add a new “Magnificent Moons” option which will afford them the option of planning trips to a few of our solar system’s most notable moons, including Jupiter’s four largest moons (Io, Callisto, Ganymede, and Europa), Saturn’s moon (Titan), and of course Earth’s moon (Luna).

Defining a Product

Before we can offer the Magnificent Moons package to our users, we need to define it as a product. We could design this option around any of Alexa’s ISP types. We’ll choose to define it as an entitlement; the choice made here makes little difference in how the skill is implemented. As an entitlement, travelers may pay a one-time fee for the product and book as many trips to moons as they want.

To create a product, we must define the product in a JSON file and use the ASK CLI to associate it with our skill. The following JSON file describes the Magnificent Moons product:

There are several properties to be set in the ISP JSON definition:

• vendorId—Your vendor ID

• type—The product type. For our product, we set it to “ENTITLEMENT”, but it can also be “SUBSCRIPTION” or “CONSUMABLE”.

• name—The name of the product

• smallIconUri—A URI to a 108x108px PNG file that will be the small icon for the product

• largeIconUri—A URI to a 512x512px PNG file that will be the large icon for the product

• summary—A summary explaining why the user may want to buy this product

• description—A longer description of the product

• examplePhrases—A list of sample utterances that the user may speak to buy this product (for example, “buy Magnificent Moons package”)

• keywords—A list of keywords to be used for search indexing the product

• purchasePromptDescription—How Alexa will describe the project in the purchase prompt

• boughtCardDescription—The text to display in a card in the companion application when the product has already been purchased

• releaseDate—The date that the product will first be available, in “yyyy-MM-dd’T’HH:mm’Z” or “yyyy-MM-dd” format

• privacyPolicyUrl—A URL to a webpage describing the privacy policy for the product

• testingInstructions—Instructions for the certification team to know how to purchase this product when you publish the skill and product

• pricing—Pricing information for the product. Our product will cost $9.99 in U.S. dollars.

You’ll need to know your vendor ID in order to fill out the vendorId property. If you aren’t sure what your vendor ID is, the easiest way to find it is to inspect the contents of your ASK CLI configuration:

Some of the properties, such as testingInstructions and privacyPolicyUrl aren’t important until you’re ready to publish the skill (which we’ll talk about in the next chapter). For now, we’ll just put temporary values in those properties.

If this were a subscription product, the subscriptionInformation property would require additional information describing how often the subscription is renewed (either monthly or yearly) and how long a trial period should last in days. Had we created a subscription instead of an entitlement, the subscriptionInformation property might have looked something like this:

This defines a subscription that has a trial period of 10 days and renews monthly. Optionally, the subscriptionPaymentFrequency property could be set to “YEARLY” for an annual renewal period.

Adding Products to the Model

So that users can plan travel to the various moons, we must add the moon destinations to our interaction model. Way back in Chapter 3, ​Parameterizing Intents with Slots​ we created a custom PLANETS slot type in our skill’s interaction model. It included all of the planets in our solar system (including Pluto) as well as several synonyms for those destinations. Although the destinations in the “Magnificent Moons” package aren’t technically planets, we now need to add them to the PLANETS type so that they are candidates for a trip’s destination:

When the interaction model is deployed with these changes, users of our skill will be able to plan travel to any of the previously declared planets or these six moons. Later, we’ll prevent users from booking trips to the moons in the skill fulfillment code. But first, let’s deploy the product definition.

Deploying Products

Now that we’ve defined our product definition JSON file, we’re ready to use it to create the product. The ask smapi create-isp-for-vendor command will do that for us:

The ask smapi create-isp-for-vendor command requires that you specify the product definition JSON via the --create-in-skill-product-request parameter. This parameter can accept an entire JSON definition as a string, but it’s much easier to use the file: prefix to reference a file containing the product definition JSON.

The JSON returned in response from creating the product will contain the new product’s “productId”. You’ll need the product ID, as well as the skill ID in the next step, as you associate the product with your skill. To create the association, you’ll use the ask smapi associate-isp-with-skill command:

The product ID is specified with the --product-id parameter and the skill ID is given through the --skill-id parameter. Once this command completes, the product is linked to the skill. You can confirm this by using the ask smapi get-isp-list-for-skill-id command:

The response to the ask smapi get-isp-list-for-skill-id command includes a list of product definitions in the inSkillProductSummaryList property, showing you which products are associated with the skill. In this case, the inSkillProductSummaryList contains our “Magnificent Moons” product.

Now that the product is created and linked to our skill, we can start selling it to our users. Let’s add a new intent and intent handler for users to purchase the Magnificent Moons package.