Bixby Developer Center

About This Capsule

This sample campsule demonstrates building a data browser powered by an external data source, as well as a quiz used to make recommendations.

Download this Capsule

File Structure

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.
• code - JavaScript files that execute capsule actions.
  • lib - JavaScript library files used by higher-level scripts.
• models - The actions and concepts used by Movie Agent.
• resources - Folder of resources.
  • base - Base resources used in all targets.
    • all.endpoints.bxb - The endpoints that connect the action models with their JavaScript code.
    • 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.

Sample Capsule Walkthrough

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:

• "Recommend a fantasy movie" (search movies by genre)
• "Show me movies released last spring" (browse movies by release date)
• "What movies did James Cameron work on last year?" (search based on multiple inputs: cast/crew member and date)
• "What movie should I watch?" (start the tree-based quiz for choosing a movie)

Accessing TMDb

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 DateTimeExpression for 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 DateTimeExpression.

The Quiz

The Movie Agent's quiz operates similarly to the Quiz Capsule Template.

• Utterances that start the quiz have a goal of RunQuiz.
• RunQuiz has a default-init block with a goal of UpdateQuiz, which starts the quiz running with its first question. UpdateQuiz returns the current state of the quiz in its output.
• The validate block in RunQuiz checks to see if the quiz.completed boolean value output from UpdateQuiz is false, indicating the quiz has not been completed; if it is, then it uses replan to call UpdateQuiz once more, passing the current state of the quiz back as an input.
• When quiz.completed is true, RunQuiz will reach its output block, returning the value of quiz.finalOutcome.

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?'
  options: [
    // 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'],
      outcome: [
        movieGenreMap.Documentary.bxb,
        movieGenreMap.Music.bxb,
        movieGenreMap.ScienceFiction.bxb,
      ],
      commentary: 'Smart choice.',
    },
    {
      text: 'Black Cat',
      match: ['cat'],
      outcome: [movieGenreMap.Horror.bxb, movieGenreMap.Mystery.bxb, movieGenreMap.Romance.bxb],
      commentary: 'Yay nap time!',
    },
    {
      text: 'Bald Eagle',
      match: ['bald', 'eagle'],
      outcome: [movieGenreMap.Drama.bxb, movieGenreMap.Thriller.bxb, movieGenreMap.War.bxb],
      commentary: 'Very majestic.',
    },
    {
      text: 'Golden Retriever',
      match: ['golden', 'retriever', 'dog'],
      outcome: [movieGenreMap.Animation.bxb, movieGenreMap.Comedy.bxb, movieGenreMap.Family.bxb],
      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 MovieGenre model.

The 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 Movie_Result_From_Quiz specifies 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 lib/movieGenreMap.js.

View Design

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 read more in our Design Guides about designing With Bixby Views, as well as specific tips on designing for multiple devices.

Code Puzzles

You can find hands-on exercises that build on the Movie Agent Capsule in the Movie Agent Code Lab.