Homey Apps SDK
📖 Apps SDK Reference🌍 Web API🛠 Developer Tools
  • Welcome to the Apps SDK documentation 👋
  • The Basics
    • Getting Started
      • Homey CLI
    • App
      • Manifest
      • Internationalization
      • Permissions
      • Persistent Storage
    • Drivers & Devices
      • Pairing
        • System Views
          • Devices List
          • Add Devices
          • OAuth2 Login
          • Credentials Login
          • Pincode
          • Loading
          • Done
        • Custom Views
      • Capabilities
      • Energy
      • Settings
      • Best practices
        • Lights
        • Window coverings
        • Battery status
    • Flow
      • Arguments
      • Tokens
    • Widgets
      • Settings
      • Styling
      • Debugging
  • Wireless
    • Wi-Fi
      • Discovery
    • Bluetooth LE
    • Z-Wave
    • Zigbee
    • 433 MHz
    • Infrared
    • Matter
  • Cloud
    • OAuth2
    • Webhooks
  • App Store
    • Publishing
    • Guidelines
    • Verified Developer
    • Updating
  • Advanced
    • Custom Views
      • App Settings
      • Custom Pairing Views
      • HTML & CSS Styling
    • Web API
    • Images
    • LED Ring
    • Homey Compose
  • Guides
    • Homey Cloud
    • Breaking Changes
    • Tools
      • Bluetooth LE
      • Zigbee
      • TypeScript
    • Using ESM in Homey Apps
  • Upgrade Guides
    • Homey v6.0.0
    • Upgrading to SDK v3
      • Zigbee Apps
    • Device Capabilities
Powered by GitBook
On this page
  • Properties
  • Additional properties
  • Platform Local Required Features
  • Contributors
  • Contributing
  • Bugs
  • Homey Community Topic
  • Source
  • Homepage
  • Support

Was this helpful?

  1. The Basics
  2. App

Manifest

The basic properties of the App Manifest.

The App Manifest contains all metadata for your app. It specifies Flow Cards, Drivers, etc.

/.homeycompose/app.json
{
  "id": "my.company.example",
  "version": "1.0.0",
  "compatibility": ">=5.0.0",
  "platforms": ["local", "cloud"],
  "sdk": 3,
  "brandColor": "#FF0000",
  "name": { "en": "My App" },
  "description": { "en": "Adds support for Example devices." },
  "category": "lights",
  "tags": { "en": ["example"] },
  "images": {
    "small": "/assets/images/small.png",
    "large": "/assets/images/large.png",
    "xlarge": "/assets/images/xlarge.png"
  },
  "permissions": ["homey:manager:api"]
  "author": {
    "email": "john@doe.com",
    "name": "John Doe"
  }
}

Properties

Name

Description

id

The ID of your app. This is a reversed domain-name.

version

compatibility

platforms

sdk

The SDK level of your app. Should be 3.

brandColor

A HEX string for the app's brand color. The brand color is not allowed to be very bright.

name

description

category

A string with the Homey App Store category. Allowed categories are: lights, video, music, appliances, security, climate, tools, internet, localization, energy.

tags

images

An object containing two paths, small and large, and optionally a third: xlarge.

permissions

author

An object indicating the author of the app. The field author.name is required, author.email is optional.

Additional properties

The following app manifest properties are optional but can be used to document extra information about your app. Most of this information will be presented to users in the Homey App Store.

Platform Local Required Features

An array of required features (nfc, ledring, speaker or matter) for platform local. Adding a required feature will make the app uninstallable on Homey Pros that do not have all the listed features. So only use this when the app will only function with the respective feature.

{
  "id": "com.athom.example",
  // ...
  "platformLocalRequiredFeatures": [ "nfc", "speaker", "ledring" ]
}

Contributors

An object with keys developers and translators. Each object in the developers or translators array must contain a name property.

/.homeycompose/app.json
{
  "id": "com.athom.example",
  // ...
  "contributors": {
    "developers": [
      {
        "name": "Alice the Wild"
      }
    ],
    "translators": [
      {
        "name": "Klemens Kohlmann"
      }
    ]
  }
}

Contributing

Perhaps some users want to show their appreciation for your hard work in the form of a small donation.

When adding one or more donation options to your app's manifest, a Donate button will appear on your app's page.

Donate buttons are only visible for non-verified developers.

/.homeycompose/app.json
{
  "id": "com.athom.example",
  // ...
  "contributing": {
    "donate": {
      "paypal": {
        // Will link to https://paypal.me/my_paypal_username
        "username": "my_paypal_username"
      },
      "bunq": {
        // Will link to https://bunq.me/my_bunq_username
        "username": "my_bunq_username"
       },
       "patreon": {
         // Will link to https://www.patreon.com/my_patreon_username
         "username": "my_patreon_username"
       },
       "githubSponsors": {
         // Will link to https://github.com/sponsors/my_github_username
         "username": "my_github_username"
       }
    }
  }
}

Bugs

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 object with a property url that contains a link to your public bug/issue tracker.

/.homeycompose/app.json
{
  "id": "com.athom.example",
  // ...
  "bugs": {
    "url": "https://bitbucket.org/athom/com.athom.myapp/issues"
  }
}

Homey Community Topic

/.homeycompose/app.json
{
  "id": "com.athom.example",
  // ...
  "homeyCommunityTopicId": 1234
}

Source

If you would like to, you can add a link to your source code to allow others to view your code and maybe even submit a Pull Request. A string, starting with https://.

/.homeycompose/app.json
{
  "id": "com.athom.example",
  // ...
  "source": "https://github.com/athombv/com.athom.myapp"
}

Homepage

Share your company, brand or personal page with users to give them some more insight. A string, starting with https://.

/.homeycompose/app.json
{
  "id": "com.athom.example",
  // ...
  "homepage": "https://homey.app"
}

Support

Sometimes your users need some help or might have some questions about your app. Consider offering them support, just in case they need it. Add a URL or e-mail address to the app manifest. A support URL is mandatory for Verified Developers. A string, starting with https:// or mailto:.

/.homeycompose/app.json
{
  "id": "com.athom.example",
  // ...
  "support": "mailto:support@homey.app"
}
PreviousAppNextInternationalization

Last updated 7 months ago

Was this helpful?

A of your app. Note that pre-release versions (e.g. 1.0.0-rc.1) are not allowed.

A indicating a range of Homey versions your app is compatible with. Use at least "compatibility": ">=5.0.0" (larger or equal than v5.0.0).

An array containing the app's supported platforms. Read the guide for more information.

A with the name of your app.

A with the description (oneliner) of your app.

A with searchable tags for the App Store.

An array of .

The is a great place to share additional information about your app with your users and fellow developers. When the ID of the topic is provided, this shows a link on the App Store. You can get the ID from the topic's URL.

Homey Community
Semantic Version
Semantic Version
Homey Cloud
translation object
translation object
translation object
Permissions