Bixby Developer Center


Capsule Developer Workflow

So you finished going through the quick start guide, you've read through the Planning Your Capsule guide, and you're finally ready to create a capsule of your own!

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. This guide outlines those steps, lists some questions you should ask yourself, and points to relevant documentation for each of those steps.


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

These steps are mostly for creating a capsule from scratch. You can also create a capsule using one of the capsule templates available in Bixby Studio or build off of any of our other sample capsules!

Set Up Your Capsule Workspace


This is an optional starting point. You can use the playground namespace to start developing your capsule until you are more ready for setting up the capsule meta data.

First, go to the Developer Console to set up some information about your capsule.

  • Are you working with other people or is this a solo project? Have you set up your team? Do you have a team already established?
  • Do you need to register your capsule or did a team member already set that up for you?
  • Do you have all the proper permissions for each team member to work on this new capsule?
  • Do you know if there are any configuration properties that need to be set up? (You might need need this later, as you continue to work on your capsule).

Then, you will need to open Bixby Studio and create an empty capsule. This will get you started on setting up your capsule.

  • What devices and locales are you supporting?

    We recommend starting with mobile and your primary language. After you've developed the basic functionality of your capsule, you can then expand to other devices and locales later.

  • Will you need to ask your user for permissions like their contact information or location?

Create Initial Models

Creating your initial set of models is the first step of developing your capsule.

  • What models do you need? For a basic overview of models, see Introduction to Modeling.
  • What actions are needed? For more information, see Modeling Actions.
  • Based on those actions, what concept models do you need? For more information, see Modeling Concepts.
  • If you're using an external API, what structures are being returned from your external service? Can you make a mapping of those structures to a structure model? From those structure concepts, what primitive concepts do you need?
  • Are there models from libraries you can leverage instead? For more information, see library capsules.

Implement the Actions Using JavaScript

To make your models come to life, you need to implement the actions using JavaScript for major API calls.

Train Your Capsule with Initial Training Utterances

Adding training utterances is what helps Bixby learn about how to interact with users. For more information, see natural language (NL) training (utterances).

Further, adding these initial training examples enables you to use NL utterances while testing instead of relying on intents or Aligned NL.

Make Initial Views

Views are the look-and-feel aspect of your capsule. You need to create initial views for lists, summaries, and properties.

  • What results need to be displayed? How will you construct your result views?
  • Are you requiring input from users? Do you need a corresponding input view?
  • Are you listing out multiple results or multiple choices? For more information, see Displaying Lists.
  • Is there something you need to confirm from the user in a confirmation view?
  • Are you following the design Layout Patterns within your views?
  • For each component that you use, are you following the Designing Components best practices?

We recommend you read the Using Expression Language and the Match Patterns Developers' Guides while working on views/layouts, dialog, and strategies. Expression Language helps you use your models directly in these files. Match patterns help Bixby identify which models, dialogs, views/layouts, or strategies to call during execution. You can read the Planner Overview guide to understand more about how Bixby uses these things and your training to dynamically generate a program.

Write Initial Dialogs

Dialogs are how Bixby talks to users, both as displayed text and spoken aloud.

  • What messages will you see in your View files?
  • What Fragments (Value, Concept, Action, other) can you write dialog for?
  • Which Events (Results, NoResults, Progress, other) need dialog?
  • Are you following the best practices and guidelines outlined in the Writing Dialog Design Guide?

If you are planning to support multiple locales, make sure to review how to localize your capsules.

Define Instantiation Strategies and Default Values

Instantiation Strategies offer ways for you to provide some default values to users.

  • Are there obvious default options you can provide for users?
  • Are there any safe assumptions you can make about a user's request, such as a location or date?
  • Should you instead set a single default value within an action?
  • Will your instantiation strategies require any selection learning?

[Optional] Define Selection Strategies and Preference Learning

Selection Strategies and Preference Learning are features you can add to your capsule that enable Bixby to better understand users and provide better results for them as they continuing using Bixby.

  • Are there instances where you expect users to constantly choose the same item every time? Would this benefit from selection learning?
  • If you're implementing selection learning, are you following selection learning best practices?
  • Is there a concept or action that you think users might end up preferring over time, such as a cuisine type? Would this benefit from preference learning?

Create Input Validations and Error Handling Code

When you add input validations and error handling code, it helps ensure that your user's experience is smoother.

  • Are there inputs you might need to double check from the user?
  • Are there situations that you might need to consider catching outside of the scope of your capsule?
  • Have you properly handled the JavaScript side of error handling? For more information, see Throwing Exceptions.
  • Are there runtime flags you can use to override specific runtime execution behavior?
  • Are there other effects you can use to help with the user experience?

Create User Stories for Testing

You should constantly be testing your capsule, either with the Bixby Studio Simulator or with on-device testing.

Additionally, we recommend you set up some user stories so that you can have repeatable testing units that you can easily run, especially as you continue to iterate and refine your capsule.

  • Do you have a user story for all your must-work use cases?
  • Can you branch any of your user stories?
  • Should you add any assertions to your user stories?

Prepare Capsule for Submission and Deployment

After getting the core functionalities of your capsule, you're ready to start the submission and deployment process. If you haven't done the initial step of setting up your capsule workspace, you need to work on that before working on submitting and deploying.

A full checklist of what needs to be done is available in the Deployment Checklist.

Iterate and Refine

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.