Bixby Developer Center

Guides

Preparing for Release

Submission Checklist

If you are planning to do a public submission of your capsule and release it to users through the Marketplace, there are some additional prerequisite steps that need to be taken. Follow these steps before you submit your capsule.

Update Your capsule.bxb File

There are additional items for your capsule.bxb file that need to be prepared for a public submission.

Increase Your Capsule Version

(Required)

Ensure that each public submission version in your capsule.bxb is unique and uses this format:

major.minor.patch

The capsule version must be a string with three numeric parts: "X.Y.Z". Each part must be an integer with no leading zeroes.

Bixby Developer Studio checks the version at submission time. If your capsule's version number already exists, the submission will fail with a Capsule Version Check Failed error:

Capsule Version Check Failed

Provide Store Countries

(Required)

You must provide specific store countries that your capsule can be available in by allowing or blocking specific countries (in ISO 3166-1 alpha-2 format) with the store-countries key in your capsule.bxb file.

If you want your capsule available in all Marketplace store countries, you can set store-countries to all:

capsule {
...
store-countries {
all
}
}

You can add exceptions to this list using the except key.

capsule {
...
store-countries {
all {
except (CN)
}
}
}

If you need to choose specific countries, you can list each country under the only key:

capsule {
...
store-countries {
only {
allow (US)
allow (GB)
allow (KO)
}
}
}

You cannot add both an all and an only key under store-countries.

Note

There is no direct relationship between store-countries and targets. With store-countries, you specify which users have access to use your capsule. However, with targets, you specify the device type and language that is supported. If a capsule has target (bixby-mobile-it-IT), for example, that means that users can talk to the capsule in Italian while on a mobile device. But store-countries determine whether a user in Italy can actually use that capsule.

Provide Supported Device Models

(Optional)

Similar to providing store countries, you can limit which device models your capsule is available on with the device-models key in your capsule.bxb file. This is useful, for example, if you only want your capsule to run on Galaxy S9 and S10 models of mobile devices and not tablets.

capsule {
...
device-models {
only {
allow (SM-G973[A-Z]*) // Galaxy S10
allow (SM-G975[A-Z]*) // Galaxy S10+
}
}
}
Choose Store Sections

You must choose which sections of the Marketplace that your capsule appears by placing your capsule in specific store-sections. Sections correspond to Categories in the Bixby Marketplace:

Store Categories

Place Your Capsule in Store Sections

(Required)

You must choose at least one store section to place your capsule in for the Marketplace. You can specify up to two store sections for your capsule. The full list of supported store section options is available on the reference page.

capsule{
...
store-sections {
section (Photography)
section (NewsAndMagazines)
}
}

Here is an example of the EducationAndReference store section in the Marketplace, with several capsules listed:

Education and Reference store section

Add Restrictions to Your Store Sections

(Optional)

If you need to, you can restrict which store sections users see your capsule in by using visibility-constraints. This is useful for placing your capsule in different sections of the Marketplace, depending on different criteria. For example, if you have a business directory capsule, you might want to list your capsule as BusinessAndFinance and Local, but additionally add ArtAndLifestyle and FoodAndDrink for just US users. Another example is if you want your capsule to be available on certain mobile devices in the US, but not in other countries yet.

capsule {
...
store-sections {
section (FoodAndDrink)
section (ArtAndLifestyle)
section (Local) {
visibility-constraints {
country-constraints {
allowed-list {
allow (US)
allow (KR)
}
}
}
}
}
}

These are the types of constraints you can use:

You can specify a blocked-list or an allowed-list for each type of constraint using valid regular expressions, but you cannot specify both lists.

Categorize Your Capsule

Natural Language Categories (NL categories) are general capsule classes for natural language processing. If you want to allow users to set your capsule as the preferred capsule for one or more categories, you can add various category values to your capsule.

For example, if you are creating some type of media-player capsule, then you might have various NL categories like News, Radio, and Podcast. The user can then choose your capsule as the default for any of those NL categories.

capsule {
id (...)
version (...)
targets {
target (...)
target (...)
}
permissions{
...
}
capsule-categories{
category (News)
category (Podcasts)
category (Radio)
}

This gives you the added advantage of letting users invoke your capsule without having to use named dispatch. This means, for example, if users choose your capsule for the default Radio NL category, then they can say "Play classical music" and Bixby will automatically choose your capsule to play a radio station that plays classical music.

Note

Because named dispatch is not required for a range of utterances covered in an NL category for a capsule that a user has set as a default, it is important to check that your hints are categorized with the for-category key and that they work without the dispatch phrase. If the hint does not make sense without the dispatch phrase, make sure to add a preferred-hint.

Keep in mind that adding NL categories to your capsule does not replace proper training for your capsule. You still need to handle the natural language scope of any NL categories that you enable support for. If your capsule doesn't support a particular utterance related to that NL category and that use case is optional, we recommend that your capsule at least tells the user it cannot support that action. For more information on how to handle the required use cases of en-US capsules, read the capsule-categories reference page. For a list of specific use cases you need to handle in each NL category, you can read that specific NL category reference page.

If necessary, you can also limit the visibility-constraints with the same constraint choices as listed in store sections.

Create Your capsule-info.bxb File

You must prepare a capsule-info.bxb that provides information about your capsule, including the capsule name, website, and related branding images. This information displays in your capsule's Details page:

Capsule details

Some of these fields are also displayed while the user is in the capsule, such as icon-asset and display-name:

Other details

Note

You must have a capsule-info.bxb that is specific to each locale that your capsule supports. Place the file in the locale-specific /resources/ folder. Example:

/resources/en or /resources/en-US

Here's an example of a capsule-info.bxb file:

capsule-info {
display-name (The Example Company)
developer-name (The Example Company)
icon-asset (/images/icons/example.png)
description (Example allows you to see examples of things.)
website-url (https://www.example.com)
terms-url (https://www.example.com/TOS.html)
privacy-policy-url (https://www.example.com/privacy.html)
search-keywords {
keyword (Example)
}
dispatch-name (The Example Company)
dispatch-aliases {
alias (Example Company)
}
action-bg-color (#BF2519)
action-fg-color (#FFFFFF)
}

For more information about the capsule-info.bxb file and all of its child keys, see its reference page.

Required Keys

(Required)

Make sure you have values for the following keys, as they are required for Marketplace approval:

  • description - Describes your capsule to users.

  • dispatch-name - Enables your capsule to be called using named dispatch with a unique name. For more information and additional requirements for named dispatch, see Choose a Dispatch Name and the reference page.

  • display-name - Displays the name of your capsule. This name is unique to your capsule.

  • icon-asset - Displays the icon image with your capsule in the Marketplace.

  • developer-name - Displays the developer name to users.

  • privacy-policy-url - Allows you to ask for specific permissions from the user. This is required only if you plan to ask the user to grant permissions to specific user-sensitive data. See Privacy Policy Guidelines.

    Note

    This key will be deprecated in the future. You should start migrating your capsule to use a legal.bxb file to handle legal agreements. For more information, see Provide Legal Agreements.

  • search-keywords - Makes your capsule more searchable in the Marketplace. You can find recommendations for adding keywords in the reference page.

Recommended Optional Keys

(Optional)

The following keys are recommended, but not required for Marketplace approval:

  • dispatch-aliases - Additional requirements for named dispatch aliases are listed on the reference page and the dispatch-name reference page.

  • terms-url - Points to terms and conditions for the user of using your capsule.

    Note

    This key will be deprecated in the future. You should start migrating your capsule to use a legal.bxb file to handle legal agreements. For more information, see Provide Legal Agreements.

  • website-url - Points to your website.

Choose a Dispatch Name

The dispatch-name is a unique name that users say to directly interact with your capsule, for example "Using ACME maps, how do I get to 1600 Pennsylvania Ave?". In practice, it should be as close to your display-name as possible. You can read more about how named dispatch works here.

All dispatch names are unique, so you should make sure to choose a dispatch name that is representative and specific to your capsule. Additionally, choose a dispatch name that you've tested and works with Bixby's Automatic Speech Recognition (ASR). If Bixby doesn't understand your dispatch name, you might experience delays in getting your capsule reviewed for Marketplace.

If you need to add variations that are conceptually the same to your dispatch name or if you need to add ASR guidance, you can add dispatch-aliases.

You can read the full list of restrictions and requirements here.

Provide Hints for Bixby

(Required)

Hints are used by Bixby to provide users with suggested queries. All your hints must use a dispatch phrase, which is an utterance phrase combined with your dispatch name used by Bixby to call your capsule. You can find the full list of named dispatch phrases in the section for your locale under Reserved Utterances. You can add a preferred-hint to a hint, which can be used in situations where named dispatch is not required. Preferred hints are recommended to handle situations where the hint is not grammatically correct with the dispatch phrase. For more information, see the reference pages.

You can add suggestions within your capsule by creating a insertyourowncapsulename.hints.bxb file within your resources folder:

resources/en-us/*.hints.bxb

Here is an example hints file:

hints {
uncategorized {
hint ("With ACME Smart Helper, start the car")
hint ("Ask ACME Smart Helper to find my keys") {
preferred-hint ("Find my keys")
}
hint ("In ACME Smart Helper, turn on the lights") {
preferred-hint ("Turn on the lights")
}
}
}

Here are some Marketplace capsules' hints page:

Hints Ex 1 Hints Ex 2

You can sort your hints based on the different capsule-categories you add to your capsule file. For any hints you want to add that do not fall into a specific category, you can place the utterance in the uncategorized key.

hints {
for-category (Radio) {
hint ("In ACME Media Player, play some classical music")
hint ("Ask ACME Media Player to play my local hip-hop station")
hint ("With ACME Media Player, play KMEL")
}

for-category (Podcasts) {
hint ("In ACME Media Player, play the newest episode of philosophize this")
hint ("Ask ACME Media Player for my favorite podcast")
hint ("Ask ACME Media Player to play an episode of rewatching")
}

uncategorized {
hint ("In ACME Media Player, tell me a story")
hint ("Ask ACME Media Player to start something interesting")
hint ("With ACME Media Player, play something relaxing")
}
}
Note

Your hints must follow these requirements in order to be considered for Marketplace:

  • You need to provide at least 3 working hints. If the hints do not work, your capsule will be rejected.
  • Your training and action implementations need to be able to handle these hints well. This includes any preferred-hint utterances you add.
  • These hints must be top-level utterances, meaning they should not be trained as continuations or responses to prompts.
  • You must have one hint file for each language that your capsule supports.

Provide Legal Agreements

You should create a legal.bxb file in your capsule's root directory, which points to the various legal agreements for each country that your capsule is available in. For example, if your capsule is available in the Korean Marketplace and supports the ko-KR target, you should make sure that all the legal agreements for Korea are correctly linked and pointed to in your legal.bxb file.

legal {
country-documents {
store-country (KR)
terms-and-conditions {
url (https://mycapsule.com/korean-toc)
}
privacy-policy {
url (https://mycapsule.com/korean-privacy-policy)
}
additional-terms-and-conditions {
url (https://mycapsule.com/korean-location-terms.com)
}
cross-border-data-transfer {
url (https://mycapsule.com/korean-cross-border-data-transfer.com)
}
}
...
}

If you have multiple countries that could be covered with a single legal agreement, for example if you have one privacy policy that covers all of North America, you can bundle your agreements by adding multiple store-country keys within a single country-documents block:

legal {
country-documents{
store-country (CA)
store-country (MX)
store-country (US)
privacy-policy{
...
}
}
...
}

Each type of legal agreement must be unique for a given store-country, meaning no two country-documents block can contain an identical type of legal agreement for the same store-country.

You can specify these types of legal agreements:

Test Your Capsules Thoroughly

(Required)

Make sure you test your capsule with respect to the following:

  1. Device: You can test your capsule with the simulator. If you use any of the following features, you must do some on-device testing:

    • If your capsule interacts with a native client, such as using app-launch to punch out to a client app.
    • If your capsule implements the audio player library capsule.
    • If your capsule uses a "Share Via" feature.
    • If your capsule implements payments.
  2. Language: In addition to ensuring that your localized content is correct, you should check the following, for each language, in your capsule-info.bxb file:

Follow Capsule Policies

(Required)

You need to make sure that your capsule also follows these policies:

Capsule Agreement Policies

By submitting a capsule for the Marketplace, you agree to not violate any of the capsule agreement policies, including but not limited to the following:

  • Content is appropriate throughout the capsule. For example, you do not have an inappropriate capsule name, do not use bad language, do not promote violence, etc.
  • There are no embedded displayed ads in your capsule.
  • No accessing user-sensitive information without the user granting permissions.
  • You have a valid privacy policy linked in your capsule-info.bxb file, if applicable.
  • You have a valid terms and conditions linked in your capsule-info.bxb file, if applicable.
  • Your capsule name is valid. For example, if you do not belong to the Samsung organization, you cannot create a capsule called myTeam.SamsungCapsule.
  • Your capsule is not providing a health or emergency services that should be handled by professionals.
  • You are not collecting payment through invalid methods. Contact us via support if you want to enable payments in your capsule.
  • Content is not offensive to any religious, political, ethical, ethnic, or cultural group.
  • You do not violate any copyright or trademark laws and/or you do not make any misleading claims.
  • Content is not harmful to users. This can include, but is not limited to illegal drug use, piracy, gambling, defamation, slander, etc.
  • Your dispatch-name and dispatch-aliases should match the requirements and restrictions listed on the dispatch-name reference page.
Note

The list of agreement policies is subject to change. If you are in violation of this agreement, the approval team will issue you an error report.

Additional Notes and Best Practices

You need to follow this checklist in order to be approved for submission to the Marketplace. If there are any issues with your capsule or if your capsule does not follow this checklist, your capsule will likely be rejected.

After you successfully have checked off all items on the checklist, you can use the Release Manager to get your capsule reviewed and released to the Marketplace.