add documentation site with markdown rendering (M12)
This commit is contained in:
341
portal/internal/web/docs/api/manifest.md
Normal file
341
portal/internal/web/docs/api/manifest.md
Normal file
@@ -0,0 +1,341 @@
|
||||
# Manifest Reference
|
||||
|
||||
Every Mosis app requires a `manifest.json` file in the root of the package. This file describes your app and its requirements.
|
||||
|
||||
## Complete Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "com.example.myapp",
|
||||
"name": "My App",
|
||||
"version": "1.0.0",
|
||||
"version_code": 1,
|
||||
"entry": "assets/main.rml",
|
||||
"permissions": [],
|
||||
"min_mosis_version": "1.0.0",
|
||||
"author": {
|
||||
"name": "Developer Name",
|
||||
"email": "dev@example.com",
|
||||
"url": "https://example.com"
|
||||
},
|
||||
"icons": {
|
||||
"32": "icons/icon-32.png",
|
||||
"64": "icons/icon-64.png",
|
||||
"128": "icons/icon-128.png"
|
||||
},
|
||||
"description": "A short description of your app",
|
||||
"category": "utilities",
|
||||
"screenshots": [
|
||||
"screenshots/1.png",
|
||||
"screenshots/2.png"
|
||||
],
|
||||
"locales": {
|
||||
"default": "en",
|
||||
"supported": ["en", "es", "fr"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Required Fields
|
||||
|
||||
### id
|
||||
|
||||
**Type:** `string`
|
||||
|
||||
Unique package identifier in reverse domain notation. Must match the ID registered in the developer portal.
|
||||
|
||||
```json
|
||||
"id": "com.yourcompany.appname"
|
||||
```
|
||||
|
||||
Rules:
|
||||
- Lowercase letters, numbers, and periods only
|
||||
- Must have at least two segments (e.g., `com.app`)
|
||||
- Maximum 255 characters
|
||||
- Cannot start or end with a period
|
||||
|
||||
### name
|
||||
|
||||
**Type:** `string`
|
||||
|
||||
Display name shown to users. Maximum 50 characters.
|
||||
|
||||
```json
|
||||
"name": "My Awesome App"
|
||||
```
|
||||
|
||||
### version
|
||||
|
||||
**Type:** `string`
|
||||
|
||||
Human-readable version string following semantic versioning (MAJOR.MINOR.PATCH).
|
||||
|
||||
```json
|
||||
"version": "1.0.0"
|
||||
"version": "2.1.3-beta"
|
||||
```
|
||||
|
||||
### version_code
|
||||
|
||||
**Type:** `integer`
|
||||
|
||||
Numeric version code that must increase with each release. Used to determine if an update is available.
|
||||
|
||||
```json
|
||||
"version_code": 1
|
||||
```
|
||||
|
||||
Rules:
|
||||
- Must be a positive integer
|
||||
- Must be greater than all previously published versions
|
||||
- Maximum value: 2147483647
|
||||
|
||||
### entry
|
||||
|
||||
**Type:** `string`
|
||||
|
||||
Path to the main RML file, relative to package root.
|
||||
|
||||
```json
|
||||
"entry": "assets/main.rml"
|
||||
```
|
||||
|
||||
### author
|
||||
|
||||
**Type:** `object`
|
||||
|
||||
Information about the app developer.
|
||||
|
||||
```json
|
||||
"author": {
|
||||
"name": "Developer Name",
|
||||
"email": "dev@example.com",
|
||||
"url": "https://example.com"
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `name` | string | Yes | Developer or company name |
|
||||
| `email` | string | Yes | Contact email |
|
||||
| `url` | string | No | Website URL |
|
||||
|
||||
### icons
|
||||
|
||||
**Type:** `object`
|
||||
|
||||
App icons at various sizes. At minimum, provide a 128px icon.
|
||||
|
||||
```json
|
||||
"icons": {
|
||||
"32": "icons/icon-32.png",
|
||||
"64": "icons/icon-64.png",
|
||||
"128": "icons/icon-128.png"
|
||||
}
|
||||
```
|
||||
|
||||
Supported sizes: 32, 64, 128, 256, 512
|
||||
|
||||
Requirements:
|
||||
- PNG format recommended
|
||||
- Square aspect ratio
|
||||
- No transparency on edges (for proper display)
|
||||
|
||||
## Optional Fields
|
||||
|
||||
### description
|
||||
|
||||
**Type:** `string`
|
||||
|
||||
Short description shown in app listings. Maximum 200 characters.
|
||||
|
||||
```json
|
||||
"description": "A simple calculator for everyday math."
|
||||
```
|
||||
|
||||
### permissions
|
||||
|
||||
**Type:** `array<string>`
|
||||
|
||||
List of permissions your app requires. Apps cannot access restricted features without declaring permissions.
|
||||
|
||||
```json
|
||||
"permissions": ["storage", "network"]
|
||||
```
|
||||
|
||||
See [Permissions](#permissions-reference) below.
|
||||
|
||||
### min_mosis_version
|
||||
|
||||
**Type:** `string`
|
||||
|
||||
Minimum Mosis version required to run this app.
|
||||
|
||||
```json
|
||||
"min_mosis_version": "1.0.0"
|
||||
```
|
||||
|
||||
If omitted, defaults to `"1.0.0"`.
|
||||
|
||||
### category
|
||||
|
||||
**Type:** `string`
|
||||
|
||||
App store category for discovery.
|
||||
|
||||
```json
|
||||
"category": "productivity"
|
||||
```
|
||||
|
||||
Valid categories:
|
||||
- `games`
|
||||
- `entertainment`
|
||||
- `productivity`
|
||||
- `utilities`
|
||||
- `social`
|
||||
- `communication`
|
||||
- `lifestyle`
|
||||
- `education`
|
||||
- `health`
|
||||
- `finance`
|
||||
- `news`
|
||||
- `other`
|
||||
|
||||
### screenshots
|
||||
|
||||
**Type:** `array<string>`
|
||||
|
||||
Paths to screenshot images for app store listing.
|
||||
|
||||
```json
|
||||
"screenshots": [
|
||||
"screenshots/home.png",
|
||||
"screenshots/settings.png",
|
||||
"screenshots/detail.png"
|
||||
]
|
||||
```
|
||||
|
||||
Requirements:
|
||||
- PNG format
|
||||
- 1080x1920 (9:16 portrait) recommended
|
||||
- Maximum 5 screenshots
|
||||
|
||||
### locales
|
||||
|
||||
**Type:** `object`
|
||||
|
||||
Internationalization configuration.
|
||||
|
||||
```json
|
||||
"locales": {
|
||||
"default": "en",
|
||||
"supported": ["en", "es", "fr", "de", "ja"]
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `default` | string | Default locale code |
|
||||
| `supported` | array | List of supported locale codes |
|
||||
|
||||
Locale files should be placed in `locales/{code}.json`.
|
||||
|
||||
## Permissions Reference
|
||||
|
||||
| Permission | Description | Example Use |
|
||||
|------------|-------------|-------------|
|
||||
| `storage` | Persist data locally | Save user preferences |
|
||||
| `network` | Make HTTP requests | Fetch remote data |
|
||||
| `clipboard` | Read/write clipboard | Copy text |
|
||||
| `notifications` | Show notifications | Reminders |
|
||||
| `camera` | Access device camera | Photo capture |
|
||||
| `location` | Get device location | Maps, weather |
|
||||
| `contacts` | Read contacts | Contact picker |
|
||||
| `microphone` | Record audio | Voice notes |
|
||||
|
||||
### Permission Declaration
|
||||
|
||||
```json
|
||||
"permissions": [
|
||||
"storage",
|
||||
"network"
|
||||
]
|
||||
```
|
||||
|
||||
Users are informed of permissions before installing. Request only what you need.
|
||||
|
||||
## Validation
|
||||
|
||||
The package builder validates your manifest. Common errors:
|
||||
|
||||
| Error | Cause | Solution |
|
||||
|-------|-------|----------|
|
||||
| `Invalid package ID` | ID doesn't match pattern | Use `com.company.app` format |
|
||||
| `Missing required field` | Required field omitted | Add the field |
|
||||
| `Invalid version_code` | Not a positive integer | Use positive number |
|
||||
| `Icon not found` | Icon path doesn't exist | Check file paths |
|
||||
| `Invalid permission` | Unknown permission | Use valid permission name |
|
||||
|
||||
## Example: Minimal Manifest
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "com.example.hello",
|
||||
"name": "Hello World",
|
||||
"version": "1.0.0",
|
||||
"version_code": 1,
|
||||
"entry": "main.rml",
|
||||
"author": {
|
||||
"name": "Developer",
|
||||
"email": "dev@example.com"
|
||||
},
|
||||
"icons": {
|
||||
"128": "icon.png"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Example: Full Manifest
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "com.acme.calculator",
|
||||
"name": "ACME Calculator",
|
||||
"version": "2.1.0",
|
||||
"version_code": 5,
|
||||
"entry": "assets/main.rml",
|
||||
"description": "A powerful calculator with scientific functions.",
|
||||
"category": "utilities",
|
||||
"permissions": [
|
||||
"storage",
|
||||
"clipboard"
|
||||
],
|
||||
"min_mosis_version": "1.2.0",
|
||||
"author": {
|
||||
"name": "ACME Corp",
|
||||
"email": "apps@acme.com",
|
||||
"url": "https://acme.com"
|
||||
},
|
||||
"icons": {
|
||||
"32": "icons/icon-32.png",
|
||||
"64": "icons/icon-64.png",
|
||||
"128": "icons/icon-128.png",
|
||||
"256": "icons/icon-256.png"
|
||||
},
|
||||
"screenshots": [
|
||||
"screenshots/basic.png",
|
||||
"screenshots/scientific.png",
|
||||
"screenshots/history.png"
|
||||
],
|
||||
"locales": {
|
||||
"default": "en",
|
||||
"supported": ["en", "es", "fr", "de"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Getting Started](../getting-started.md) - Create your first app
|
||||
- [Permissions Guide](../guides/permissions.md) - Understanding permissions
|
||||
- [Publishing Guide](../guides/publishing.md) - Submit your app
|
||||
Reference in New Issue
Block a user