NOTICE: For Voiceflow's biggest UI updates, I will revise all this tutorial. So stay tuned!
This is the One-time purchases part2 of basic tutorial for In-Skill Purchasing on Voiceflow series.
The Part 1 is here:
In previous part, we created a simple Hello World skill as a basic feature of skill. Today, we add some ISP specific feature such as adding a in-skill product, create flows to buy, and also premium features for purchased users.
How many flows should we should create for ISP?
Before we start, let's make a list of all flows we should create for ISP. Here's Amazon's official document for user-experience tests.
In the document above, seems we should create the following flows (especially for certification):
Buy Flow
If users have already knows about the in-skill product and want to buy it, users will say "I wanna buy Greetings Pack" directly. Alexa will receive this as an intent and describe about the product, price, etc.
Also, if users have already purchased, Alexa will say "you've already purchased." That means users cannot buy double.
Premium Feature Flow
Alexa will check if users have purchased or not. If users have purchased Greetings Pack, they can access to premium content. If not, they can access only basic feature.
Other Flows
We also should create the following flows. This time, we will do Buy Flow and Premium Feature Flow. The others will be
Cancel Flow
If users have already purchased and want to cancel or refund it, users will say "I wanna cancel refund Greetings Pack". Alexa will receive this as an intent and cancel it.
Also, if users have not purchased, Alexa will say "you've not purchased yet."
Upsell Flow
If users have not purchased the in-skill product, Alexa will offer users to purchase it and explain the benefits users can get by buying it, but it should be in a natural context. This context is so important. You should not put too much pressure on users to buy it unless users show some interests in in-skill product such as using the skill too often, asking about the product, or trying to access premium content directly.
"What Can I buy" Flow
This is good especially if there are more than 2 in-skill products available.
Users does not know what products they can buy, so Alexa will describe those products available. Also, if users have alrealy bought one of those products, Alexa should described the others only.
Product Descrption Flow
This is a kind of similar to "What Can I buy" flow, but this wil be for only one single product. Users know the name of product but they don't know its benefits. So, Alexa should describe those benefits. Also, this will be a good trigger for "Upsell".
"What I bought" Flow
Users might not know what they have already bought because they can not "see" it and it's better for users to process all via voice. (actually, they can check these via Alexa app, but it will take another step.) So, Alexa should check if users have bought any products and will describe it.
Flow block
So, now we know we should create lots of flows for ISP. That means it will be like this.
This is my sample which I implmented whole flows. Not bad. But messy, complex and confusing, isn't is?
Now we will learn about how to Flow block.
What are flows?
A flow is a set of blocks in Voiceflow organized within a single canvas. When you are working on Voiceflow, everything you can see on the canvas is all stored within a single flow.
Flows are like boxes that contain your building blocks. Flows can contain other flows, allowing you to stack them and organize thousands of Voiceflow blocks into easy, manageable sections that you can duplicate and reuse.
Flow block | Voiceflow Tutorials
Sounds nice! So we will create each Flow block for whole flows required for ISP.
Notes: Variables and Flow Blocks
In this tutorial, we use only a few variables across the main flow and flow blocks, so you don't need to care so much. However, if you use variables with Flow Block, you might need to know the differences about "scope" and "persistency" between project/flow variables. Here's the link of my cheet sheet.
Create Buy Flow and in-skill product
It's time to hands-on! First, we will create Buy flow.
Click on the Choice block which we created basic_hello_intent, and click on "Add Path" to add an intent.
Create an intent for buy Greetings Pack named "buy_greetings_pack_intent" and add some utterances.
Put a Flow blocks and connect with choice "2" of the Choice block.
Click on the Flow block again. Then we will see Flow block's menu appears. Type "Buy Greetings Pack Flow" and click on "Create".
A new flow has been created and we will see a whole new canvas. This is a new canvas for the Flow block and means now we are the inside of "Buy Greetings Pack Flow".
In the "Buy Greetings Pack Flow", we will create an in-skill product first. Put a Aayment Block anywhere on canvas. You don't need to connect it with any blocks at this time. Payment Block's menu will appears, then click on "Create Product".
The Product screen is divided in to some sections. The first one is "Name & Description" to describe the detail about the product we will create. Enter the following details for Greetings Pack and click on Next.
| Field | Description | Value |
|---|---|---|
| Product Name | The name of the product. Users will see and hear this. | Greetings Pack |
| Short Description | Summary description of the product. Users will hear this. | The Greetings Pack says hello in a variety of voices and languages. |
| Detailed Description | A full description explaining the product's functionality and any prerequisites to using it. Users will see this. | The Greetings Pack unlocks the variety of voices and languages, and greets you in Hindi, Spanish, Italian, and more. |
Next, "Pricing Model" section. This time, we will go with One-time purchase type. So it will be like this:
| Field | Description | Value |
|---|---|---|
| Product Type | You can choose a type of in-skill products: One-Time Purchase, Consumerable, or Subscription. About product types in detail, see here. | One-time Purchase |
| Tax Category | You can choose the tax category for the product. Select the category that matches the nature of your product. See here in detail. | Infomation Service |
Next, "Availability" section. In this section, you can choose which Alexa stores and countries your product is available and its price. This time, we will go only for amazon.com(US) only.
| Field | Description | Value |
|---|---|---|
| Marketplace Availability | You can choose which Alexa stores you sell your in-skill products. This will enhance which country and currency you can choose in Distribution Countries & regions. Also, this should be related with your skill's locale setting. | amazon.com(USD) |
| Pricing | The price of your in-skill product. This has minimum and maximum prices depending on each marketplace. | 2.99$ |
| Distribution Countries & Regions | You can choose countries you sell your in-skill products. | US |
Next, "Phrases" section. In this section, you can set some phrases to trigger to buy the in-skill product. This should be same as sample utterances in "buy_greetings_pack_intent" and should works as that intent.
| Field | Value |
|---|---|
| Phrases | get greetings pack |
| get greeting pack | |
| buy greetings pack |
Next, "Product Icons". This will appears in skill card on Alexa app. Upload images for each. If you need help creating icons, you can use Alexa Skill Icon Builder. Then click on "Next".
Finally, "Details" section. Enter the following and click "Create Product".
| Field | Description | Value |
|---|---|---|
| Keywords | Keywords that will be used with search. Comma separated. | greetings, hello, languages |
| In-App Card Description | A description of the product that displays on the skill card in the Alexa app. Users will see this after purchased. | You now have the Greetings Pack, which will greet you in multiple languages in a variety of voices. |
| Privacy Policy URL | A URL to the privacy policy. In this tutorial, we will use a placeholder value, but in the real certification, you should create your own privacy policy page which can be accessed via the Internet. | http://www.example.com/privacy.html |
| Testing Information | You should provide testing instructions to help the certification team find and test your in-skill product. In this tutorial, we omit this. | (fill the testing instructions) |
Now, we've created the first in-skill product! Yeah!! Now we go back to canvas by clicking on "Return to Canvas".
We come back to canvas of the main flow. But we have not finished creating "Buy Greetings Pack Flow" yet. So, click on the Flow block again and go back there.
We really want to connect Payment block now, but wait a moment. We need check 2 things before it:
- If users can buy any products by voice?
- If users have already purchased Greetings Pack?
For the first one, when we buy some in-skill products via Alexa, "Voice Shopping" and "1-click ordering" settings must be enabled on our Alexa app. If these are disabled, purchasing the in-skill products in your skill always fail.
So we should check if this is enabled or not using User Info block, first.
Put an User Info block next to Home block and connect to it.
Click on the User Info block and choose "ISP" for User Info Type.
This means if users have enabled "Voice Shopping" and "1-click ordering", it will go to the success path (not "fail" one), not enabled, will go to the fail path. So put a Speak block and connect it to the fail path of User Info block, then make Alexa urge users to enalble those before purchasing.
If users have already enabled "Voice Shopping" and "1-click ordering", they are ready to purchase but we need to check one more thing: If users have already purchased Greetings Pack. So put another User Info block and connect with previous User Info block.
This time, choose "Product" for User Info Type. This will check if user has alrealy purchased a in-skill product. Then "Check if Product Purchased" will appear and we can choose specific in-skill product we want to check. Choose "Greetings Pack".
If users have alrealy purchased "Greetings Pack", it will go to the success path. If users have alrealy purchased, they don't need to buy again. So put a Speak block and tell them they have already purchased.
If users have not purchased yet, it will go to the fail path. This the main part of this flow. Now we connect Payment Block we created before to the fail path of the second User Info Block. Then Payment Block settings will appears, click on Greeting Pack.
Click on Upsell Message. When users is going to buy one-time purchase, Alexa will speak this message first, then describe its price and confirmation automatically. Enter as follows.
Like User Info Block, Payment Block has 2 paths, too: success and fail. Inside Payment Block, Alexa will handle users' whole purchasing process and there are 3 results.
- Purchasing process succeeded.
- Users declined to purchase.
- Something wrong such as errors happened.
1 will go to the success path and others will go to the fail path. First, put Speak Block for the success path and tell users that they can now use Greetings Pack.
For the fail path, there are 2 possibilities: Users declined or some errors happened. In Voiceflow, we cannot distinguish this difference, so we put a Speak Block and enter a vague response here.
We've done for Buy Greeting Pack Flow! This is the whole flow of Buy Greetings Pack Flow.
Click on Home icon upper left on canvas and go back to the main flow.
Notes: How to get out from Flow Block
In the main flow, if blocks don't have the next block, skill will ends. In the flow block, this works different. If blocks don't have the next block in the flow block, its flow will ends and go back to the root or original flow, which called its flow block.
On the other hand, if you want to end your skill in the flow block, you have to put Exit Block.
Now we're back to the main flow. After buying the Greetings Pac, users want to try it A.S.A.P. Even if they have not bought, we should continue conversation. So connect the Flow Block back to the Speak Block, which Alexa says "How can I help you?".
Add Premium Feature
Next, we will add the Premium Feature for users who purchased the Greeting Pack. Let's remeber the main feature flow. I just added some comments for you.
For unpaid users, Alexa will say the variety of hello but only in English. For premium users, Alexa will say these in the variety of languages and voices, too. So, put a Speak Block first and set some speech texts.
In Voiceflow, you can change a voice in Speak Block like this. Here's a sample for using Spanish voice. (NOTICE: You don't need to do this right now. We'll know why later.)
But it's not enough. Each voice has each language he/she can speak. Without setting an appropriate language for voice, Alexa will not speak collectly or will not speak anything. We have to set languages, too. We can set this by using SSML lang tag. For example:
<lang xml:lang="es-ES">Hola</lang>
With the combination of SSML lang tag and setting voice "Conchita" or "Enrique", both are Spanish voices, Alexa will speak "Hola" fluently in Spanish.
However, Voiceflow does not support setting language by SSML lang tag currently, so we need a workaround here. Put a Code Block before Speak Block.
Copy and paste the codes below into the Code Block.
var premium_greetings = [ '<voice name="Aditi"><lang xml:lang="en-IN">Namaste.</lang></voice>', '<voice name="Raveena"><lang xml:lang="en-IN">Namaste.</lang></voice>', '<voice name="Conchita"><lang xml:lang="es-ES">Hola.</lang></voice>', '<voice name="Enrique"><lang xml:lang="es-ES">Hola.</lang></voice>', '<voice name="Hans"><lang xml:lang="de-DE">Hallo.</lang></voice>', '<voice name="Marlene"><lang xml:lang="de-DE">Hallo.</lang></voice>', '<voice name="Vicki"><lang xml:lang="de-DE">Hallo.</lang></voice>', '<voice name="Celine"><lang xml:lang="fr-FR">Bonjour.</lang></voice>', '<voice name="Lea"><lang xml:lang="fr-FR">Bonjour.</lang></voice>', '<voice name="Mathieu"><lang xml:lang="fr-FR">Bonjour.</lang></voice>', '<voice name="Mizuki"><lang xml:lang="ja-JP">Konnichiwa.</lang></voice>', '<voice name="Takumi"><lang xml:lang="ja-JP">Konnichiwa.</lang></voice>', '<voice name="Carla"><lang xml:lang="it-IT">Ciao.</lang></voice>', '<voice name="Giorgio"><lang xml:lang="it-IT">Ciao.</lang></voice>' ]; var premium_speech = premium_greetings[Math.floor(Math.random() * premium_greetings.length)];
These codes randomly choose one of various international greetings with a language and a voice, and put it into the variable "premium_speech". We can use this variable "premium_speech" in the next Speak Block. (Now we can create and set a variable in Speak Block. This is very nice, isn't it?)
Then connect the Code Block with the Speak Block.
We've done our premium contents for paid users!
Next we will divide the main feature flow into 2 flows depending on whether users are paid or not paid. Insert an User Info Block between Choice Block and Speak Block which is for unpaid, and connect it with Choice Block.
Remember User Info Block and how to check If users has already purchased or not? Should be like this.
Then, connect with speak blocks depending on purchased or not.
For premium users, Alexa should ask them if they want another greet again, too. So connect 2 Speak Blocks with a line.
Also, reconnect the Choice Block, which checks "yes" or "no", back to the User Info Block. Then, Alexa alway check if users has purchased or not before she speaks Hello.
Finished! This is the whole flow today.
Before testing, Dont' forget to "Upload to Alexa"!!!
Test
Now, it's fun time to test! Before starting, we should know how to reset purchase state.
How to reset test purchase
For testing a skill with in-skill purchasing, we will buy and cancel many times as tests. It will not cost us for purchasing in-skill product, but Alexa remembers our test purchases. Also, we have not created the flow to cancel or refund. So we need to reset those by ourselves and actually we can reset those on Alexa Developer Console.
Open Alexa Developer Console and click on our skill, in this tutorial, it should be "Premium Hello World".
Scroll down on Build page, click on "IN-SKILL PRODUCT".
You will see "Reset test purchases" under the in-skill product name. Click on it.
Confirmation diaglog will show up. Click on "Reset".
Success message will show up on the top. Now our test purchase state has been reset and we can purchase our in-skill product again.
Let's Test
First, we just make sure if basic feature works because we have changed a little.
It's ok. Then, test buying, but decline once.
If testing on ADC with speakers, we heard one strange thing. After declined to purchase, when Alexa spoke "...anyway.How can I help?", she pronounced "...anyway dot How can I help?", didn't she? I think this is a bug on Voiceflow. This might be fixed in future, but currently we will add a workaround.
Click on the Speak Block which Alexa says "How can I help?". Move cursor before "How" and click. Then click on ADD EFFECT, Break, and Sentence.
A sentence break has inserted before "How". We will make sure if this fix works on the next test.
Next, we will purchase it.
Works perfect! Also, we should check if paid users cannot buy double.
Everything works Great!!!
That's all for today. Next time, we will add:
- add intents for cancel
- add flows for upsell
Will continue to Part3. See you soon!
