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.

Before you follow these steps, make sure you've registered your team and capsule in the Developer Console. For more information, see Using the Developer Console Developers' Guide.

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.

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:

  store-countries {
all
}

View 1e9150c on GitHub

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:

    store-countries {
only {
allow (US)
}
}

View 4fd0a5c on GitHub

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+
}
}
}
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.

  store-sections {
section (GamesAndFun)
}

View 1e9150c on GitHub

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

Smart home 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

(Optional)

Natural Language Categories (NL categories) are general capsule classes for natural language processing. If your capsule falls under one of these NL categories and you want to allow users to set your capsule as their preferred capsule, you can add various Natural Language category values to your capsule.

For example, if you are creating some type of Astrology capsule, then you might want to add the NL category Astrology. The user can then choose your capsule as the default capsule under Astrology in the "Preferred Capsules" setting.

capsule {
id (...)
version (...)
targets {
target (...)
target (...)
}
permissions{
...
}
capsule-categories{
category (Astrology)
}

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 Astrology NL category, then they can say "Tell me my horoscope" and Bixby will automatically choose your capsule to tell them their horoscope for the day.

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 subscribing to an NL category for 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 not required, your capsule should at least tell the user it cannot support that action.

Even though we list example utterances for each use case, you should add utterances that not only make sense to the NL category's use case but are also appropriate to your capsule's content.

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. Certain keys are required, while others are recommended but optional.

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

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. For 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)
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.

  • 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.

  • 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 on the dispatch-name reference page.

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 on the capsule-info reference page.

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 to use in situations where named dispatch is not required, such as if your capsule is the default for an NL category. Because they are shown only without the dispatch phrase, preferred hints are recommended for handling situations where the hint is not grammatically correct without the dispatch phrase. For more information, see the preferred-hint reference page.

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 (In Space Resorts, find space resorts)
hint (With Space Resorts, find hotels near Mars)
hint (In Space Resorts, research space resorts on Mercury)
}
}

View master on GitHub

The Hints page for a capsule will sort the hints by which target devices the hints are available in, such as Phone/Tablet for mobile. Here are some Marketplace capsules' hints pages:

Hints page for Fifty Fifty Hints page for Word Sensei

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 NL category, you should place the utterance under 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 (Podcast) {
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 uncategorized, visible hints for each store country and device to the Marketplace. 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.
  • If you use categorized hints, you must have at least 3 working hints per NL category.
  • You must have one hint file for each language that your capsule supports.

You can also add several groups of hints in your *.hints.bxb file, with each group having different visibility-constraints. Hints use the same visibility constraints as store sections. However, if you add visibility constraints to your hints, this could affect the total number of hints needed to be accepted to Marketplace.

See the hints reference page for more information and examples.

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 blocks can contain an identical type of legal agreement for the same store-country. However, if you have policies that are covered in one legal agreement URL, you can use the same URL to point to those policies. For example, if your privacy-policy covers the information needed in cross-border-data-transfer, you can use the same URL for both those keys within that country-documents block.

You can specify these types of legal agreements:

Note

Make sure you link to all the appropriate legal agreements required for each store country that you are submitting your capsule to, or your capsule might be rejected for the Marketplace. For example, if you are requiring location access for a capsule in the Korean store country, you need to link that information in additional-terms-and-conditions. Read each of the legal agreement key's reference pages listed above for more information.

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 built-in 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:

Note

You need to test each device and each locale listed in the targets block of your capsule.bxb file. If one of the targets listed doesn't pass the submission process, the entire capsule submission will fail.

Follow Capsule Policies

(Required)

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

Capsule Agreement Policies

This is a summary of agreements that you agree to follow for your capsule. For a full list of current policies, see the Marketplace Capsule Content Policies document.

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.
  • Audio ads are limited to a very short pre-roll ad before or post-roll ad after streaming audio. For example, a short clip that says "Sponsored by ACME Autos" before a podcast episode plays would be acceptable.
  • 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. All terms and conditions that you must agree to before release can be found in the Marketplace Capsule Content Policy Document.

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 have successfully checked off all items on the checklist, you can use the Release Manager to get your capsule reviewed and released to the Marketplace.