Bixby Developer Center

Top-level declaration of hints. Hints are used by Bixby to provide users with suggested queries. Hints consist of a named dispatch phrase and a suggested utterance. All hints must have a dispatch phrase associated with them to ensure that they go to the correct capsule.

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 sort the hints by the capsule's category. For example, if you have a media playing capsule, you might use a set of hints with for-category (Radio) and another set with for-category (Podcast). If there are any hints you need to add that are not related to a specific category, you can place them in uncategorized. For more information, see Categorizing Hints.

You can also provide multiple hint groups within a single hints.bxb file, which is especially useful if you need different visibility-constraints. For example, if your capsule is available in the Marketplace, targets en as a locale, but has different NL categories depending on the country store, you can have a single resources/en/hints.bxb file with similar visibility constraints as your NL categories. Another example is using target-constraints to separate hints by regional vocabulary.

If you add visibility constraints to your hints, though, this might affect the total visible number of hints you need to submit to Marketplace. For example, if you have a capsule for mobile and watch, but mobile targets the US in English and Korean store countries in Korean, while the watch target is only for en-US, you need to make sure you have 3 hints visible and working for mobile in English, 3 hints visible and working for mobile in Korean, and 3 hints visible and working for watch in English. You can choose to do this in several ways. For example, you can create separate help files for each subset of the Marketplace you want to support, or you can have a single hints file without any restrictions that shows up in all store countries.

You must provide at least three uncategorized, visible hints that work when submitting to the Marketplace for each store country and device. For more information, see Provide Hints for Bixby.

You must define this top-level key and its child keys in a *.hints.bxb or hints.bxb file. This file must be in the appropriate locale-specific resources folder.

Examples

Hints file with NL categories and uncategorized hints:

// resources/en/my_hints.hints.bxb
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")
    }
}

Hints file with only uncategorized hints, in English and in Korean:

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

hints {
  uncategorized {
    hint (스페이스 리조트에서 금성에 무중력 골프장이 있는 리조트 보여줘봐)
    hint (스페이스 리조트 열어서 해왕성에 키즈룸이 있는 호텔 찾아봐)
    hint (스페이스 리조트에서 토성 근처 리조트 검색해줘)
  }
}

View master on GitHub

Separating hints by regional vocabulary using target-constraints:

// For US stores
hints {
  visibility-constraints {
    target-constraints {
      allowed-list {
        allow (en-US)
      }
    }
  }
  uncategorized {
    hint ("Ask ACME Smart Helper to find my garage keys")
    hint ("Ask ACME Smart Helper to start the car")
    hint ("In ACME Smart Helper, turn on the lights")
  }
}
hints {
  visibility-constraints {
    target-constraints {
      allowed-list {
        allow (en-GB)
      }
    }
  uncategorized {
    hint ("Ask ACME Smart Helper to find my car parks keys")
    hint ("Ask ACME Smart Helper to start the car")
    hint ("In ACME Smart Helper, turn on the lights")
  }
}

Categorizing Hints

If you choose to put your capsule in one or more NL Categories, you should make sure that each NL category has at least three working hints, as well as three uncategorized hints. Because users don't need named dispatch to use your capsule if they choose to make it a default, you should add a preferred-hint to make sure the hint makes sense without it.

Here is a working example of the "My Japanese Dictionary" capsule, which is part of the Translators NL category.

hints {
  for-category (Translators) {
    hint ("Ask My Japanese Dictionary what is artificial intelligence in Japanese?") {
      preferred-hint ("What is artificial intelligence in Japanese?")
    }
    hint ("Ask My Japanese Dictionary what is alligator?") {
      preferred-hint ("What is alligator in Japanese?")
    }
    hint ("Ask My Japanese Dictionary what is crab?") {
      preferred-hint ("What is crab in Japanese?")
    }
    hint ("Ask My Japanese Dictionary what is the character for fire?") {
      preferred-hint ("What is the character for fire in Japanese?")
    }
  }
  uncategorized {
    hint ("Look up teacher with My Japanese Dictionary")
    hint ("Character for rain in My Japanese Dictionary ")
    hint ("Look up a word with My Japanese Dictionary ")
    hint ("Look up a character with My Japanese Dictionary ")
  }
}