Uh oh! We couldn’t find any match.

Please try other search keywords.

Bixby Developer Center

Guides

Preparing Your Capsule

Before your capsule can be distributed to users, you need to prepare your capsule.bxb file, as well as organizing the capsule files appropriately. Follow these steps before you submit your capsule:

Preparing the capsule.bxb File

The capsule.bxb file handles the metadata required by Bixby to ensure the capsule contents are rendered correctly. This section discusses the different settings you need to update in your capsule.bxb file.

Increase Your Capsule Version

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 Targets

You must also indicate the device types and languages your capsule supports within your capsule's capsule.bxb file. Use targets to specify each pair of device type and language, such as bixby-mobile-en-US. This is important when you want your capsule to support multiple device types.

Here's a sample capsule.bxb for reference:

capsule {
id (viv.test)
// ensure that the version is unique with each submission
version(4.0.0)
format(3)
targets {
target (bixby-mobile-en-US)
}
capsule-imports {
import (viv.measurement) {
as (measurement)
// indicate version for imported capsule
version (2.1.3)
}
}
}
Note

Each target must have at least a device and two-letter language code.

You can find the list of supported targets on the target reference page.

For more information on implementing translated versions of your capsule and organizing your localized text, see How to Localize Your Capsule.

Provide Marketplace Constraints

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.

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 direction relationship between marketplace-constraints and targets. With marketplace-constraint, 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)
allow (CA)
}

// or
blocked-list {
block (AU)
block (UK)
}
}

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.

Grant Capsule Permissions

Your capsule needs to be granted special permissions for certain situations. For a full list of what permissions you can request from users and additional information on implementation, see the permissions key and its child keys in the reference guide.

Depending on which permissions you request, you might have to do additional configuring in order to get the requested information. For example, you might want your capsule to be accessible at the lock screen. You can request from the user to provide your capsule this access with the permissions key:

capsule {
id (...)
version (...)
targets {
target (...)
target (...)
}
permissions{
lock-screen-enabled
}

Once a capsule has lock-screen access, you can choose to only allow certain actions that can be executed from the lock screen. For any actions that you don't want executed from the locked state, you can choose to do one of the following:

  • Validate your inputs by checking for the screen lock using the $screenLocked expressional variable:
      collect {
    input (input) {
    type (InputStruct)
    min (Required) max (One)
    validate {
    if($screenLocked) {
    unlock {
    dialog("Unlock your phone!") // Optional, if not specified a default dialog is shown.
    }
    }
    }
    }
    }
  • Handle the error in your action model by catching the LockedState:
      output (Output) {
    throws {
    error (LockedState) {
    on-catch {
    unlock {
    dialog("Can't do that until you unlock your phone") // Optional, if not specified a default dialog is shown.
    }
    }
    }
    }
    }
  • Throw an exception in your JavaScript by checking for the screen lock using the $vivContext.screenLocked variable:
      if($vivContext.screenLocked) {
    throw fail.checkedError("Your phone is currently locked", 'LockedState', {})
    }

If the user decides not to grant permissions to that capsule, it will continue to execute. For example, if the capsule asks for user-profile-access location and the user denies, the capsule will still be executed, but not have access to the users location. If you want to check if the permission has been granted first, you can use the permissionGranted() EL function or the $vivContext.grantedPermissions variable in JavaScript.

If checking with Expressions:

 output (Something) {
evaluate {
if("#{permissionGranted('user-profile-access')}") {
...
} else {
...
}
}
}

If checking in JavaScript:

var permissions = $vivContext.grantedPermissions
if ('user-profile-access' in permissions) {
console.log("PERMISSON GRANTED")
} else {
console.log("PERMISSION DENIED")
}
Note

The permissions granted is always the permissions of the top-most level capsule. For example:

  • CapsuleA imports CapsuleB.
  • The user invokes CapsuleA.
  • During the execution of CapsuleA an action ActionB from the imported CapsuleB is executed.
  • If the permissions are checked in ActionB, the permissions will be the permissions granted to CapsuleA by the user. This enforces the correct and expected behavior, as the user does not know about imported capsules.

Organize Your Capsule Resources

Your capsule organization should also reflect the device types and languages (Targets) you want to support. For a full list of supported devices and languages, see the target reference doc.

Bixby sorts resources in the following order:

  • spec-lang-country (ex: bixby-mobile-it-IT)
  • spec-lang (ex: bixby-mobile-it)
  • spec (ex: bixby-mobile)
  • lang-country (ex: it-IT)
  • lang (ex: it)
  • base

For example, if you want to support all devices in the US but only mobile devices in Korea, organize your capsule resources in two folders, as shown here:

/resources/en-us/
/resources/bixby-mobile-ko-KR/

The organization of your capsule resources offers fallback support, which lets you reuse parts of your capsule as needed.

Preparing the capsule-info.bxb File

To help prepare your capsule to be available in the Marketplace, you must prepare a capsule-info.bxb that provides information about your capsule, including the capsule name, website, and related branding images.

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:

description {
name (Yelp)
displayName (Example)
companyName (Example, Inc.)
iconUrl (/images/icons/example.png)
imageUrl (https://example.com/brand-image.png)
description (Example allows you to see examples of things.)
websiteUrl (https://www.example.com)
termsUrl (https://www.example.com/TOS.html)
dispatch-name (Example)
dispatch-aliases {
alias (Example Site)
}
actionBgColor (#BF2519)
actionFgColor (#FFFFFF)
}

Refer to the Bixby Reference for more information on specific capsule-info.bxb keys.

Provide Hints for Bixby

Hints are used by Bixby to provide users with suggested queries. You can add suggestions within your capsule by creating a hints.bxb file within your resources folder:

%capsulename%/resources/en-us/*.hints.bxb

Here is an example hints file:

hints {
hint-set (Things to try) {
utterance ([g:KitchenMishap] Burn a pizza)
utterance ([g:KitchenMishap] Overcook a steak)
}
}

The accompanying Set Label ("Things to try") provides the guiding description for the suggested queries.

The text, with the annotations stripped off, such as Burn a pizza, is what Bixby shows to users.

If the hint goal is tagged as a continuation, it only shows up when the user's previous goal was a continuation goal.