App Store

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 review your app, before it becomes available in the App Store. To make sure that the review process goes smoothly and you make the most out of your App Store page, we have set up the following guidelines to help you on your way.

1. Design Guidelines

1.1. App Name

Naming your app is an important step. If you want to successfully reach your potential users, make sure you choose a simple name that hints at what your app does. Is your app created to support devices of a specific brand? Consider using the brand’s name as the name of your app, not to be confused with the company name of that brand.

The use of ‘Homey’ in your app name is not allowed.

1.2. Icons

Icons are used in various places to improve user experience. After all, a picture is worth a thousand words! So let your icons do the talking.

Your app’s icon is one of the first things users will see when they search for your app. If possible avoid an icon that contains text. Be sure the brand is clearly represented or the icon is fitting to your app’s purpose. Always use the full canvas, so your icon is displayed properly.

Example app icon bad Example app icon good

If your app is created for a specific brand, check out the company’s brand icon and use this.

Equally important are the icons for the devices your app supports. The icon should resemble the device. When you look at it from a distance you should recognize the device.

details-bad.jpg details-good.jpg

Check out the Icons guidelines for more information.

1.3. Subtitle

Grab the user's attention, with a quick one-liner. Use the Description field in your App Manifest to state your subtitle. The subtitle will be displayed above the readme in the Homey Apps Store. This field is not meant for a long extensive description. Provide an engaging subtitle that highlights the features and functionality of your app.

Make the most of this field, because it’s one of the first things users will see. Avoid repeating information already given in the app’s readme or just stating your app’s name. And because it is a subtitle there is no need to use punctuation marks to end the sentence, so leave the stops and screamers(!) off.

What we’d like to see:

  • Philips - “Transform the way you experience light”
  • Ikea - “Create the right atmosphere for every mood”
  • Rituals - “Your home never smelled smarter”
  • Heimdall - “Turn your Homey into a surveillance system”

Stay away from stating the obvious. All apps in the Homey App Store add support to talk with Homey, that is why they are there. So avoid subtitles like these:

  • “Control your Ikea devices with the Ikea app”
  • “Adds support for Sonos “
  • “Integrates Philips hue with Homey”
  • “Fibaro”

1.4. Readme

Use your app’s readme to provide an engaging description of your app’s purpose, this will be shown as plain text in the App Store. Let users know what your app can do for them. Sell that baby!

Always keep the user in mind. Make your description short and concise, preferably one paragraph. Describe some of the possibilities of your app without going to deep into technicalities.

It’s not necessary to add a header to your readme or use your app name as a title, the app name will sit proudly at the top of your App Store page.

Perhaps you want to add a list with all the supported devices, try to avoid this, supported devices will be visible on the app’s page in the “Supported devices” section.

Have additional information to share with the users? Why not use a Homey Community topic to offer helpful tips for setup or troubleshooting and more. See 1.10. URLs for more information on how to do this.

Avoid these commonly made mistakes:

  • Creating a lengthy readme
  • Using markdown format
  • Adding of URLs
  • Listing what’s new (see section 5.1 of the App Development Guidelines)

If your app supports languages other than English, you can add a translated README.<language_code>.txt file (e.g. README.nl.txt).

1.5. App images

Display your app with images in the App Store. It’s the first thing users will see when they visit your app page, so make sure it’s a visually compelling image. Use brand images if this is possible.

However, if you want to use a custom image to go along with your app, keep it clean and simple. make sure the images are clear, not pixelated, well designed and recognizable for the respective brand or app. Avoid using the Homey logo in your images. Images are not allowed to have a white or transparent background.

To make your images come accross well, avoid big unicolored shapes on a monochromatic background. For more information on images in Homey check Images.

There are two sizes required:

  • Large 500 x 350 px /assets/images/large.png
  • Small 250 x 175 px /assets/images/small.png

Images must be provided in either .jpg or .png format. Both the large and small app image should be identical.

large.jpg large.jpg

1.6. Driver images

If you have a driver, you should supply driver images. A driver image should have a white background and fill most of the image. Avoid using the same images as used for the App.

  • Large 500 x 500 px /drivers/<driver_id>/assets/images/large.png
  • Small 75 x 75 px /drivers/<driver_id>/assets/images/small.png

Images must be provided in either .jpg or .png format. Both the large and small driver image should be identical.

large small

1.7. Flows

To create the optimal Homey experience Flows are imperative. That's why we encourage you to incorporate When-And-Then Flow cards in your app.

Keep them short and clear. Use the hint field to give further explanation, if necessary. Having trouble creating your Flow card labels? A helpful trick is to fill in the blanks in the following sentences:

  • When... (device name) _____ --> (trigger) _____
  • And... (device name) _____ --> (condition) _____
  • Then... (device name) _____ --> (action) _____

The trigger/condition/action is likely a good descriptive Flow card title.

For example:

  • When... Netatmo Presence --> Unknown face is detected
  • And... Philips Hue bulb --> Is off
  • Then... Nuki lock --> Lock door

1.8. Tag(s) your it!

Now that you have created your app, it’s essential that users will find it in the Homey App Store. That’s where tags come in handy. To make it easier for users to find your app, you can add a translated array of tags to the App Manifest. This will make your app easily searchable for users, if you add the right tags. For example: Philips Hue, Smart Bulbs.

When adding your tags avoid the following :

  • Using both the singular and plural form of one word
  • Names of categories or the word “app”
  • Duplicate words
  • Special characters — such as # or @

/app.json

{
  "id": "com.nest",
  "name": {
    "en": "Nest"
  },
  "tags": {
    "en": ["learning thermostat"]
  }
}

1.9. Mention contributors

We always encourage collaboration within the community, so give credit where credit is due! Perhaps you have had some input whilst creating your awesome app? Or maybe you’ve had some help translating your app to another language? Your users will really appreciate all your efforts into creating the best app for them. So give a shout out to those that helped you do it.

Because only one user can publish to the App Store, you can add multiple authors in your App's manifest. Their names will be visible on the App Store page as well. Have a look at the App Manifest for more information.

1.10. URLs

There is only so much information that can be added to your Homey App Store page, however there are other ways to offer a little extra help or information to your users. Simply by adding a URL to your App Manifest.

The following URLs can be added and will be visible as a clickable link on your app page.

  • Homepage: Share your company, brand or personal page with users to give them some more insight.

  • Support: Sometimes your users need some help or might have some questions about your app. Consider offering them a bit of support, just in case they need it. Add a URL or e-mail adress to the app manifest. If you have a Homey verified app, a support URL is mandatory.

  • Bugs: However hard we all try, bugs sometimes happen. Your users can come across an issue in your app. Provide them with a bug URL, so they can quickly share their findings with you. An example would be a URL to your apps Github issues tracker.

  • Source: Allow others to view your code and maybe even submit a Pull Request. If you want to you can add a link to your source code.

  • Donations: Perhaps some users want to show their appreciation for your hard work in the form of a small contribution. Consider adding a donation link. A donate button is not allowed when an app is based on a fork.

  • Homey Community Topic: Join the community! A Homey Community Topic is a great place to share additional information about your app with your users and fellow developers. Add your topic ID to your app manifest.

For implementation view the App Manifest

2. Submission guidelines

A few submission guidelines have been established to keep the community working together in unison.

2.1. App Permissions

Is your app using the homey:manager:api permission? That's alright! However it is not allowed to use it so that an external devices can control Homey.

2.2. App License

  • Adding a LICENSE file helps other developers understand if they can copy your app, modify it, etc.
  • As a rule of thumb, Athom will look at the submission process and if an app has been forked or is a duplicate, the license file of the original repository will be leading.

2.3. Make that the copycat wise

As a community developer, you are part of a community where we are working towards the common goal of making home automation accessible to everyone. This means we must keep things simple, so ideally there is only one 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 existing app we cannot approve it. However in the event where a similar app submission is absolutely necessary, please elaborate in your submission why, and make sure it is clear to the end-user.

2.4. Contribute to an Athom app

Several apps in the Homey App Store are created by Athom. Some of these Athom apps are open sourced projects. These projects serve as an example of how we would like the code for Homey Apps to be constructed.

Even though these apps are open sourced, we discourage developers to put in Pull Requests on their own. In case you want to contribute to an existing Athom app, first put in a request. We want to prevent developers from putting in a lot of hard work, which later on will not be approved.

If we have given you the go ahead you can put in a pull request, which we will review. During the review process the code quality is important. It is up to us to maintain the app therefore we set a high standard in order to ensure maintainability. Add a clear commit message or pull request description to make it clear for the reviewer. Pull Requests made without our consent will not be reviewed.

2.5. Explicit content

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

Athom holds the right to make the final descicion if an app will be approved.