Appstore discover section API¶

The appstore “Discover” section is generated from data is provided using a JSON file. The discover.json consists of an array containing multiple elements, those elements are either shuffled or can be always shown.

Currently the following elements are supported:

Posts: Posts consists of a headline, a text and an optional image.
Full width media: Like images (webp is recommended due to quality, size and browser support), animations (webm or mp4) or videos 1
App showcases: Promote a set of apps
Carousel: Allow to shuffle through multiple elements

1: For videos see the example below.

Supported elements¶

Common element interface
Simple post: type: "post"
Showcase: type: "showcase"
- Example: Showcase with headline and apps
- Example: Showcase with headline and media entries
Carousels: type: "carousel"

Common element interface ¶

All content types are sharing a common interface

{
        // The type of the element
        "type": "post",
        // ID to indentify this element
        "id": "1d41a08e-4aa6-49b3-ad1b-ff2e83bcdc88",
        // (optional) if set this element will be always shown on that specified position
        "order": 1,
        // (optional) if set the content will only be shown starting that date
        "date": "2024-04-04T20:00:00Z",
        // (optional) if set the content will only be shown UNTIL that date
        "expiryDate": "2024-05-04T20:00:00Z",
        // (optional) the optionally localized headline, if a language is missing the "en" default is used
        "headline": {
                "en": "...",
                "de": "..."
        },
        // (optional) link for the element
        "link": "https://..."
}

Simple post: `type: "post"`¶

Post are elements with a headline, a text and an (optional) media part. All elements of it can be localized.

Example 1: Post with image ¶

{
        "type": "post",
        "id": "1d41a08e-4aa6-49b3-ad1b-ff2e83bcdc88",
        "headline": {
                "en": "Amazing wallpapers",
                "de": "Bezaubernde Hintergründe"
        },
        "text": {
                "en": "This are the most amazing wallpaers that you can possible have. Get them now!",
                "de": "Die wohl beeindruckensten Hintergründe die man haben kann. Hol sie dir jetzt!"
        },
        "link": "https://example.com/wallpapers",
        "media": {
                "alignment": "end",
                "content": {
                        "en": {
                                "src": {
                                        "src": "http://example.com/a.png",
                                        "mime": "image/png"
                                },
                                "alt": "Amazing wallpaper"
                        }
                }
        }
}

Output of example 1 - A post with an image on the right side

Example 2: Post with video ¶

{
        "type": "post",
        "id": "1d41a08e-4aa6-49b3-ad1b-ff2e83bcdc88",
        "media": {
                "content": {
                        "en": {
                                "src": {
                                        "src": "https://example.com/preview.webp", // the preview image (or animation)
                                        "mime": "image/webp"
                                },
                                "alt": "Some alternative text",
                                "link": "http://example.com/full-video" // the link to navigate to when pressing "Play video"
                        }
                }
        }
}

Output of the example 2 - background image with "play video" button on top

Example 3: Post with localized media ¶

It is possible to have localized media, e.g. screenshots in different languages. For this use an array for media instead:

{
        "type": "post",
        // ...
        "media": {
                "content": {
                        "en": {
                                "src": {
                                        "src": "https://example.com/english.webp",
                                        "mime": "image/webp"
                                },
                                "alt": "Some alternative text"
                        }
                        "de": {
                                "src": {
                                        "src": "https://example.com/german.webp",
                                        "mime": "image/webp"
                                },
                                "alt": "Ein Alternativtext"
                        }
                }
        }
}

Showcase: `type: "showcase"`¶

The showcase type allow to promot multiple entries in one element. It allows to either show multiple posts or apps.

Example: Showcase with headline and apps ¶

{
        "type": "showcase",
        // ...
        "headline": {
                "en": "5 top rated apps over all time"
        },
        "content": [
                {
                        "type": "app",
                        "appId": "cospend"
                },
                {
                        "type": "app",
                        "appId": "cookbook"
                }
        ]
}

Show case of 5 apps shown in a grid with a headline above

Example: Showcase with headline and media entries ¶

{
        "type": "showcase",
        "headline": {
                "en": "5 amazing wallpapers"
        },
        "content": [
                {
                        "type": "post",
                        "media": {
                                "content": {
                                        "en": {
                                                "src": {
                                                        "src": "http://example.com/first.png",
                                                        "mime": "image/png"
                                                },
                                                "alt": "Wallpaper..."
                                        }
                                }
                        }
                },
                {
                        "type": "post",
                        "media": {
                                "content": {
                                        "en": {
                                                "src": {
                                                        "src": "http://example.com/second.png",
                                                        "mime": "image/png"
                                                },
                                                "alt": "Another wallpaper..."
                                        }
                                }
                        }
                }
                // other posts
        ]
}

Show case of 5 images shown in a grid with a headline above

Carousels: `type: "carousel"`¶

Carousels allow the same common properties, like headlines and text, but have a content property for and array of posts to show. The content property also allows the app type like type: "showcase" does.

Example: Carousel with post content ¶

{
        "type": "carousel",
        "content": [
                {
                        "type": "post",
                        "headline": {
                                "en": "Nextcloud Office 7.0 out with full-featured editing dialogs"
                        },
                        "text": {
                                "en": "Today is an..."
                        },
                        "media": {
                                "content": {
                                        "en": {
                                                "src": {
                                                        "src": "http://example.com/first.png",
                                                        "mime": "image/png"
                                                },
                                                "alt": "..."
                                        }
                                }
                        }
                },
                // other posts
        ]
}

Carousel with a post but without a headline, users can swipe through different posts

Example: Carousel with headline and media content ¶

{
        "type": "carousel",
        "headline": {
                "en": "Some headline that is important"
        },
        "text": {
                "en": "Today is an..."
        },
        "content": [
                {
                        "type": "post",
                        "media": {
                                "content": {
                                        "en": {
                                                "src": {
                                                        "src": "http://example.com/first.png",
                                                        "mime": "image/png"
                                                },
                                                "alt": "...",
                                                "link": "..."
                                        }
                                }
                        }
                },
                // other posts
        ]
}

Carousel with a headline and text above. The carousel is showing a video.

Example: Carousel with app content ¶

{
        "type": "carousel",
        "headline": {
                "en": "Some amazing apps"
        },
        "content": [
                {
                        "type": "app",
                        "appId": "Cospend",
                },
                // other apps
        ]
}

JSON data schema¶

The JSON can be validated using out schema, see app-discover.schema.json.

The generic element
Localized strings
Media object
- Media content
- Media source
The app-element
The post-element
The showcase-element
The carousel-element

The generic element ¶

This element all other inherit from

Property	Type	Is required	Notes
`type`	string	yes
`id`	string	yes
`order`	integer		For manual ordering. Elements without `order` are shuffled
`headline`	Localized strings
`text`	Localized strings
`link`	URL		allows also `app://APP_ID` links opening the app, if installed or the appstore page otherwise
`date`	string (ISO8601 date-time)		Can be set to only show this entry after the specified date
`expiryDate`	string (ISO8601 date-time)		Can be set to only show this entry until the specified date

		"genericElement": {
			"type": "object",
			"properties": {
				"type": {
					"type": "string"
				}
			},
			"required": ["type"]
		},

		"genericContainerElement": {
			"$ref": "#/$defs/genericElement",
			"type": "object",
			"properties": {
				"id": {
					"$comment": "A unique ID, using UUID v4 is recommended",
					"type": "string"
				},
				"order": {
					"$comment": "Optional order for fixed order of elements",
					"type": "integer"
				},
				"headline": { "$ref": "#/$defs/localizedString" },
				"text": { "$ref": "#/$defs/localizedString" },
				"link": {
					"type": "string",
					"format": "uri-reference"
				},
				"date": {
					"type": "string",
					"format": "date-time"
				},
				"expiryDate": {
					"type": "string",
					"format": "date-time"
				}
			}
		},

Localized strings ¶

Localized strings are objects with the language code as the key and the translated string as the property, like:

{ "en": "Hello", "de": "Hallo" }

Property	Type	Is required	Notes
`en`	string	yes	The English text
language code	string		The translated text for that language

		"localizedString": {
			"type": "object",
			"properties": {
				"en": {
					"type": "string"
				}
			},
			"required": ["en"],
			"patternProperties": {
				"^[a-z]{2,3}(_[a-z]+)?$": { "type": "string" }
			},
			"additionalProperties": false
		},

Media object ¶

Media objects are used within the post element, they allow to embed video or image media.

Property	Type	Is required	Notes
`content`	Media content	yes	The content to show
`alignment`	string		When combined with text this defined the media alignment. One of: `left`, `right`, `top`

		"mediaObject": {
			"type": "object",
			"properties": {
				"content": { "$ref": "#/$defs/localizedMediaContent" },
				"alignment": {
					"enum": [
						"start",
						"end",
						"center"
					]
				}
			},
			"required": ["content"]
		},

Media content ¶

The media content is dictionary similar to Localized strings but instead of strings its values are media content objects with following properties:

Property	Type	Is required	Notes
`src`	Media source or array of it	yes	The media source, use an array for fallback options (source sets)
`alt`	string	yes	The alternative text for the media
`link`	URL		In case of videos this is the link to navigate when pressing the play-video button

		"mediaContent": {
			"type": "object",
			"properties": {
				"src": {
					"oneOf": [
						{ "$ref": "#/$defs/mediaSource" },
						{
							"type": "array",
							"items": { "$ref": "#/$defs/mediaSource" }
						}
					]
				},
				"alt": { "type": "string" },
				"link": {
					"type": "string",
					"format": "uri-reference"
				}
			},
			"required": ["alt", "src"]
		},

Media source ¶

Property	Type	Is required	Notes
`src`	URL	yes	The URL of the media element
`mime`	string	yes	The MIME type of the media element

		"mediaSource": {
			"type": "object",
			"properties": {
				"mime": { "type": "string" },
				"src": {
					"type": "string",
					"format": "uri-reference"
				}
			},
			"required": ["src", "mime"]
		},

The app-element ¶

The app element is only used in showcase elements.

Property	Type	Is required	Notes
`type`	string	yes	`"type": "app"`
`appId`	string	yes	The app id, e.g. `text` or `forms`

		"appElement": {
			"$ref": "#/$defs/genericElement",
			"type": "object",
			"properties": {
				"type": { "const": "app" },
				"appId": { "type": "string" }
			},
			"requiredProperties": ["appId"],
			"additionalProperties": false
		},

The post-element ¶

The post element is the basic element for media or text entries, it inherits from the The generic element and extends it by allowing the media property:

Property	Type	Is required	Notes
`type`	string	yes	`"type": "post"`
`media`	Media object or array	yes	Either one Media object or an array of multiple for localized media

		"postElement": {
			"$ref": "#/$defs/genericContainerElement",
			"type": "object",
			"properties": {
				"type": { "const": "post" },
				"media": { "$ref": "#/$defs/mediaObject" }
			}
		},

The showcase-element ¶

The showcase elements allows to display multiple posts inside one element, it inherits from the The generic element and extends it by allowing the content property:

Property	Type	Is required	Notes
`type`	string	yes	`"type": "showcase"`
`content`	array	yes	Array of The app-element or of The post-element

		"showcaseElement": {
			"$ref": "#/$defs/genericContainerElement",
			"type": "object",
			"properties": {
				"type": { "const": "showcase" },
				"content": {
					"type": "array",
					"items": {
						"oneOf": [
							{ "$ref": "#/$defs/appElement" },
							{ "$ref": "#/$defs/postElement" }
						],
						"minItems": 2
					}
				}
			},
			"required": ["content"]
		},

The carousel-element ¶

The carousel elements allows to display multiple posts inside carousel. It inherits from the The generic element and extends it by allowing the content property:

Property	Type	Is required	Notes
`type`	string	yes	`"type": "carousel"`
`content`	array	yes	Array of The post-element

		"carouselElement": {
			"$ref": "#/$defs/genericContainerElement",
			"type": "object",
			"properties": {
				"type": { "const": "carousel" },
				"content": {
					"type": "array",
					"items": {
						"$ref": "#/$defs/postElement",
						"minItems": 2
					}
				}
			},
			"required": ["content"]
		}