Bixby Developer Center

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
• Provide Store Countries
• [Optional] Provide Supported Device Models
• Place Your Capsule in Store Sections
• [Optional] Add Restrictions to Your Store Sections
• [Optional] Categorize Your Capsule

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.

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:

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.
• target-constraints - Limit by a single target.

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.

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.

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:

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")
    }
}

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:

• privacy-policy - Required if you need to ask for permissions. For more information, see Privacy Policy Guidelines.
• terms-and-conditions - Required for each target language you're supporting
• cross-border-data-transfer
• additional-terms-and-conditions

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:

   • Appropriate capsule description.
   • Search key words related to your capsule.

Follow Capsule Policies

(Required)

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

• Ensure your capsule does not violate any of the capsule agreement policies. If your capsule is in violation, it will not be approved.

• Dialog follows the Dialog Best Practices.

• All user interfaces use Bixby Views.

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.

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.