|
1 | | -# Build An Alexa Skill with In-Skill Purchases |
| 1 | +# Build An Alexa Skill with In-Skill Purchases - Premium Fact |
2 | 2 | <img src="https://m.media-amazon.com/images/G/01/mobile-apps/dex/alexa/alexa-skills-kit/tutorials/fact/header._TTH_.png" /> |
3 | 3 |
|
4 | | -## Setup the ASK CLI |
5 | | -There are several aspects of developing an Alexa skill with in-skill purchases that require the use of the Alexa Skills Kit Command Line Interface (ASK CLI), so this entire walkthrough will require you to have installed and configured the ASK CLI. If you haven't done this before, here are the resources you need to get the ASK CLI installed on your machine: |
| 4 | +Adding premium content to your skill is a way for you to monetize your skill. This sample skill has taken the basic fact skill and has added new categories as premium content. This premium content is accessed through either a subscription or the one-time purchase of a given category. This guide walks through the setup of this skill, including the creation of the in-skill products. |
6 | 5 |
|
7 | | -> Note: If you would like to setup the ASK CLI using AWS Cloud9, step-by-step instructions can be found [here](https://github.com/alexa/alexa-cookbook/blob/master/guides/cli/cli-cloud9.md). |
| 6 | +Click [here](./instructions/setup-using-cli.md) if you would like to use the Alexa Skills Kit Command-Line Interface (ASK CLI). |
8 | 7 |
|
9 | | -* [Quick Start Guide for Installing the ASK CLI](https://developer.amazon.com/docs/smapi/quick-start-alexa-skills-kit-command-line-interface.html) |
10 | | -* [ASK CLI Command Reference](https://developer.amazon.com/docs/smapi/ask-cli-command-reference.html) |
| 8 | +To **Get Started** using the Alexa Developer Console, click the button below: |
11 | 9 |
|
12 | | -If you have used the ASK CLI previously, you will also need to **make sure** that you have the **most recent version** of the ASK CLI. You can make sure you have the latest version by running the command: |
| 10 | +[](./instructions/voice-user-interface.md) |
13 | 11 |
|
14 | | -```bash |
15 | | -$ npm update -g ask-cli |
16 | | -``` |
| 12 | +## Additional Resources |
17 | 13 |
|
18 | | -### Installation |
| 14 | +### Community |
| 15 | +* [Amazon Developer Forums](https://forums.developer.amazon.com/spaces/165/index.html) - Join the conversation! |
| 16 | +* [Hackster.io](https://www.hackster.io/amazon-alexa) - See what others are building with Alexa. |
19 | 17 |
|
20 | | -> _Note: if you have git installed, you can clone this repo and skip this section._ |
| 18 | +### Tutorials & Guides |
| 19 | +* [Voice Design Guide](https://developer.amazon.com/designing-for-voice/) - A great resource for learning conversational and voice user interface design. |
21 | 20 |
|
22 | | -> _Note: if you don't have git installed and want to skip this section, download the repo as a zip from [here](https://github.com/alexa/skill-sample-nodejs-fact-in-skill-purchases/archive/master.zip)._ |
23 | | -
|
24 | | -1. **Create** a new skill using the CLI. |
25 | | - |
26 | | - ```bash |
27 | | - $ ask new |
28 | | - ``` |
29 | | - |
30 | | -2. **Name** the skill "Premium_Facts_Sample". |
31 | | - |
32 | | - ```bash |
33 | | - ? Please type in your new skill name: |
34 | | - Premium_Facts_Sample |
35 | | - ``` |
36 | | - |
37 | | - |
38 | | -3. **Navigate** to your project folder. |
39 | | - |
40 | | - ```bash |
41 | | - $ cd Premium_Facts_Sample |
42 | | - ``` |
43 | | - |
44 | | -4. **Explore** the project structure. You should see folders for lambda and models, and skill.json file. |
45 | | - |
46 | | - ```bash |
47 | | - $ ls |
48 | | - lambda models skill.json |
49 | | - ``` |
50 | | - |
51 | | -5. **Open** the models folder. |
52 | | - |
53 | | - ```bash |
54 | | - $ cd models |
55 | | - ``` |
56 | | - |
57 | | -6. **Open** the interaction model file, en-US.json. |
58 | | - |
59 | | - ```bash |
60 | | - $ open en-US.json |
61 | | - ``` |
62 | | - |
63 | | -7. **Replace** the contents of *en-US.json* with the contents of [this JSON file](https://github.com/alexa/skill-sample-nodejs-fact-in-skill-purchases/blob/master/models/en-US.json), and save it. |
64 | | - |
65 | | -8. **Go back** to the project's root folder. |
66 | | - |
67 | | - ```bash |
68 | | - $ cd .. |
69 | | - ``` |
70 | | - |
71 | | -9. **Navigate** to the custom folder under the lambda folder. |
72 | | - |
73 | | - ```bash |
74 | | - $ cd lambda/custom |
75 | | - ``` |
76 | | - |
77 | | -10. **Open** the AWS Lambda function code file, index.js. |
78 | | - |
79 | | - ```bash |
80 | | - $ open index.js |
81 | | - ``` |
82 | | - |
83 | | -11. **Replace** the contents of *index.js* with the contents of [this JS file](https://github.com/alexa/skill-sample-nodejs-fact-in-skill-purchases/blob/master/lambda/custom/index.js), and save it. |
84 | | - |
85 | | -12. **Replace** the contents of *package.json* with the contents of [this JSON file](https://github.com/alexa/skill-sample-nodejs-fact-in-skill-purchases/blob/master/lambda/custom/package.json), and save it. |
86 | | - |
87 | | -13. While still in the lambda/custom folder, **update** the ASK SDK and the other npm dependencies by running `npm update`. |
88 | | - |
89 | | - ```bash |
90 | | - $ npm update |
91 | | - ``` |
92 | | -1. **Navigate** back to the root project directory. |
93 | | - |
94 | | - ```bash |
95 | | - $ cd ../.. |
96 | | - ``` |
97 | | - |
98 | | -### Creating In-Skill Products |
99 | | - |
100 | | -There are ASK CLI commands for creating your in-skill purchases. This guide will walk you through creating three different one-time purchases (entitlements), as well as a subscription. Our sample code is expecting these to be created as described, so make sure to follow along carefully. |
101 | | - |
102 | | -1. **Create** your first in-skill product. You should be in the project's root directory. |
103 | | -
|
104 | | - ```bash |
105 | | - $ ask add isp |
106 | | - ``` |
107 | | -
|
108 | | -3. **Choose** Entitlement. |
109 | | -
|
110 | | - ```bash |
111 | | - ? List of in-skill product types you can choose (Use arrow keys) |
112 | | - ❯ Entitlement |
113 | | - Subscription |
114 | | - ``` |
115 | | -
|
116 | | -4. **Choose** Entitlement_Template as your template. |
117 | | -
|
118 | | - ```bash |
119 | | - ? List of in-skill product templates you can choose (Use arrow keys) |
120 | | - ❯ Entitlement_Template |
121 | | - ``` |
122 | | -
|
123 | | -5. **Name** your in-skill product *science_pack*. |
124 | | -
|
125 | | - ```bash |
126 | | - ? Please type in your new in-skill product name: |
127 | | - (Entitlement_Template) science_pack |
128 | | - ``` |
129 | | -
|
130 | | -6. **Repeat** steps #2 - #5 to create two more entitlements: *history_pack* and *space_pack*. |
131 | | -
|
132 | | - ```bash |
133 | | - ? Please type in your new in-skill product name: |
134 | | - (Entitlement_Template) history_pack |
135 | | - ... |
136 | | - ? Please type in your new in-skill product name: |
137 | | - (Entitlement_Template) space_pack |
138 | | - ``` |
139 | | -
|
140 | | -7. **Create** a subscription product named *all_access* using a similar process. |
141 | | -
|
142 | | - ```bash |
143 | | - $ ask add isp |
144 | | -
|
145 | | - ? List of in-skill product types you can choose (Use arrow keys) |
146 | | - Entitlement |
147 | | - ❯ Subscription |
148 | | -
|
149 | | - ? List of in-skill product templates you can choose (Use arrow keys) |
150 | | - ❯ Subscription_Template |
151 | | -
|
152 | | - ? Please type in your new in-skill product name: |
153 | | - (Subscription_Template) all_access |
154 | | -
|
155 | | -8. **Navigate** to the new ISPs directory, and note the two folders, *entitlement* and *subscription*. This is where the JSON files for each of your in-skill products reside. |
156 | | -
|
157 | | - ```bash |
158 | | - $ cd isps |
159 | | - $ ls |
160 | | - ``` |
161 | | -
|
162 | | -9. **Navigate** to the *entitlement* folder. You should see three files in this directory, one for each of the entitlements you created in our previous steps. |
163 | | -
|
164 | | - ```bash |
165 | | - $ cd entitlement |
166 | | - $ ls |
167 | | - ``` |
168 | | -
|
169 | | -10. **Open** history_pack.json |
170 | | -
|
171 | | - This JSON file contains all of the necessary fields for your in-skill product, but you'll need to add the details to get them ready to sell. Because we used the Entitlement_Template template, we have provided a small explanation for each field, make sure you replace all of them. Take a look at [the sample in our docs](https://developer.amazon.com/docs/smapi/isp-schemas.html#entitlement-schema) for an additional reference. For this sample, at a minimum, you will need to update the name (not referenceName!), smallIconUri, largeIconUri, summary, description, purchasePromptDescription, boughtCardDescription, releaseDate and privacyPolicyUrl. Alternatively you can copy and paste the contents of the files found here: [ISP Entitlements](https://github.com/alexa/skill-sample-nodejs-fact-in-skill-purchases/tree/master/isps.samples/entitlement). |
172 | | - |
173 | | - After updating *history.pack.json*, Fill out the details for the *science_pack.json* and *space_pack.json* files. You will need to update with content about your science and space products including icons for each. |
174 | | - |
175 | | - > **IMPORTANT: Don't change the *referenceName* in your files, as our codebase is relying on those to be consistent.** |
176 | | -
|
177 | | - Once you are happy with your pricing, descriptions, and the other metadata for your three entitlements, you should update the same fields plus the subscriptionPaymentFrequency for your subscription. Alternatively you can copy and paste the contents of [All Access ISP subscription sample](https://raw.githubusercontent.com/alexa/skill-sample-nodejs-fact-in-skill-purchases/master/isps.samples/subscription/all_access.json) into your *all_access.json* file. |
178 | | -
|
179 | | -11. **Review and edit** the subscription file. |
180 | | -
|
181 | | - ```bash |
182 | | - $ cd ../subscription |
183 | | - $ open all_access.json |
184 | | - ``` |
185 | | -
|
186 | | - Now that you have customized your in-skill products, you can deploy your skill using the ASK CLI, and start testing it. |
187 | | -
|
188 | | - > _Note: be sure to review the output to confirm there were no errors._ |
189 | | -
|
190 | | -### Deployment |
191 | | -
|
192 | | -1. **Navigate** to the project's root directory. You should see a file named 'skill.json' there. |
193 | | - |
194 | | - ```bash |
195 | | - $ cd ../.. |
196 | | - ``` |
197 | | - |
198 | | -2. **Deploy** the skill and the Lambda function in one step by running the following command: |
199 | | - |
200 | | - ```bash |
201 | | - $ ask deploy |
202 | | - ``` |
203 | | - Assuming that you followed all of the setup instructions for the ASK CLI, your entire skill and Lambda function should be created on their respective portals. |
204 | | - |
205 | | - |
206 | | -### Testing |
207 | | - |
208 | | -1. To test, login to [Alexa Developer Console](https://developer.amazon.com/alexa/console/ask), click on the **Premium Facts Sample** entry in your skill list, and click on the "Test" tab. The "Test" switch on your skill should have been automatically enabled. If it was not, enable it now. |
209 | | - |
210 | | -2. Your skill can now be tested on devices associated with your developer account, as well as the Test tab in the Developer Portal. To start using your skill, just type or say: |
211 | | - |
212 | | - ```text |
213 | | - Alexa, open premium facts sample |
214 | | - ``` |
215 | | - |
216 | | -**Note: The developer account associated with the skill is never charged for in-skill products.** For more details about testing skills with in-skill products, please refer to the [In-Skill Purchase Testing Guide](https://developer.amazon.com/docs/in-skill-purchase/isp-test-guide.html) |
217 | | - |
218 | | - |
219 | | - |
220 | | -## License Summary |
221 | | - |
222 | | -This sample code is made available under a modified MIT license. See the LICENSE file. |
| 21 | +### Documentation |
| 22 | +* [Official Alexa Skills Kit Node.js SDK](https://www.npmjs.com/package/ask-sdk) - The Official Node.js SDK Documentation |
| 23 | +* [Official Alexa Skills Kit Documentation](https://developer.amazon.com/docs/ask-overviews/build-skills-with-the-alexa-skills-kit.html) - Official Alexa Skills Kit Documentation |
0 commit comments