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 Marketplace Constraints

(Optional)

Aside from specifying targets, you can use marketplace constraints to further customize where your capsule is available when the Marketplace is available in specific countries.

By default, a capsule supports all markets. This optional step allows you to either allow or disallow specific countries (in ISO 3166-1 alpha-2 format) and device models (such as SM-G965N).

A market is characterized by a country and a device model. For example, SM-N960U:VZW is the code for a Galaxy Note 9 variant available through Verizon in the United States.

Your capsule can use store-country-constraints and device-model-constraints to control which countries and device models, respectively, are supported. You can specify constraints using either allowed-lists or blocked-lists. Values within an allowed-list are supported, and any values not explicitly listed are unsupported. The opposite is true for blocked-list, where any values listed are unsupported, while values not listed are supported.

Note

There is no direct relationship between marketplace-constraints and targets. With marketplace-constraints, 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 marketplace-constraints determine whether a user in Italy can actually use that capsule.

Within your capsule's capsule.bxb file, you can specify either an allow-list or a block-list, and you can use valid regular expressions:

capsule {
id (...)
version (...)
targets {
target (...)
target (...)
}

marketplace-constraints {
country-constraints {
// either
allowed-list {
allow (US)
}

// or
blocked-list {
block (KR)
}
}

device-model-constraints {
// either
allowed-list {
allow (SM-G965N) // S9+ Korean version
allow (SM-G960[A-Z]?) // any variant of S9
}

// or
blocked-list {
...
}
}
}
}
Note

For details on specific keys, see the related reference documentation on marketplace-constraints keys.

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:

  • language-constraints - Limit by language using the locale code. For example en-US.

  • device-model-constraints - Limit by specific device models. For example, SM-G965N.

  • device-class-constraints - Limit by device type. For example, bixby-mobile.

  • country-constraints - Limit by country using the Alpha 2 ISO 3166 country code. For example, US.

    Similar to marketplace-constraints, you can specify a blocked-list or an allowed-list for each type of constraint.

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 (Example)
developer-name (Example, Inc.)
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 (Example)
dispatch-aliases {
alias (Example Site)
}
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.

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

  • 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

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.

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.