Homey Cloud
Everything you need to know to make your apps compatible with Homey Cloud.
Last updated
Everything you need to know to make your apps compatible with Homey Cloud.
Last updated
The Homey Apps SDK is engineered to support both Homey Pro and Homey Cloud. Whether you developed your app for Homey Cloud or Homey Pro, it likely already works on both platforms. However there are some important differences that you should be aware of. This page will explain those differences and help you make sure your app offers the best experience to users whether they use Homey Cloud or Homey Pro.
You should not use "Homey Cloud" in user facing texts. Our products are Homey and Homey Pro. Homey Cloud is a term that is only used for developers to distinguish on what platform apps are running.
It is important to know how your apps will be run in Homey Cloud. On Homey Cloud your app is responsible for more than one user at a time. We refer to this as multi-tenancy, which means that several app instances are created inside the same Node.JS process. In addition if your app has many users it will get started on several servers to spread the load.
Despite Homey Cloud running apps in the cloud it is still possibly to easily test your app during development. If you run homey app run
while having a Cloud Homey selected, the Homey CLI will automatically guide you to install all the required tools. It will then run the app on your computer and connect it to Homey Cloud.
Because Homey Cloud is offered for a mainstream audience, we want to ensure every app is of great quality. To assist with this, we offer code-level support and in-depth app reviews as part of the Homey Verified Developer subscription. This subscription is required to publish your app to the App Store when targeting "platforms": [ "cloud" ]
or "platforms": [ "local", "cloud" ]
.
Only official app integrations will be approved. This means an app submitted by a brand or submitted by a third party developer commissioned by said brand.
Publishing apps for Homey Pro does not require a subscription and will always remain free.
You can check whether your app passes some of the additional validation by running:
To indicate that your app supports running on Homey Cloud you will need to add the platforms
flag to your App, Driver and Flow manifests.
Only SDK v3 is supported on Homey Cloud so before you start making your app compatible with Homey Cloud, make sure you are using SDK v3.
Each individual driver can list the supported platforms and the wireless connectivity that is used with the platforms
and connectivity
properties:
The available options for connectivity
are:
Read the App Store Guidelines for more information.
In order to handle multi-tenancy for Homey Cloud, your app should not use global variables. Because the global scope is shared the values of global variables may be unpredictable.
This is a contrived example of what you should not do:
Instead you should set properties on your App
, Driver
or Device
instances:
Multi-tenancy also means that your app should cleanup when an instance is destroyed. For example if a user removes an app. On Homey Pro that causes the entire app process to be killed but on Homey Cloud you need to put in some extra care to make sure all your resources are correctly released.
In order to make this easier the Apps SDK as several "un-init" methods: App#onUninit()
, Driver#onUninit()
, and Device#onUninit()
. These methods will be called when your app is destroyed so you can perform cleanup in them. For example:
Another case in which you need to take care to clean up when your app is uninstalled would be timers like setInterval()
and setTimeout()
. You should not call these directly, instead you should use this.homey.setInterval()
or this.homey.setTimeout()
. These act exactly the same as their regular counterparts but will automatically be cleared when your app is destroyed.
Make sure you don't do this:
Instead write code like this:
On Homey Cloud unhandled promise rejections will cause the app to crash. Unhandled promise rejections can cause memory leaks and may indicate that your app is not correctly handling errors. If errors do not matter you can, in most cases, simply log the error using: .catch(this.error);
This behaviour is about to be standard in Node.JS and is therefore also coming to Homey Pro in the near future.
An example of this is Device#setCapabilityValue()
which returns a promise. In order to prevent unhandled promise rejections you should add .catch(this.error)
.
Make sure you don't do this:
Instead write code like this:
Homey Cloud apps are not allowed to do everything that apps on Homey Pro are allowed to do. The following Apps SDK features are not supported on Homey Cloud:
Homey Cloud does not have support for App Web APIs. While this means that you cannot expose a complete REST API you can still receive Webhook updates. Read the Webhooks documentation to learn more.
App-to-app communication is usually pretty tricky for a user to setup and may break due to app changes. Because of this it is not supported on Homey Cloud. This means that apps that run on Homey Cloud cannot have homey:app:<appId>
permissions. Likewise the homey:manager:api
permission that allowed an app to use ManagerApi and the Homey Web API is not allowed.
Homey Bridge does not support local Wi-Fi connections, therefore mDNS, SSDP and MAC discovery are not supported.
Obviously this means that ManagerCloud#getLocalAddress()
is also not supported on Homey Cloud.
To simplify the user experience, custom app settings views are not supported on Homey Cloud.
Any information your app might need to function should be asked for when pairing a device. If information needs to be updated you can use the "re-pair" pairing views so a users Flows don't become broken. Read the Custom Pairing Views documentation for more information.
On Homey Pro, apps are sandboxed and chroot'ed. On Homey Cloud, apps are run in a Docker container.
This means that the root-path /
is different. On Homey Pro, /
is your app's directory, and on Homey Cloud, /
is the Linux root.
To ensure your app works on both platforms, always require files relatively, e.g. require('./assets/foo.js')
or path.join(__dirname, 'myfile.svg')
.
Because Homey Cloud is targeted at a broader audience not all the types of apps that are available on Homey Pro are going to be approved for Homey Cloud.
Apps that add Drivers for a brand of smart home devices are very welcome on Homey Cloud. However apps that add advanced functionality that can only be used in combination with other apps are going to be rejected.
Generally these kinds of apps are found in the "Tools" category on the Homey Apps Store. Most of these apps won't work on Homey Cloud because the homey:manager:api
permission is not allowed to be used.
If you are a verified developer and are questioning whether your app idea will be allowed to be published on Homey Cloud be sure to get in touch with the developer support.
Value
Description
lan
This is not possible with Homey Bridge, see SDK difference between Homey Pro and Homey Cloud.
cloud
This means that your Driver uses OAuth or Webhooks to connect to a cloud service.
ble
Use if your Driver connects to Bluetooth Low Energy devices.
zwave
Use if your Driver implements a Z-Wave device.
zigbee
Use if your Driver implements a Zigbee device.
infrared
Use if your Driver sends infrared signals.
rf433
Use if your Driver sends 433Mhz signals.
rf868
This is not possible with Homey Bridge.