Use Alexa In-Skill-Purchasing (ISP) with Jovo

Learn how to make money with your Alexa Skills by selling digital goods with Alexa's In-Skill Purchasing (ISP) feature and the Jovo Framework. In this tutorial, we will build a simple Alexa Skill that allows users to buy and refund items.

You can find the full code example of this tutorial here: jovo-templates/alexa/isp.

• Introduction to Alexa In-Skill Purchasing
• Adding Products for Alexa ISP
  • Using the Alexa Developer Console
  • Using ASK CLI
• Implementing Alexa ISP with Jovo
  • Updating your Language Model
  • Adding ISP to the Logic
    • Upsell
    • Purchase Request
    • Refund
    • ON_PURCHASE
  • Inventory Management for Consumables

Watch the video here:

Introduction to Alexa In-Skill Purchasing

Jovo Docs: In-Skill Purchases.

In May 2018, Amazon introduced the ability for Alexa Skill developers to make money through in-skill purchasing. It allows you to sell premium content either through one-time purchases, consumables, or subscriptions.

The Alexa ISP API works independently from your own skill. You do not handle the transactions yourself, but you send a directive just like with the Dialog Interface. Alexa will use predefined values from products that you either define in the Alexa Developer Console, or with the ASK CLI, to fulfill the transaction. The moment you send out one of these directives, the current session ends. Once the transaction is finished, your Skill will get a request with data about the transaction at which point you can resume where the user left off.  

There are two main steps that need to be done to add In-Skill Purchases to your Alexa Skill:

• Adding Products for Alexa ISP
• Implementing Alexa ISP with Jovo

Adding Products for Alexa ISP

Before we can implement the interactions in our code base, we have to first create the items we want to sell.

There are two different ways how products can be added to an Alexa Skill:

• Using the Alexa Developer Console
• Using ASK CLI

Using the Alexa Developer Console

Recently, Amazon introduced the ability to add products with a graphical user interface directly in the Amazon Developer Console.

To do this, go to the "In-Skill products" tab:

Create a new product and call it frozen_sword. For this product, we select the "One-Time Purchase" option:

Add all the necessary information:

In the next step, we have to select pricing and use a tax category. For the purposes of this tutorial, it doesn't really matter, so we stay at 99 cents and will choose the "Software" category:

The final step is to add testing instructions. If you then save the product, you need to confirm to link it to your Alexa Skill:

That's it! Your product is now linked to your Alexa Skill:

You can now move on to Implementing Alexa ISP with Jovo, or take a look at how you can also add products by using the ASK CLI.

Using ASK CLI

To add items without using a graphical interface, we will use the ASK CLI (version 1.4.3 or later). If you did not install or initialize the ASK CLI yet, check out this quickstart guide by Amazon.

To run the ASK CLI's commands we have to move from the project's root folder to the alexaSkill folder:

We're going to add an entitlement, which is a one-time purchase item, and call it frozen_sword using the ask add isp command:

After that, there should be a frozen_sword.json file in your alexaSkill/isps folder. The content of that json file is used to define the price, release date, description as well as the prompts Alexa will use when she handles the transaction and much much more. You can find examples and a small description for each field in the official Amazon reference.

Here's how our product's file looks like:

Additionally, we could add a subscription by running the ask add isp command again and adding the premium_pass:

Here's the template for the subscription:

Since the file structure for a consumable is the same as for a entitlement, we will skip adding that.

Save the files and deploy everything with the ASK CLI:

Implementing Alexa ISP with Jovo

Now that we've added at least one product to our Alexa Skill, we can start implementing it into our app. The Alexa In-Skill Purchases API offers three kinds of interactions with our user:

• Upsell: We proactively offer the user our products ("The Product X could help you with that..").
• Purchase request: The user asks to buy something ("I want to buy X").
• Refund: The user wants to return a product ("I want a refund for X").

For the Alexa Skill to understand those requests mentioned above, you need to do two things:

• Update your Language Model
• Add ISP to the Logic

Updating your Language Model

Docs: Jovo Language Model.

As I described earlier, there are three kinds of interactions we have to implement in our Skill, but only two of these need to be added to the language model because the buy and refund request are the only ones initiated by the user.

All of the elements that we're going to add now should be placed inside in the alexa object of our Jovo Language Model (models/en-US.json) to keep everything as clean as possible.

First of all, we will add a custom slot type for our product names. The important thing here is that the id of each value is the reference_name of our product, because we need it later on to initiate the transaction.

Next up the intents. Amazon provides sample intents for both buy and refund requests:

That's everything we need for our Language Model. To upload it to the Alexa platform, use the following commands:

Adding ISP to the Logic

As we discussed earlier, our only task is to start the transaction, since Alexa will handle the transaction autonomously. After the transaction finished, we will receive a request notifying us about the outcome, i.e. the purchase was successful or not. Inside that request, there will also be a token, which we can define while starting the transaction, to help us resume the Skill at the place the user left off.

To access the Alexa ISP API in Jovo we use the Alexa In-Skill Purchase object of the Jovo framework:

Before we start any kind of transaction or refund process, we always retrieve the product first:

The data we get looks like this:

Using that data we can check if the user already owns the product:

Upsell

The upsell method is used to proactively offer the user our products. To send out the request, we need three things:

• the reference name of the product
• a message/prompt
• a token

For simplicity reasons and because these things are different for every individual skill, we will just hard-code the reference name and use a placeholder token.

For your own skill, you should try to build a system which offers each product at the right time, e.g. offer the user extra lives after they have died, so you don't annoy your user.

For the message/prompt, Amazon offers the following guidelines:

• Don't include the price. The price, subscription term, or free trial length are obtained from the product's json file during the transaction.
• End the message with a question to determine if the user is interested, but don't specifically ask if they want to buy it. That will be handled in the transaction by Alexa.
• Explain the benefit the user would have from that product at the current situation.

In general, you should also avoid suggesting multiple products in a row or suggestion products too often, so you don't interrupt and annoy the user.

Alright, now that we discussed all that, we can start the transaction using the upsell() method, which takes the productId, prompt and token as parameters, after we've checked if the user already owns the product:

Purchase Request

Now we can get to the first user requested intent, BuySkillItemIntent.

There are two scenarios at which the intent gets invoked. In the first one, the user does not specify which item they want to buy, i.e. there is no value for our input variable, where we just suggest them some.

In the other scenario the user specifies the product and we use the input's id as our product's reference_name to check whether they already own it. If that's not the case, we start the transaction:

Refund

Next, the RefundSkillItemIntent. Same procedure, get the input's id, use it to get the product, check if the user even owns the product and start the refund process:

ON_PURCHASE

As we discussed earlier, the initial session ends after we start a transaction (upsell, buy or cancel). After it's finished your Skill will get another request, which will looks like this for example:

The important parts of that request are:

The incoming request will be mapped to the Jovo built-in ON_PURCHASE intent, where you can resume the Skill at the point before the transaction. The token you can send is supposed to help you with that.

Inventory Management for Consumables

With consumables, you have to maintain one more thing, the user's inventory. While Alexa keeps track of the number of purchases per item, activeEntitlementCount, which gets incremented with every purchase and decremented with every refund, you have to track how many times the user has used the consumable. Simply storing the data inside a database would be enough in this case.

Because you are offering consumables, the userId of your user stays the same even if they disable and re-enable the skill later on, so keep that in mind if you clean up the user data after they've disabled your skill using the Alexa Skill Events.

The incoming AlexaSkillEvent.SkillDisabled request will have the userInformationPersistenceStatus property that has either the value PERSISTED or NOT_PERSISTED, which you can use to decide, whether you can clean up the data or not.

That's the basic implementation of Alexa in-skill-purchasing (ISP) with Jovo.

Any questions? You can reach us on Twitter or Slack.