Bixby Developer Center

Developers should strive to ensure that users have a predictable experience in Bixby, no matter which capsule they are using. Refer to the design principles behind Bixby while developing your capsule. Also, the Designing Conversations guide describes how each conversation between Bixby and users should flow, including how to write dialog and the components to use in various views. The Designing With Bixby Views guide discusses the components that you should use within views. This guide specifically defines the key policies that govern a consistent user experience with respect to punching out.

In general, users should stay in the Bixby interface while interacting with your capsule. Staying within Bixby allows users to experience efficient and personalized experiences you can offer within your capsule. Additionally, it gives you, as the developer, several benefits:

• Capsules can work across multiple devices seamlessly if you stay within the Bixby interface and leverage Bixby Views.
• You don't have to keep versions in sync between devices. Deep links within apps introduce dependencies between Bixby and specific app versions, but you can avoid this by staying in the Bixby interface.
• Hands/Eyes Free experiences are smoother through Bixby, since users won't have to rely on screen UI for interactions or display.
• The conversation context is known and clear, which allows for building a richer and smarter user experience with deep NL integration and learning.
• Follow-ups are easily supported and based on a result that is within the scope of the Bixby conversation.
• You can contain your work within Bixby Developer Studio. You won't have to span between both the server side and the Android APK side.

When It's OK to Punch Out from Bixby to Your App or Website

As previously mentioned, you should strive to keep your user in the Bixby experience until their task is complete. However, there are a few situations in which leaving the Bixby experience makes sense. These typically break down into two cases: (1) the user asks Bixby to open an app directly and (2) the user taps on something in a Bixby result view that causes a punch-out action for a scenario that is within the defined policy.

If the utterance requires more information (for example, Which John do you want to call? or On which service should I play this video?), you should handle this in Bixby before launching the appropriate application.

You can direct them to a separate application in the following situations:

• The user asks to launch an app with a direct command.
  • "Open the Facebook app"
  • "Launch the YouTube app"
• The user requires a response from a deeply dependent hardware or device sensor feature and using a library capsule feature doesn't fit your user experience.
  • "Take a picture"
  • "Get me directions to 60 S Market street in San Jose, California"
• The user asks to play immersive content beyond a thumbnail video snippet.
  • "Play Grace and Frankie on Netflix"
  • "Launch Clash of Clans"
• The user needs to complete a payment-related transaction. See Payment-Related Transactions.
  • "Order on Cheryl's Cookies"
  • "Buy on TicketMaster"

You can have users tap on a component in Bixby to navigate them out to a website or application in the following situations:

• The user wants more details for a piece of content that is summarized in the Bixby UI (Open app for more information).
  • View an expanded weather forecast with radar
  • View the biography of a musical artist

Payment-Related Transactions

If your user is purchasing something in Bixby, you should have them punch out to the appropriate application to finish the transaction. Your capsule should still help users complete as much of the transaction as possible (such as filling out details of an order or setting the date and time for a reservation), but once Bixby collects that information, you should direct the user to complete payments or bookings in the app or website with the Action Button. For more information on how to punch out, see How to Navigate Users Out of Bixby.

For example, if users say "Buy chocolate chip cookies", your capsule can return a list of results. Once they tap on a result they like, it can direct them to the details view of that item. In the details view, your select-button-text could say something like "Buy on My Cookies Company". When they tap on that Action Button, you can use app-launch to direct users to the "My Cookies Company" app or website, where they can purchase the item.

When It's NOT OK to Punch Out from Bixby

For situations not specifically listed in when you should punch out, you should model and train Bixby to stay within its interface. Additionally, if you need to disambiguate any situation in the previous section, you should gracefully handle this in Bixby before punching out to the app. For example, if users ask "Call John" and there are multiple Johns in their contacts list, you should create an input-view to list the contacts, asking Which John? for users to select.

Do not punch out of Bixby in the following situations:

• To complete a situation that does not fall into the previous section that could be completed in Bixby's interface.
• As an alternative to creating a Bixby Views file, if you can't recreate your UI with Bixby Views. In this situation, you should work with our team to help use Bixby Views with your capsule or to file a feature that you might need.

If you need to direct a user to another location and your situation does not follow the app launch policies listed above, consider using an attribution-link instead. For more examples and additional guidelines, see Punch Out of Bixby Views.

How To Navigate Users Out of Bixby

If you have a scenario that falls into the acceptable situations of when it's okay to leave Bixby, you can punch out using the following methods:

• Punch out of Bixby into an application with the app-launch key in a result-view. This will automatically take a user out of Bixby to the designated application.
• Punch out of Bixby with the on-click key defined in a component to direct them to a URL or an intent that takes them to a separate application. The user must tap on the component in a Bixby View in order to punch out.
• Punch out of Bixby with the attribution-link at the bottom of a result-view. The user has to tap on the link at the bottom of the page to leave Bixby.