Owncast

External Actions

You can build additional interfaces that are hosted with any add-ons, extensions, or 3rd party sites. Each action is a single URL or custom HTML that will be loaded and displayed when a user presses a button on the Owncast page.

External actions was first supported in Owncast 0.0.7.

Examples

Some examples of this functionality might be things like:

  1. A leader board for some chat-based game you built or an external game you’re playing on stream.
  2. Lists of actions that perform fun animations on your stream overlays when selected.
  3. Integrations with your polling chat bot that shows recent polls and the results.
  4. Tip Jar to accept donations.
  5. A schedule that is fancier or more interactive than what you can represent in Markdown.

Limitations

  1. URLs embedded via external actions must be hosted on a server that supports SSL and has a https protocol. Unsecured URLs are not supported.
  2. These URLs must support existing inside an iframe. This means X-FRAME-OPTIONS and the CSP cannot be blocking. If you are blocked then you’re limited to loading this URL in a new tab and that’s not a great experience.
  3. While you can experiment with using URLs that you don’t personally control, it’s often likely that many of them will not work due to limitations placed on the remote server. An example of this is just throwing in a PayPal or Google URL.

How to register actions

  1. Visit the admin, and under “Integrations” go to the “External Actions” page.
  2. Add an action.
  3. Set the URL or custom HTML of this action. URLs should be a HTTPS destination and follow the best practices listed.
  4. Give it a name that will be displayed on the button that launches this action, an optional description that will show in the modal that presents the action, a URL to an optional icon for the button, and optionally a color that will be used for the button.
  5. If you really want to register a URL you don’t control, but it doesn’t work with the default functionality, you can tell it to “Open Externally” and it will open a new tab in your browser. This is not optimal, but it’s an option.

Best practices

  1. This action’s UI should perform little to no navigation. It shouldn’t be treated as a way to show just any page.
  2. Design your UI to live in a small window that doesn’t require much, if any, scrolling, and is responsive to mobile and small displays.
  3. Make sure your URL’s server allows loading your content from your Owncast server via X-FRAME-OPTIONS and the CSP.
  4. The chat username of the person who fired this action is passed along as a URL parameter so you can pre-fill any forms for convenience. You should utilize this.
  5. The instance URL of the Owncast server that is displaying this action UI is passed along as a URL parameter so if you happen to be hosting actions for multiple servers you can know where it’s coming from. Note: You shouldn’t perform arbitrary API requests just because this parameter exists, since anybody can easily fake it.
  6. For HTML actions that include custom styling via <style> tags, you should make sure to have selectors that are as specific as possible, not colliding with any other elements in the page.
  7. For HTML actions that directly embed a <form> element, it makes sense to set target="_blank" to open the submit page in a new tab. That way your viewers won’t have to stop the stream when submitting the form.