Bixby Developer Center

Guides

2018 January–March

Note

Internal platform changes that are not visible to capsule developers will be communicated via internal status updates.

18G Capsule SDK Release Notes

Updated: April 18, 2018

Named Dispatch Support

We've introduced support for named dispatch, which allows users to prefix utterances with specific dispatch phrasing in order to channel them though your capsule. An example of this might be:

  • In Contacts, add my friend Jane with the number 123-456-7890
  • With Maps, take me to my mother's house

For your capsule to support named dispatch, declare a dispatch-name in the appropriate capsule-info.bxb file. You can optionally include up to 5 dispatch-aliases, which are secondary dispatch names:

description {
displayName (...)
icon-asset (...)
...

dispatch-name (spotify)
dispatch-aliases {
alias (spotify Music)
alias (spotify player)
alias (spotify music app)
}
}
Note

A primary dispatch name will always supersede a dispatch alias, so if you add an alias that is currently used as a primary dispatch name in another capsule, that capsule takes precedence.

Required Client App Info for Client Endpoints

If your capsule uses client-endpoints, you must now include client-app-support to specify details of the required companion application, including app ID, minimum required version, and app store URL:

Example

  client-app-support {
app-id (my-app-id)
app-min-version (1234567)
app-store-url (http://url...)
}

action-endpoints {
action-endpoint (login) {
client-endpoint {
...
}
}
}

viv:SelectionButton Deprecated

We have deprecated viv:SelectionButton because users can now select the full row when you use a Selection Picker input component.

Hints

We've introduced Hints, which will be used by Bixby to provide users with suggested queries.

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

You can add suggestions within your capsule by creating a hints.bxb file within your resources folder:

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

For more information, refer to the Hints in the Reference documentation.

Store Country and Device Model within '$vivContext'

You now have access to the following data within $vivContext:

  • storeCountry:
    The store country specified by the client, denoted in ISO 3166-1 alpha-2. Example: US or UK.
  • deviceModel:
    The specific device model of the client. Example: SM-G965N.

For more information, refer to User Context Information in the Developer's Guide.

18F Capsule SDK Release Notes

Updated: April 4, 2018

New Capsule Constraints

We've introduced a way for capsules to specify support of particular countries (in ISO 3166-1 alpha-2 format) and device models (such as SM-G965N) in the capsule.bxb file. These new constraints are optional and different from targets, which specify languages and device types.

Capsules that don't support a certain country or device model will not ultimately be supported in the Marketplace for that country or device model.

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 (KR)
}

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

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

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

Aligned NL Without Revision Override

You no longer need a revision override to use Aligned NL. Bixby can now interpret aligned utterances in synced capsules without a submission.

Prompt Suppression Disabled

We've disabled prompt suppression, which means that, in cases where there isn't a valid Selection Rule that applies, users will be prompted if there is more than one result.

You can read more about Selection Prompts and Selection Rules section of the Selection Learning Developers' Guide.

UI Kit Version 1 Result Components

We've added additional UI Kit components to handle results that include lists and images.

Example Result View Component:

result-view {
  match: Image (this)

  message { template ("Here are some cool images...") }

  render {
    image-list-of (this) {
      size (Small)
      title { template("test images...") }
    }
  }
}

Additionally, you can now add components that currently support cards and cells. Cards provide context and an entry point to more robust information, whereas cells are a collection of list tiles that show related content in a consistent format.

Example Card:

<layout-macro id="common:card">
  <image>{{thumbnail.url}}</image>
  <imageType>thumbnail</imageType>
  <thumbnailPosition>right</thumbnailPosition>
  <title>{{this.name}}</title>
  <titleSize>small</titleSize>
  <bodyText>
    {{#if exists(totalTime)}}<template-macro id="recipe:CookingTime"><number>{{totalTime}}</number></template-macro><br/>{{/if}}
    {{#if exists(nutritionInfo) && exists(nutritionInfo.calories)}}<template-macro id="recipe:CaloriesPerServing"><calories>{{nutritionInfo.calories}}</calories></template-macro>{{/if}}

  </bodyText>
</layout-macro>

You can learn more about the UI Kit output components in the Developers' Guide.

18E Capsule SDK Release Notes

Updated: March 14, 2018

18D Capsule SDK Release Notes

Updated: March 5, 2018

Simplified Labels

We've simplified how you define dialogs to make them easier to write and less verbose. If the dialog requires no conditional logic for rendering, you can define the dialog using label () instead of label { template ()}:

label { template (label text) }

New:

label (label text)

You can use the old or new method, but you will get an error if you use both:

Error:

label (some label) { template (a complex label) }

18B Capsule SDK Release Notes

Updated: Feb 9, 2018

The following release notes specifically cover updates in the 18B Capsule SDK. Internal platform changes that are not visible to capsule developers will be communicated via internal status updates.

Versioned Capsule Imports

When importing capsules, you must now indicate a specific capsule version for each capsule that you import. Importing version-specific capsules help to stabilize your capsule in cases where updates to an imported capsule might adversely affect your own capsule.

Within the capsule.bxb file, you must now include a version for each capsule that you import:

capsule {
id (viv.test)
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)
}
}
}

You no longer have to import all the dependencies of the capsules you import, so feel free to remove the superfluous imports from your capsule.bxb file.

However, in some cases, a capsule you import might require you to import one of its dependencies. For example, to use the viv.flight capsule, you might need to train some viv.geo and viv.time concepts. To get those capsules at the same version as viv.flight, you can define a transitive import using the version-from keyword with the ID or alias of the parent capsule. This inherits the requested capsules at the same version as the reference. The order in which you declare transitive imports is important: first declare the parent import before the transitive import in your list of imports

capsule {
id (viv.test)
version(4.0.0)
format(3)
targets {
target (bixby-mobile-en-US)
}
capsule-imports {
import (viv.flight) {
as (flight)
version (1.0.2)
}
import (viv.geo) {
as (flightGeo)
// reference capsule alias for version
version-from (flight)
}
import (viv.time) {
as (flightTime)
// reference capsule ID for version
version-from (viv.flight)
}
}
}

Keep in mind that you can only import a capsule version that has been publicly submitted.

Note

We encourage you to use capsule aliases (using the as keyword). This reduces the chance of errors caused by Bixby finding more than one version of a capsule. You might also want to update the capsule later. If the capsule ID changes, you have less refactoring to do.

Non-Linear Submissions

With the 18B release, we’ve made submissions non-linear, which means that each capsule submission is standalone and does not build on the state of a previous submission. You can import publicly submitted capsules using their version.

Note

When you make a public submission for a capsule, its capsule version must be unique from all previous public submissions of that same capsule. This requirement currently also applies to private submissions, but we will soon allow you to make multiple private submissions of the same capsule with the same version.

You can continue to check out any CAN revision in Bixby Developer Studio and sync your capsule(s) on top of it. To test NL, Aligned NL, or stories, you should check out a CAN revision containing your submitted capsule.

You can load a revision within Settings using Revision Override:

Revision Override Setting

(Select the image to view a large version)

Removal of Channels

Since capsule submissions are now standalone (non-linear) and capsule imports declare versions explicitly, channels no longer exist. The channel picker has been removed from Bixby Developer Studio, so ensure that you update to the version 4.18 or later.

Endpoints "accepted-inputs" Now Optional

To reduce the need to re-declare inputs, the accepted-inputs key within endpoints is now optional. If accepted-inputs is not present, the endpoint accepts all non-hidden inputs of the action model.

Old:

endpoints {
action-endpoints {
// simple local-endpoint example
action-endpoint (FindMyData) {
local-endpoint (FindMyData.js)
accepted-inputs (input1, input2, input3)
}
}
}

New:

endpoints {
action-endpoints {
// simple local-endpoint example
action-endpoint (FindMyData) {
local-endpoint (FindMyData.js)
}
}
}

Structures Now Inherit Sort Ordering

Structure concepts that extend other structure concepts now correctly inherit their named sort orderings.

Now a child structure that extends a parent structure inherits the parent sort orderings in the following way:

  • If there is exactly one ordering for a given name in the parent structure(s), the child inherits the exact same ordering.
  • If there are multiple ordering declarations for a given name in parent structures (as a structure can extend multiple structures), the child inherits a compound ordering (compound from all the orderings for the name) with that name.
  • If the child structure defines a ordering with the same name as a ordering in the parent structure, it overwrites the ordering from the parent structure.

Structures that contain default-ordering are handled in the same way.

JUEL Java Methods Deprecated

To increase security, we've deprecated access to Java methods via JUEL (Java Unified Expression Language). If you currently use the following methods, you should migrate them:

  • $user.locale.getCountry(): Migrate to $user.locale.country
  • concat: Migrate to string1 + string2

Old:

  case(USD) {
advice("${('foo' + $user.locale.getCountry()) == 'US' ? 1.0: 0.0}")
}

New:

  case(USD) {
advice("${('foo' + $user.locale.country) == 'US' ? 1.0: 0.0}")
}

Old:

  result = result.concat(response.restaurants);

New:

  result = result + response.restaurants;

18A Capsule SDK Release Notes

Stories and Assertions

You can now test your capsule using the new stories and assertions features in Bixby Developer Studio.

Stories enable you to test multiple use cases in your capsule within Bixby Developer Studio and check the results that Bixby returns. For more information about developing stories, see Writing Stories topic in the Testing Your Capsules Developers' Guide.

Assertions enable you to check on a granular level the execution graph of each of the stories you create, including testing layouts and dialogs. You can read about Developing Assertions in the Testing Your Capsules Developers' Guide. You can use the Assertions API while writing assertions to navigate the different nodes or edges in the execution graph. We include several templates to help you get started.

Disabled HTML Tags in Layouts

Certain HTML tags are automatically disabled in layouts. (This refers to the deprecated HTML-based UI Kit.)

Training Statuses Documented

A list of training-related errors is now available at Training Entry Statuses.

Qualify Imported Macros

You must now qualify macros that you import, though macros that are local to your capsule can remain unqualified.

Take, for example, a capsule called viv.capsule1 that defines template macro template1. If you want to import template1 into another capsule called viv.capsule2, you must fully qualify it as shown here:

template-macro(viv.capsule1:template1)

However, if you want to use that same macro within viv.capsule1 itself, you should use the unqualified notation:

template-macro(template1)

You can also use an alias to qualify template macros. For example, if viv.capsule2 imports viv.capsule1 as aliasedcapsule, you can then invoke a macro within it using the alias:

template-macro(aliasedcapsule:template1)

Structures No Longer Have 'Natural-Order' by Default

Structures no longer have a default natural-order unless you explicitly specify one. Previously, every structure was given an arbitrary default-ordering. Now, if you do not specify a default-ordering or natural-order, the structure will not be sortable.

Collections No Longer Sorted by Default

Collections that do not specify a default-sort-order no longer have their results sorted. Previously, collections without a default-sort-order were sorted by the default order of the concept they were rendering. Now, the original collection result order is preserved.