Bixby Developer Center

The Facts and Jokes Prototype Capsule allows the user to ask for a random fact and/or joke, with the option to ask for a specific type. You can use this prototype as the starting point for your own Facts or Jokes capsule! This document will help you personalize this prototype for your own needs. Additional information about this prototype capsule can be found in the README.

How This Capsule Works

This capsule is very simple: all the facts or jokes are stored in the content.js file and the GetContent action model returns a Content structure. This Content model corresponds to an item from the content.js JSON file. The GetContent action is tied to the GetContent.js file through the endpoints.bxb file using a local-endpoint and returns a randomized item from content.js.

Each content item is formatted like this:

\\a Content item. the `image` and `tag` properties are optional
{
    tags: ["my tag", "my tag2"], // tags are used to identify the type of object such as "dog" related jokes or facts
    text: "The joke or fact goes here",
    image : {
        url : "images/image.png" // if you provide an image, you can place them in the assets/images folder and refer to them this way; or you can use a fully qualified url like "http://myimages.com/image.png" for externally hosted images
    }
}

If the user request asks for a specific type of joke or fact (for example, "dog jokes"), Bixby processes the optional SearchTerm input. On the JavaScript side, the lib/util.js filters the content with that search term through the tag property.

For output, Bixby says one of two dialog options: either the text from the returned content or Nothing found if no content is available. Additionally a simple view.

For training, both "Tell a joke" and "Tell a fact" are added, as well as two tagged training entries: "Tell me a fact about dogs" and "Tell me a cat joke", with "dogs" and "cats" tagged as SearchTerm values.

How to Customize This Capsule

This section expands on the How to Customize section of the README and gives further tips and tricks for customizing this capsule for your own.

Update Your Capsule Metadata

In order to add this capsule to your Team, you need to update your capsule.bxb file.

1. Update the capsule id from example.fact to the namespace you've registered and whatever capsule name you want to call it. For example, if your namespace is my_org_name and you're making an animal facts capsule, you should rename it to something like my_org_name.animalFacts.
2. (Optional) Add any additional targets, if there are additional languages or devices you'd like to support.

Add Your Own Content

You can manually replace the content.js file information with your own and add more content items as needed. Alternatively, you can use the spreadsheet located at contentUtility/CreateContent.xlsx provided by the prototype. Directions are provided in the spreadsheet.

If you are not linking to images hosted externally, then the local images must be in your assets/images folder. You can sort these images into further subfolders, if necessary. For example, if you want to place all your animal images in one folder and all your plant images into another, you can place them under assets/images/animals and assets/images/plants respectively. You would then refer to each image URL as something like images/plants/tulip.png.

If your content can be accessed through an API instead, you could choose not to use the content.js file and instead Call a Web Service to return a JSON object that contains your material. However, you might have to change the existing modeling action implementations to process this and you might be better off creating a new capsule.

Add and Update Training

We provide several training entries with this prototype. In order for Bixby to understand and properly reply to user requests for your capsule, you need to add additional training examples. You should pay particular attention to adding a few examples with tags that match your content.

Also remove any training entries that are not relevant to your capsule. For example, if you are creating a capsule about plant facts, you should remove all the entries about jokes and the entry that tags cat and dog. The training entries provided are specific to the content provided. Your training examples should only be related to your content.

Optional Enhancements

This section discusses some additional enhancements you can make that are not necessary for your capsule to be functional, but are optional enhancements you can do to further customize your capsule.

Rewrite the Dialog

We provide dialog for content not found, but you can customize it further for your capsule. For example, if you're creating an animal jokes capsule and a user requests for alligator jokes but you don't have any, you could have Bixby say I'm not koala-fied for this! or I'd be lion-ing if I had something for this!. You could also choose to randomize which dialog appears if this happens.

Edit the Views

The View file we currently supply has a simple image-list-of component to help display any image associated with the content. However, you could further customize this. For example, if you are telling plant facts, you could create an image card to show the type of plant you're telling a fact about as well as include the fact as part of the card's title-area.

You could decide to add some input views. For example, if a user asks "Tell me a joke", Bixby could ask What kind of joke? and present the options of knock-knock joke, puns, limericks, or riddles. The complexity of your user flow is up to you.

For more information on designing and updating the view, as well as best practices for user experience, you should read the Designing Conversations guides.