Uh oh! We couldn’t find any match.

Please try other search keywords.

Bixby Developer Center

Guides

Planning A Capsule

Now that you've had a chance to start learning about how to create capsules in the quick start guide, you can begin planning your own capsule! This topic is meant to be a set of recommendations that you should think about and plan ahead of time before creating your capsules.

Specifically, it teaches you how to do sufficient research for your capsule, write out specifications, and then plan the engineering work involved.

Note

It is not required to read this topic for you to start working on your capsule, but we recommend going through these phases. It will greatly help you figure out which models, actions, and general information you need while developing your capsule.

Research Phase

While you're creating your own capsule, narrow down what you want the user to be able to accomplish through Bixby while using their device and the cloud platform. Essentially, you're asking "What ability do I want to teach Bixby?"

In order to answer this question, consider the following:

  • Understand your target users. Figure out the prioritization of user goals and consequently, what Bixby will do for your users. For example, if you're building a weather capsule and the user asks "What's the weather like today?", they probably want to know the current temperature and then the weather conditions (for example, if it's raining), in that order.
  • Understand your market, and specifically the domain within it. For example, if you're building a capsule to check stock market prices, it is useful to have expertise in finance and various stock markets. If you're building this capsule for users located in the US, you might want to be familiar with the Dow Jones Industrial Average and the S&P 500.
  • Decide which locales you want to support. This is going to affect how you organize your resources during development. The specific list of supported languages are determined when you prepare your targets.

Specification Phase

After you've researched enough information for your capsule, you can start your specification phase:

  1. Start writing user stories.
  2. Then, create a more complete list of use cases.
  3. Begin listing inputs and outputs that your capsule will need.
  4. At the very least, consider creating a must work utterances table to establish a base minimum for how your capsule should work.
Writing User Scenarios

Writing typical user scenarios enables you to really narrow down the scope of what your capsule will be used for by users. User scenarios also help you understand what to expect from Bixby. Specifically, these user scenarios will be useful later, when you start adding stories and training examples.

Here are some recommendations for writing a good scenario:

  • Do limit each scenario to a single paragraph that focuses on a single usage case
  • Do make it memorable by adding names, jobs, activities, and places
  • Do ensure that it's realistic, believable, and representative of a typical user experience
  • Do make sure your scenarios have a diversity of people, usages, and context
  • Do write at least 2 user scenarios per capsule, which will help keep your capsule focused

The following examples are well written user scenarios.

Example Scenario 1: Flight Status Capsule

Friend on flight

Jane is picking up her roommate Delilah who is arriving to San Francisco on a flight from Sydney, Australia. She wants to know if the flight is on time and what terminal (and gate) it arrives at. Before driving to the airport, she checks her phone assistant for details on "the BA flight from Sydney to SFO this afternoon" and realizes it left 45 minutes late. Instead of waiting in the parking lot, she uses the extra time to pick up coffee from Blue Bottle in SF (Delilah's favorite) to help cheer up her friend on arrival after a long and delayed journey. BFF #win.

Example Scenario 2: Recipe Capsule

Specific Ingredients

Raj arrives home after a long day of work, and is immediately greeted at the door by his children. His stomach growls, and he checks the fridge. He notices an assortment of products and leftovers, as well as a large chicken. He pulls out his phone and with one hand asks: "What recipes can I make with chicken, tomato, and mozzarella cheese?" and selects the second option (which looks delicious). Following the steps, he is able to prepare a chicken dinner for his family using the steps in the recipe, and makes a great meal.

Example Scenario 3: Weather Capsule

Individual Local

Hayato lives in Yokohama and likes to dress comfortably. He wakes up in the morning and checks notifications on his phone, and then he asks his assistant a few questions about the weather. He asks what the temperature will be today for his current location. Then, he asks what the chances are of rain at 6:00 pm when he gets off work and walks to the train station. Good news today, it will be warm and sunny and only a 1% chance of rain - so he decides to wear his favorite cotton t-shirt and khakis with open-toe sandals. 今日 もいい天気 だ!("Kyou mo ii tenki da!" - or, "Fine day today!")

Listing Use Cases

While user scenarios give you specific details on how a user will interact with your capsule, listing use cases helps you define scope for your capsule. It also gives you some idea of which actions you will need to implement.

Here are some best practices for writing a use cases list:

  • Do cover every distinct way of using the capsule.
  • Do include an example utterance.
  • Do rank and prioritize the list (e.g., P1, P2, P3).
  • Do capture all feature ideas. It's okay to mark some as "postponed".
  • Do capture every unique feature and ensure diversity in the examples.
  • Don't try to capture every single possible variation! For example, if you have "What is the current price of TGT?", then you don't also need "What is the current price of AAPL?" and "What is the current price of ORCL?"

In general, a simple capsule should have about five use cases, while a more advanced capsule should have about fifteen.

Example Use Case Table - Simple Stocks Capsule
#ScenarioUtterance Example
1Check price for stock"What is the current price of TGT?"
2Check exchange for stock"What stock market exchange is Google listed on?"
3Check market cap for stock"What is the market cap for MSFT?"
4Buy shares"Open Fidelity and buy 50 shares of SNAP stock with $10 limit"
5Sell shares"Sell all shares of DIS using a Market Order day trade"
......

Inputs and Outputs

Once you have your scenarios listed, it's important to understand what Bixby will need (inputs) in order to produce the desired results (outputs). Creating an input table and an output table helps keep track of the various concept models your capsule needs.

Example Input and Output Table - Simple Stocks Capsule
Note

The cardinality listed below in each of the tables refers to the number of inputs or outputs that are expected for each utterance. You can read more about cardinality in the Modeling Concepts topic in the developer's guide.

Input NameExample
Company NameTarget Corporation
Stock SymbolTGT
Price$125.50
ExchangeNYSE
Amount100 shares
Output NameExample
Confirmation numberFID-123456789
Total purchase amount$10,005.00
Order fee$5.00
Price$100.00
Amount10 shares

Must Work Utterances

A must-work utterances (MWU) table helps you keep track of use cases to support through utterance examples with input mapping. Use a simple table with structures and leverage your existing inputs table. These MWU tables are normally created by a product manager, but can be used by your developers, designers, and quality assurance engineers. You might also want to keep track of capsule versions, with future work being put on separate tables. Make sure you also test variations, while limiting duplicate testing.

Example MWU Table - Simple Stocks Capsule
UtteranceExchangeStock SymbolPrice...
"What is the price of WMT?"WMT
"What is the cheapest stock on the NYSE?"NYSE
"Show me stocks that cost less than $5"$5
... and more 

Engineering Planning Phase

This section discusses the mechanics of creating your capsule, preferably after you've finished researching information and creating specifications. First, you'll need to plan API integration. Then you can further familiarize yourself with Bixby's platform, using the developer guides.

Planning API Integration

Since you are likely going to be using an existing API to implement actions, you should remember that Bixby is a conversational user interface (CUI):

  • Don't just recreate an app in a capsule.
  • Don't design your capsule strictly based on your existing API.
Note

If the API is not your own, there might be additional business development work you need to do. You should meet, discuss, and acquire rights with the owners and come to a proper contract agreement in the API's use. Make sure to discuss the Service Level Agreement (SLA), including responses from the provider in case of downtime and pricing. You will also need to make plans for handling bugs and if there are any new feature requests.

Capsule Developer Workflow

To help with your engineering planning, here are the typical tasks that the capsule developer will need to work on, in the order that they should typically be done. These are in the same order as shown in the quick start guide.

Note

We highly recommend that you follow the order listed below when developing your capsule!

  1. Create initial models.
  2. Implement the actions using JavaScript for major API calls.
  3. Create initial layouts for lists, summaries, and properties.
  4. Create initial natural language (NL) training (utterances).
  5. Write initial dialogs.
  6. Define Instantiation Strategies and default-values.
  7. Define Selection Strategies and Preference Learning, as desired.
  8. Set up Vocabulary using files and/or feeds.
  9. Create input validations, preconditions, and error handling code.
  10. Create user stories for testing.

You should continue to iterate and refine your user experience and user interface as needed, once the core functionality of your capsule has been implemented and tested.