Skip to content

Winside API Reference

Jump to bottom
Spatchy edited this page Mar 30, 2023 · 6 revisions

⯇Previous: Injectable Content Overview | Next: Expose Addons Reference⯈

Winside API Overview

The Winside API is a collection of functions exposed to a Winsert on the window.WinsideAPI object. These functions allow for special functionality for Winserts to perform actions on a user's device outside of the Winsert's own sandbox. All the endpoints are asynchronous and hence return promises so they must be awaited or .then used to get the actual result.

⚠️ Important: From Winside version 2023.02 onwards, some API endpoints now require requesting permission from the user before they can be used. See the requestPermission endpoint for details.

Reference

getAppVersion Introduced:2023.02

window.WinsideAPI.getAppVersion()

Will return the version of Winside being used

  • Required Permissions: none
  • Params: none
  • Returns: <string> | The currently running version of Winside (i.e. "2023.02")

openLinkInBrowser Introduced:2023.01

window.WinsideAPI.openLinkInBrowser(url)

Will open the given url in the user's default browser. (The sidebar will not be closed)

  • Required Permissions: none
  • Params:
    • url: <string> | The URI the browser will navigate to.
  • Returns: none

requestPermission Introduced:2023.02

window.WinsideAPI.requestPermission(winsertId, permission)

From Winside version 2023.02 onwards, some API endpoints now require requesting permission from the user before they can be used. Calling this endpoint will prompt the user to either grant or deny the permission.

  • Required Permissions: none
  • Params:
    • winsertId: <string> | The Winsert's winsertId
    • permission: <string> | The name of the permission to request (Check the Required Permissions section of the endpoint you wish to use)
  • Returns: <boolean> | True if the user granted the permission, false otherwise

keepOpenInBackground Introduced:2023.02

window.WinsideAPI.keepOpenInBackground(winsertId)

Tell Winside to keep the rendered Winsert running in the background when the sidebar is closed

  • Required Permissions:
    • keepOpenInBackground
  • Params:
    • winsertId: <string> | The Winsert's winsertId
  • Returns: <undefined> OR <Error> | returns nothing if the operation succeeds or an error if adequate permissions are not granted

cancelKeepOpenInBackground Introduced:2023.02

window.WinsideAPI.cancelKeepOpenInBackground(winsertId, killIfInBackground)

Tell Winside to no longer keep the Winsert running in the background when the sidebar is closed. The Winsert can be killed immediately or when next opened and closed from the sidebar.

  • Required Permissions:
    • keepOpenInBackground
  • Params:
    • winsertId: <string> | The Winsert's winsertId
    • killIfInBackground: <boolean (default: false)> | True if the process should be killed immediately, otherwise it will be killed next time it is closed from the sidebar
  • Returns: <undefined> OR <Error> | returns nothing if the operation succeeds or an error if adequate permissions are not granted

sendNotification Introduced:2023.02

window.WinsideAPI.sendNotification(winsertId, title, body)

Send a desktop notification via Windows Action Center

Note: As of 2023.3.0 HTML5 web notifications are now intercepted and treated as if they called this endpoint. This means they will only be shown if the sendNotifications permission is granted.

  • Required Permissions:
    • sendNotifications
  • Params:
    • winsertId: <string> | The Winsert's winsertId
    • title: <string> | The title to be displayed on the notification
    • body: <string> | The main text to be displayed on the notification
  • Returns: <undefined> OR <Error> | returns nothing if the operation succeeds or an error if adequate permissions are not granted

closeSidebar Removed:2023.02

⯇Previous: Injectable Content Overview | Next: Expose Addons Reference⯈

Previous Versions of This Page

2023.01

Clone this wiki locally