Guidelines

Before publishing your app your should read the Homey App Store guidelines to avoid getting your app submission rejected.

The Homey community is expanding and so are the number of app developers. In order to provide each user with a consistent experience, a set of guidelines has been designed for you, as an app developer, to follow. Whether you are a beginner or experienced developer, working solo or in a large team, implementing these guidelines will ensure a speedy review process.

Before you submit your app

Ready to upload your app to the Homey App Store? We are very excited to see what you have created. We want to make sure that all Homey users have a great experience. Therefore, we will thoroughly review your app, before we can approve it.

Apps that are submitted for review for the first time need to be complete i.e. icons, images and required texts need to be present. Once we approve an app it can be released to the Homey App Store by the developer. To prevent apps in testing or prototyping stages from being released, we require that every app must meet our requirements before being published in the Homey App Store.

Before you submit your app for approval we advice to:

• Test your app for any crashes or bugs.

• Double check for any spelling errors.

• Check that your app follows the guidelines below.

• Provide Athom with the necessary devices to test your app (for Verified Developers only).

1. Design

A coherent look and feel in both the Homey App Store and Homey's various user interfaces is essential to how users experience Homey. That is why the overall appearance for each submitted app is a key factor in our review process.

Each of the following articles will explain what is expected and what is definitely not desired.

1.1. App name

A clear app name is essential for new customers to find your app and understand what it's about. In most cases, the app's name should be exactly the same as the brand name.

1. In case your app supports a specific brand, use the brand name for your app. Company names are not allowed.

2. You may not use the trademarks Homey or Athom in your app's name.

3. You may not include protocol names (Zigbee, Z-Wave, 433 MHz, Infrared etc.) in your app's name.

4. Names that are longer than 4 words are not allowed. An app name should be short and simple, one that immediately clarifies what the app does.

Do	Don't
Philips Hue	Lights by Philips Hue
tado°	Tado Gmbh

1.2. Description

The description field is a required field to provide your app with a catchy tagline to grab the user's attention. The description is shown beneath your app's name and above the readme in the App Store. In case your app supports devices by a specific brand, consider using their slogan as your description.

1. Using your app's name or repeating text from the readme in your description is not allowed.

2. The description field is not meant for an extensive text. Provide an engaging one-liner that highlights the purpose of your app. In case your app supports devices by a specific brand, consider using their slogan as your description.

3. All apps in the Homey App Store add support for something to Homey, that is why they are there. So avoid descriptions such as these:

   • "Adds support for Sonos"

   • "Integrates Philips Hue with Homey"

   • "Control your Ikea devices with the Ikea app"

What we'd like to see:

• Philips Hue - "Transform the way you experience light"

• Ikea - "Create the right atmosphere for every mood"

• Rituals - "Your home never smelled smarter"

• Heimdall - "Turn Homey into a surveillance system"

1.3. Readme

The app's readme.txt must be used to provide an engaging summary of your app's purpose. Describe why your app's integration is useful in day-to-day life.

1. Keep the text short and concise, one to two paragraphs tops. The text should be pleasant to read, so stick to single line spacing and avoid unnecessary indentations. Headers or titles are not needed.

2. In order to keep your readme short, do not list all the different features, capabilities and Flow cards available in your app. Give credit to contributors in your App Manifest instead of your readme.

3. The readme text is displayed in plain text, any Markdown format in your readme is not allowed and will not be rendered.

4. URLs in the readme are not allowed. See section URLs for more information.

5. Don't create a changelog in your readme. In case you are updating your app, use the Changelog functionality of the Homey App Store. When publishing your app, Homey will ask your 'What's new?" and a .homeychangelog.json file is automatically created in the root directory of your app. Describe your changes clearly, so your users know what has changed.

1.4. Images

Images are a great way to uplift your app's experience. Both the app and driver images are prominently visible on the Homey App Store page, so make sure they are visually compelling. Use brand images if this is possible. If you want to create custom images, keep it clean, simple and do not use a Homey or Homey logo in the images. Make sure the image is clear, well designed and recognizable for the respective brand or purpose.

1.4.1. Format & resolutions

All images must be provided in either .jpg or .png format. Each chosen image should be included in two resolutions.

Resolutions for the app image:

• Small 250 x 175

• Large 500 x 350

• XLarge 1000 x 700

Resolutions for the driver images:

• Small 75 x 75

• Large 500 x 500

• XLarge 1000 x 1000

4KB

Homey App Template.sketch.zip

archive

Homey App Store template for Sketch

1.4.2. App images

The app image should be a lively image that represents the purpose of your app. Images with big two-dimensional unicolored shapes on a monochrome or transparant background are not approved. E.g. a black shape on a white background will not look appealing in the Homey App Store.

Avoid a logo as app image:

Avoid clipart type of images:

Avoid images that contain Android or iOS app examples:

1.4.3. Driver images

In case your app has drivers, make sure to provide individual images for each driver. A driver image should have a white background and a recognizable picture of the device it supports.

Don't use the app image as a driver image.

Don't use your app icon as a driver image.

Do not use the Homey logo, name or device in any of your images.

1.5. Icons

Icons (.svg files) are used in various places and are a key element in the overall user experience. Icons are used frequently in Homey's user interfaces to represent the apps and devices paired with Homey. A picture is worth a thousand words! So let your icons do the talking.

If you do not have suitable icons for your app or drivers we can provide a handmade icon for you. You can request an icon by creating an issue in the Homey Vectors repository. Please include as much information about your app as possible and include pictures of the devices.

1.5.1. App icon

The app icon is one of the first things users will see when they search for an app. If possible avoid an icon that contains text. Be sure the brand is clearly represented or the icon is fitting to the app's purpose. Always use the full canvas, so the icon is displayed properly. If an app is created for a specific brand, use the company's brand icon. Icons are required to have a transparent background.

Don't use a driver icon as your app icon:

Don't use a background color in your icon:

1.5.2. Driver icons

Driver icons are visible once an app has been installed and the user adds a device to Homey. Each individual driver your app supports must have its own unique icon. The icon should resemble the device. When looked at from a distance the device must be recognisable.

Want to try your hand at creating your own driver icons? Here's a few things to keep in mind:

1. The canvas size should be 960x960px.

2. Always use the full canvas, so the icon is displayed properly.

3. If possible use an angle from the right side instead of front facing.

4. Make sure to use the right line width

Add dimension to your icons and use a right side angle:

Don't use driver images as an icon:

Don't re-use the app's icon for your drivers:

Don't use a background color, icons should have a transparent background:

1.6. Brand color

The property brandColor is a mandatory value which needs to be added to your App Manifest. The defined color is used as a backdrop for your icons in e.g. Flows, Add devices and the App Store.

Both your app icon and driver icons must be clearly visible against the background color. Use brand colors to complement the icons and make them more recognizable.

1.7. URLs

Offer extra help or information to your users, simply by adding a URL to your App Manifest. Each URL will be visible as a clickable link, at the lower section of your app page.

Read the App Manifest guide for more information.

Manifest

1.8. Flow

Flow is an essential part of Homey. Incorporate When-And-Then Flow cards, so that users can integrate your app in their automated home environment.

1.8.1. Titles

Flow card titles need to be short and clear, so the user instantly knows what the trigger, condition or action does. Device names should not be mentioned in the title. Don't add the When, And, Then statements to the title. Do not use parantheses in Flow titles.

	Do	Don't
When	Unknown face is detected	Netatmo Presence detected an unknown face.
And	Is !{{on|off}}	And the light is off
Then	Lock door	Going to lock the door

1.8.2. Formatted titles

Flow cards may contain arguments. To integrate an argument into the title of the Flow card the titleFormated property must be used. Make sure that the title is still straightforward and clear with the arguments incorporated.

  "title": { "en": "Run a script" },
  "titleFormatted": { "en": "Run [[Script]]" }

Example: A remote or wall switch can have multiple buttons, with several actions to trigger them. For example pressed once, twice or a long press. Instead of creating several Flow cards for all these triggers, one flow card can be created containing several arguments.

  "title": { "en": "Button was pressed" },
  "titleFormatted": { "en": "[[buttontype]] button was pressed [[scene]]" }

1.8.3. Hint

In case the function of the Flow card is not obvious use the hint property to give additional information.

  "title": { "en": "Battery state changed" },
  "hint": { "en": "This card starts a Flow when a change in the battery state is observed." }

1.9. Widget Previews

The Widget Preview is a simplified representation of your Widget. If your app includes a Widget, the preview will be displayed on the App Store page of your app as well as in the Widget picker within the Homey Mobile app. The preview should give users an idea of the Widget’s appearance without revealing too much detail. Both light and dark mode versions should be provided.

We highly recommend using our Figma Template for creating these previews. The template includes the proper color styles and shadows and will automatically generate a dark mode version. It also provides examples and ensures export in the correct dimensions (1024x1024). In addition to using the template, please keep the following guidelines in mind.

Don't use screenshots or provide over detailed designs:

• Don’t include text.

• Use simple shapes.

Use the color styles provided in the Figma template for basic elements:

• Don't use the same colors as the Widget picker background.

• Try not to use too many different colors.

• Use the shadow styles provided in the template.

Don't use a background color or image:

• Previews should have a transparent background.

1.10. Language & Translations

English is the required language for your app, however additional languages are also allowed and encouraged. For more details on implementing translations read the internationalization guide.

1. Make sure your app doesn't have any typos, language or spelling errors. Your app will be rejected if spelling errors are found.

2. Consistency in translations is vital. A partially translated app is very confusing for users. So avoid sporadic translations throughout the app. If the description is translated to a certain language, the readme should be translated to that language as well. In case you translate Flow cards, make sure to translate all Flow cards, device settings, capabilities, etc.

1.11. Dependencies

Apps may communicate to other apps using App-to-App communication to enhance an app's functionality. It is however not permitted to make one app fully dependent on another app. An app's core functionality must always work standalone.

It is also not allowed to publish an app which does not add any value by itself, but is meant to be used by other apps. In such scenarios, embed such an app's functionality directly.

1.12. Account

Your app will be published with your Athom account. A developer account name cannot contain emoji's, special characters or inappropriate language. Account names can be adjusted via accounts.athom.com

If your account has the verified developer badge, the account name should be the name of the company publishing the app. A few examples:

Bosch-Siemens Home Connect published by "Home Connect GmbH" Frient published by "frient A/S" Yale Access published by "Yale Access" Plugwise published by "Plugwise B.V."

2. Legal

2.1. Copycats

2.1.1. App

As a community developer, you are part of a community that is working towards a common goal of making home automation accessible to everyone. This means we must keep things simple. Ideally there is only one community app per brand, because too many apps with the same purpose will confuse users. So make sure your app is one of a kind - just like you.

We encourage developers to work together by sending Pull Requests to the original author and give credit where due. If your app resembles an already published app we cannot approve it. In the event that a similar app submission is absolutely necessary, please elaborate in your submission why and make sure it is clear to the end-user.

2.1.2. Code

There is a lively and open Homey community, with many developers that keep their source code open for others to view, or even contribute. Copying or using code created by fellow developers without consent is an infringement on their intellectual property.

If your code is based on source code that is not your own, always ask for permission and give credit to the original source in the app manifest. If at any point it is revealed that code has been used without consent your app will be at risk of being removed from the Homey App Store.

2.2. Explicit content

Apps with adult content (e.g. pornography) are not allowed.

2.3. Compensation

Apps that require payment for partial or all functionality are not allowed. Apps should be free of charge for all users. We encourage you to add donation options to your app.

Apps whose goal is to connect to a service that requires payment (for example a Premium-tier for a smart thermostat), and the payment happens on the integration product's end, this app can still be offered for free in the Homey App Store.

3. After app submission

Once an app has been submitted for certification, the app will be reviewed according to the various criteria mentioned in these guidelines. Athom holds the right to make the final decision if an app will be approved or removed from the Homey App Store.

3.1. Review duration

After your app heen been submitted, your submission will be reviewed. This process can take up to 2 weeks. Within this time an app can either be approved, receive feedback or we might inquire more information before proceeding with the review. If an app meets all the requirements upon submission, the review process can go much faster.

The review process for a new app created by a Verified Developer can take longer, depending on the size of the app and all its capabilities.

3.2. Testing your app (Verified Developers only)

It is imperative that an app created by a Verified Developer is of the highest quality and delivers a great user experience. To assure that these standards are met, an app created by a Verified Developer will be thoroughly tested before its approval.

In order for the app to be tested by our testing team, make sure to provide a few sample devices prior of your submission. For cloud apps a demo account can be an option as well. If devices are to large or not available consult with us to determine how we can proceed with the review.

An app will be tested not only on correct functionality, but also the user experience and usability are of high importance. So make sure that:

• The pairing instructions for all drivers are accurate and clear.

• Error messages are understandable.

• Capabilities are functioning correctly.

• Flow cards are available, intuitive and understandable.

• Driver settings are usable and understandable.

• Every aspect of the app has been accurately translated.

To ensure a smooth approval process, we expect an app has been thoroughly tested before it is submitted for certification. Once the app has been published to Test in the Developer Tools a testing URL will be available which can be shared with beta testers.

https://homey.app/en-us/app/APP.ID/test/ replace with your apps own App ID

Apps with a history of high quality submissions will often experience a faster review process.

3.3. Feedback

Any findings or feedback during the review process will be shared with the developer and is expected to be implemented.

3.4. Removal

In the event that your app is no longer compatible with Homey, functioning correctly or actively maintained it may be removed from the Homey App Store.