Bixby Developer Center


Capsule Developer Workflow

After you finish going through the quick start guide and the Planning Your Capsule guide, you're ready to create a capsule of your own.

To help with your engineering planning, here are typical tasks that a capsule developer will need to work on, in the order they should typically be done. This guide outlines those steps, lists questions you should ask yourself, and points to relevant documentation for each step.


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're ready to set up the capsule metadata.

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.

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 set a single default value within an action instead?
  • 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 continue using Bixby.

  • Are there instances where you expect users to 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, this helps ensure that your user's experience is smoother.

  • Are there inputs from the user that you might need to double check?
  • Are there situations outside of the scope of your capsule that you might need to address?
  • 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 behaviors?
  • 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 setting up some user stories so that you can have repeatable testing units you can easily run, especially as you continue to iterate and refine your capsule.

  • Do you have a user story for each of 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 setting up the core functionalities of your capsule, you're ready to start the submission and deployment process. If you haven't yet set up your capsule workspace, complete that before working on submission and deployment.

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

Iterate and Refine

After the core functionality of your capsule has been implemented and tested, make sure to iterate and refine your user experience and user interface as needed.