This sample campsule demonstrates building a data browser powered by an external data source, as well as a quiz used to make recommendations.
Because you cannot submit a capsule with the
example namespace, in order to test a sample capsule on a device, you must change the
id in the
capsule.bxb file from
example to your organization's namespace before making a private submission.
For example, if your namespace is
The following folders and files are included in the sample capsule. More information about what these files do and how they interact with each other are explained further in the walkthrough.
README.md- Repository-level documentation for Movie Agent.
capsule.bxb- Metadata Bixby needs to interpret capsule contents.
conceptsused by Movie Agent.
resources- Folder of resources.
base- Base resources used in all targets.
capsule.properties- Configuration information for the capsule.
dialog- Dialog files that determine what Bixby tells the user.
layout-macros- Layout files that help determine what the user sees.
views- Folder of Views files that help determine the user experience per each moment during the conversation.
bixby-watch- Layout and view files specific to watch device targets.
en- Folder containing files for English-speaking locales.
training- Folder of training files that help Bixby learn to generalize within this capsule. Do not edit these files directly, but use Bixby Developer Studio's Training Editor.
all.hints.bxb- Hints used to provide users with suggested queries.
capsule-info.bxb- The metadata used to categorize the capsule in the Bixby Marketplace.
MovieGenre.vocab.bxb- Vocabulary information that provides different ways to reference movie genres.
template-macro-defs.macro.bxb- Dialog macros, reusable strings for the capsule's dialog.
The Movie Agent capsule is designed to give users recommendations for movies they might enjoy. Users can ask the capsule to recommend a movie by genre, browse movies by their release dates, search movies based on cast and crew information, or play a quiz that guides them toward a movie choice.
Here are some utterances the capsule knows:
The Movie Database (TMDb) is a crowd-sourced database with information about movies and TV shows that Movie Agent uses for its data. The capsule uses functions in
lib/TMDB.js to communicate with the TMDb API.
The API key is stored in the
capsule.properties file. In a production capsule, you would want to store your own key in the Configuration & Secrets section of the Developer Console rather than in the properties file.
discoverMovie: calls the TMDB Discover API, which searches movie by a variety of criteria. Movie Agent supports searching by a
DateTimeExpressionfor a range of release dates, by person (cast or crew member for a movie), or genre.
getMovie: gets data about a specific movie, given the TMDB movie ID.
getMovieCredits: gets credits for a specific movie, given the TMDB movie ID.
getTrendingMovies: gets popular movies whose release dates are within the range of a
The Movie Agent's quiz operates similarly to the Quiz Capsule Template.
default-initblock with a goal of
UpdateQuiz, which starts the quiz running with its first question.
UpdateQuizreturns the current state of the quiz in its output.
RunQuizchecks to see if the
quiz.completedboolean value output from
false, indicating the quiz has not been completed; if it is, then it uses
UpdateQuizonce more, passing the current state of the quiz back as an input.
RunQuizwill reach its
outputblock, returning the value of
Unlike the Quiz Template, there are no right or wrong answers in the Movie Agent Quiz. Instead, each answer is associated with an array of movie genres. Here's a sample question in JSON format:
question: "What animal would you want to be for one day?"
// a single option is a JSON object with name (text), an array of regexes
// that are used to match the option, an array of movie genres, and Bixby's
// response if this option is selected.
text: "Bottlenose Dolphin",
match: ["bottle[-\s]?nose", "dolphin"],
commentary: "Smart choice."
text: "Black Cat",
commentary: "Yay nap time!"
text: "Bald Eagle",
match: ["bald", "eagle"],
commentary: "Very majestic."
text: "Golden Retriever",
match: ["golden", "retriever", "dog"],
commentary: "Good choice."
As the user goes through the quiz, the genres their answers return are saved. At the end of the quiz, the genres are counted and sorted from most often returned to least often returned, and the top outcome is returned to the
RunQuiz action, whose output is a
Movie_Result_From_Quiz.dialog.bxb file is used to read the result to the user rather than the more general
Movie_Result.dialog.bxb file, because
from-output: RunQuiz in its
match block, making it a more precise match pattern.
The movie genres are mapped to TMDb ID numbers by a hardcoded JSON data object in
In Bixby, there are two ways of customizing views for each target: dedicated views for each target, and device-specific conditionals within the views. The Movie Agent capsule defines dedicated views. This is the best choice if, as in this case, the view definitions are very different for each device. It's best to use single cross-device views if the views are fairly similar across devices and you can make small tweaks with conditionals rather than large customizations.
You can find hands-on exercises that build on the Movie Agent Capsule in the Movie Agent Code Lab.