Bixby Developer Center

Guides

Setting Up Your Capsule

Before you can work on your capsule, you need to prepare your capsule.bxb file, as well as organize the capsule files appropriately.

Create the capsule.bxb File

When you create a new capsule from scratch, one of the files that is automatically created is the capsule.bxb file in your capsule's root directory, which handles the metadata required by Bixby to ensure the capsule contents are rendered correctly.

This is what it looks like:

capsule {
id (playground.tester) // your ID will match your org and capsule name that you choose
version (0.1.0)
format (3)
targets {
target (bixby-mobile-en-US)
}
}

This section discusses the different settings you need in your capsule.bxb file in order to start working on your capsule.

You can always update your capsule.bxb if you decide to change the designs and plans for your capsule.

Set Device and Locale Targets

You must 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 locale, such as bixby-mobile-en-US. This is important when you want your capsule to support multiple device types in multiple regions of the world.

Here's a sample capsule.bxb for reference:

capsule {
id (example.test)
// ensure that the version is unique with each submission
version(4.0.0)
format(3)
targets {
target (bixby-mobile-en-US) //supports US-English mobile devices
}
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.

Import Library Capsules

We've provided several capsules that contain commonly used models. For example, viv.time has Date and Time concepts, with several actions to process those concepts. Instead of trying to model your own, you can import the viv.time capsule.

If you try to use one of these models without importing it, you won't be able to run your capsule.

For more information, you can read the Library Capsules topic and the individual library capsule topics.

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{
user-profile-access
}

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 EL:

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("PERMISSION GRANTED");
} else {
console.log("PERMISSION DENIED");
}
How Capsules Inherit Permissions

Because users do not know about capsules that are imported, the way that permissions are inherited vary depending on the permission.

Some permissions are top-level capsule-based permissions, such as user-profile-access. This means that you would only need to declare them at the top-level capsule that needs the permission. These permissions are checked at execution, prompted for a value from the user, and the value the user gives (either granted or denied) persists for the entire execution of the request.

For example, consider a capsule called RestaurantFinder that declares permissions { user-profile-access } in order to access a user's location. When a user asks Bixby "Find Italian restaurants nearby", Bixby checks for the user-profile-access permission and prompts the user if no persisted value exists. If the user grants the permission, RestaurantFinder can access the user's location. However, if the RestaurantFinder never declares the user-profile-access permission, Bixby does not check or prompt the user for the user's location and the RestaurantFinder capsule won't get that information either.

You might want to test that the permissions are being properly prompted-for and granted using on-device testing.

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/

Anything language-specific should be put in the corresponding language's resource folder. For example, each language should have their own training and vocab files.

The organization of your capsule resources offers fallback support, which lets you reuse parts of your capsule as needed. For example, you can organize your capsule to use the same English dialog (en-US), but different layouts depending on the device type.

Consider the following example with bixby-mobile-en-US and bixby-tv-en-US:

resources/en-US/Recipe_Results.dialog.bxb
resources/bixby-mobile-en-US/Recipe_Summary.layout.bxb
resources/bixby-tv-en-US/Recipe_Summary.layout.bxb
Note

Note that your macros follow a certain hierarchy within your resource folders. Bixby defaults to the base directory for your dialog and layout files, unless you provide a more specific resource bucket with a file defined for that instance.

You cannot have a macro with the same ID if the macro is defined in the same resource folder. For example, if you have a macro with the ID "this-test-macro" in the bixby-mobile-en-US target, you cannot have another different macro with the same name in that target.

However, if the macro's target is in a higher level resource folder, the more specific target will override the more general target. For example, say you have a macro in bixby-mobile-en and another macro in bixby-mobile-en-US, both with the ID "this-test-macro". The macro in the bixby-mobile-en-US target will render for the bixby-mobile-en-US target, but the bixby-mobile-en macro will render for the bixby-mobile-en-GB target.

Macros with the same ID but in different targets (for example, bixby-mobile-ko-KR and bixby-mobile-en-US) are allowed and are encouraged, especially when localizing or handling development for multiple devices.