App Manifest

File structure

The file structure of your app looks as follows.

com.athom.example
├── APPSTORE.md
├── README.md
├── api.js
├── app.js
├── app.json
├── assets
│   ├── icon.svg
│   └── images
│       ├── large.png
│       └── small.png
├── drivers
│   └── my_driver
│       ├── assets
│       │   ├── icon.svg
│       │   └── images
│       │       ├── large.png
│       │       └── small.png
│       ├── device.js
│       └── driver.js
├── env.json
├── locales
│   ├── en.json
│   └── nl.json
└── settings
    └── index.html

Click a file in the tree to learn more about it.

Manifest file

The App Manifest, a JSON file called /app.json, contains all metadata for your app. It specifies Flow Cards, Drivers, etc.

Example

Most documentation specify their own properties for the /app.json file. An example file is shown below.

/app.json

{
    "id": "com.athom.myapp",
    "version": "1.0.0",
    "compatibility": "1.x >=1.5.0",
    "sdk": 2,
    "brandColor": "#FF0000",
    "name": {
        "en": "My App",
        "nl": "Mijn App"
    },
    "description": {
        "en": "Adds support for certain devices.",
        "nl": "Voegt ondersteuning toe voor bepaalde apparaten."
    },
    "category": "appliances",
    "tags": {
        "en": [ "example" ],
        "nl": [ "voorbeeld" ]
    },
    "images": {
        "large": "/assets/images/large.png",
        "small": "/assets/images/small.png"
    },
    "permissions": [
        "homey:manager:speech-output",
        "homey:manager:ledring"
    ],
    "author": {
        "email": "john@doe.com",
        "name": "John Doe"
    },
    "contributors": {
        "developers": [
            {
                "name": "Alice the Wild",
                "email": "alicewild@gmail.com"
            }
        ]
    },
    "contributing": {
        "donate": {
            "paypal": {
                "username": "my_paypal.me_username"
            }
        }
    },
    "bugs": {
        "url": "https://bitbucket.org/athom/com.athom.myapp/issues"
    },
    "homeyCommunityTopicId": 1234,
    "signals": {
        // ...
    },
    "flow": {
        "actions": [
            {
                "id": "my_action",
                "title": {
                    "en": "My Action",
                    "nl": "Mijn Actie"
                }
            }
        ]
    },
    "drivers": [
        {
            "id": "my_driver",
            "class": "socket",
            "capabilities": [ "onoff", "dim" ],
            "name": {
                "en": "My Driver",
                "nl": "Mijn Driver"
            },
            "images": {
                "large": "/drivers/my_driver/assets/images/large.png",
                "small": "/drivers/my_driver/assets/images/small.png"
            },
            "gtin": [ "123456789111" ],
        }
    ],
    "capabilities": {
        // ...
    },
    "speech": {
        // ...
    },
    "speechExamples": {
        "en" : [
            // ...
        ]
    },
    "screensavers": [
        {
            "name": "my_screensaver",
            "title": {
                "en": "My Screensaver"
            }
        }
    ]
}

Properties

id

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

version

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

compatibility

A Semantic Version indicating a range of Homey versions your app is compatible with. For Apps with "sdk": 2, use at least "compatibility": "1.x >=1.5.0" (1.x range and larger or equal than 1.5.0).

sdk

The SDK level of your app. Should be 2.

brandColor

A HEX string for the app's brand color. Colors that are too bright will not be validated. If no brandColor is provided, an unique app color will be automatically generated.

name

An i18n-object object with the name of your app.

description

An i18n-object object with the description (oneliner) of your app.

category

A string or array of App Store categories. When provided an array, the first item will be used to show in the App Store's frontpage.

Allowed categories are: lights, video, music, appliances, security, climate, tools, internet, localization, energy

tags

An i18n-object object with searchable tags for the App Store.

images

An object containing two paths, small and large.

permissions

An array of Permissions.

author

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

contributors

An object with developers, following the same format as author.

contributing

An object to show people how to contribute to app development. Only donate.paypal is supported for now, which will show a PayPal button in the sidebar.

bugs

An object with a property url to link to. This is rarely necessary, only when using a non-common Git system.

homeyCommunityTopicId

A number with the discussion ID of the Homey Community. When provided, this shows a link on the App Store. Get the discussion ID from the topic's URL.

signals

See Signals.

flow

See Flow.

drivers

See Drivers.

capabilities

See Capabilities.

speech

See Speech.

speechExamples

See Speech.

screensavers

See LED Ring.