Bixby Developer Center

This prototype can be used as a base for your own Quiz capsule, letting Bixby users answer either multiple choice and free-form questions. For more information about this prototype capsule, view the README file.

Adding Questions

The questions for the quiz are stored in JSON in the code/data/quizzes.js file. This file has four top level keys:

• title: The quiz title. This is required.
• tags: An optional array of keywords that Bixby can use to find the quiz. For instance, a quiz about animals with silly answers might have ["funny", "animal"] as its tags.
• image.url: The URL of an image to display when the user starts the quiz; it can be a public URL, or a relative path to an image file in the capsule's /assets folder. This is optional.
• questions: An array with one or more question objects to ask during the quiz. This is required.

Each question object has the following keys:

• question: The text of the question to ask.
• options: An optional array of multiple choice answers to the question. If this is present, Bixby will display the options on the screen and read them out, letting the user select one to answer. If this is not present, the question will be considered free-form, and the user must type or say the answer.
• answer: The correct answer to the question.
  • If options is not present, this must be a text value to match.
  • If options is present, you can use either a text value that matches a value in the options array, or the index of the correct option (where 0 is the first option).
  • Instead of a single value, you can use an array for the answer to allow multiple correct answers.
• explanation: An optional explanation for the answer to show when Bixby displays the summary of the quiz.

JSON Quiz Example

Here's a full (simple) quiz:

module.exports = [
  {
    title: 'Funny Quiz',
    tags: ['funny', 'animal'], //used to find this quiz
    image: {
      url: '/images/Dogs.jpg',
    }, //optional
    questions: [
      {
        question: 'What do cats like to eat on a hot day?',
        options: ['Mice cream', 'Ice Cream', 'Hot Cream'],
        answer: 0, // Corresponds to "Mice cream"
      },
      {
        question: 'What do you call a cold dog?',
        options: ['Frozen', 'Hot dog', 'Chilli Dog'],
        //you can enter the answer as a string instead of using the index
        answer: 'Chilli Dog',
        //you can optionally provide an explanation
        explanation: "Because it's cold. Get it?",
      },
    ],
  },
]

Using the Spreadsheet

The prototype includes a Microsoft Excel spreadsheet in the contentUtility folder which can help you create the JSON for a quiz. Enter the questions, options, answers, and explanations in columns A–D and copy the created JSON from column G.

How the Capsule Works

A quiz is located by name or keyword using the FindQuiz action, whose goal is StartQuiz. The StartQuiz action is the heart of the Quiz capsule:

action (StartQuiz) {
  description (Keep prompting the user for answers until quiz is completed.)
  type (Calculation)
  collect {
    input (quiz) {
      type (Quiz)
      min (Required) max (One)
      default-init {
        intent {
          goal: FindQuiz
        }
      }
      validate {
        if (!quiz.completed) {
          replan {
            intent {
              goal: UpdateQuiz
              value { $expr(quiz) }
            }
          }
        }
      }
    }
  }
  output (Quiz)
}

This demonstrates a technique for maintaining state (the current question and the correct/incorrect answers) as Bixby moves through questions.

• First, StartQuiz gets a quiz with the default-init block, which runs the action FindQuiz.

• After it gets a quiz, the validate block tests whether or not the quiz.completed boolean value is true or false.

  • If quiz.completed is false, the replan block executes UpdateQuiz, which takes the quiz and a user's answer as inputs, checks whether the user got the answer correct, and gives the updated quiz to the StartQuiz action. UpdateQuiz will toggle quiz.completed if the user has answered the last question.
  • If quiz.completed is true, StartQuiz will give you the completed quiz and you'll see your quiz's results.

The JavaScript code for UpdateQuiz in code/UpdateQuiz.js updates counters for the number of total questions answered, questions answered correctly, and the questions left, as well as setting the quiz.completed flag.

Customization

To make a new capsule based on this prototype, you'll have to start by updating the metadata in the capsule.bxb file. Change the capsule id from example.quiz to your team's namespace and a unique name for the capsule. If your namespace is my_team and you're making a quiz about delicious tropical fruits, you might use my_team.quiz_tropical_fruits.

You can edit dialog statements in the resources/en/dialog/ folder and the macros/ subfolder. This could let you customize dialogue to give your quiz a more specific branding or personality. Dialog you write should match our Writing Dialog Design Guide.

Views are stored in resources/base/views/. If you'd like to update the existing views, read the Designing Conversations guide.

The training for this capsule is very simple: a handful of utterances that can be used to start a quiz (with and without an initial search term), and one utterance used at the answer prompt which is simply the answer concept itself. Depending on your quiz, you might want to add new training.

If you are not linking to images hosted externally, the local images must be in your assets/images folder. You can sort these images into further subfolders, if necessary.

The capsule could be designed to fetch the JSON array for the quiz questions and answers from an external web service rather than reading the quizzes.js file. To do this, you'll need to modify the code/FindQuiz.js file to call the external API.