Best Practices

Just because you can doesn't mean you should. And just because you aren't doesn't mean you shouldn't. Here are some "best practices" we recommend. This is not all-inclusive, more will likely be added here later.

  • Have different Relay accounts for workflow development and production. And have separate copies of your workflow code between development and production. This helps to provide isolation in case anything goes wrong in development from affecting production.
  • When registering a workflow, you have the option of "installing the workflow" (making the workflow available) to all devices, or to a specific list of devices. In general, we recommend installing the workflow to all devices, unless you want to limit access to the workflow, but the latter means you need to manage which devices it is installed on.
  • Be aware of the utility functions provided in the SDK. They are there to make your life easier. You can find them listed in the Utilities guide and in each language's API reference.
  • Especially during develop and testing, utilize verbose mode in the SDK so you see what is going on, to help diagnose any unexpected behaviors. Also consider making liberal use of logging, so you have visibility to what your workflow code is doing.
  • Call startInteraction before your first interaction with a device (i.e., say, listen, setLed, vibrate, etc). This is how you get an interaction URI for the methods that need it.
  • Don't send an action to a device unless the INTERACTION_STARTED handler has been called, assuming the action API requires an interaction URI parameter. There are a few exceptions to this rule, such as setVar
  • Explicitly call endInteraction when you are done with your workflow logic to cleanly close the interaction. And then within the INTERACTION_ENDED event handler, explicitly call terminate to end the workflow. This should line up symmetrically with the START event and INTERACTION_STARTED event.
  • In your workflow code add a handler for the STOP event. Then you can log a reason when the workflow stops. And when something ends prematurely, you can see it.
  • If you want to know when text-to-speech is being streamed to your Relay device, consider adding a handler for the PROMPT event. Otherwise, you probably don't need a handler for that.
  • If you expect to pass in data to a workflow to customize its behavior, feel free to do that using the CLI's support of key/value pairs with the --arg, --number, and --boolean arguments. This is for when you want the arguments to be the same for every time that trigger occurs. If you want to pass in data that might be different even with the same trigger, the HTTP trigger supports a customized payload. See the documentation for that.
  • If one business logic flow needs to be broken up into multiple short-running workflows for technical reasons, it's OK to put those multiple workflows in one source file that has multiple calls to create Workflow objects and register() them.