From 82cbe33ad90de244cd2752d666401aa67b72a58f Mon Sep 17 00:00:00 2001 From: Ldoppea Date: Thu, 19 Oct 2023 19:50:35 +0200 Subject: [PATCH] chore: Document `accept_from_flagship` on app's manifest --- docs/accept-from-flagship.md | 163 +++++++++++++++++++++++++++++++++++ docs/apps.md | 50 +++++------ 2 files changed, 189 insertions(+), 24 deletions(-) create mode 100644 docs/accept-from-flagship.md diff --git a/docs/accept-from-flagship.md b/docs/accept-from-flagship.md new file mode 100644 index 00000000000..3de146d9c66 --- /dev/null +++ b/docs/accept-from-flagship.md @@ -0,0 +1,163 @@ +[Table of contents](README.md#table-of-contents) + +# Accept from Flagship + +Flagship app is a mobile app that allows users to access all their Cozy from their phone (see [here](https://github.com/cozy/cozy-flagship-app) for more details). + +When the Flagship app is installed on the user's phone, then they can share a document with the app to upload it in their Cozy. + +When doing so, the user will have to chose which cozy-app should receive the shared document from a list of elligible cozy-apps (i.e. cozy-drive, mespapiers, etc) + +To be elligible, a cozy-app has to declare what it can receive. This is done in its `manifest.webapp` file. + +## The manifest + +The `manifest.webapp` file is used to declare the cozy-app's ability to receive files + +### `accept_from_flagship` field + +First field to declare is `accept_from_flagship`. It should be set to `true` to make the cozy-app visible in the list of elligible cozy-apps + +Example: +```json +{ + "name": "Drive", + "name_prefix": "Cozy", + "slug": "drive", + //... + "accept_from_flagship": true, + //... +} +``` + +### `accept_documents_from_flagship` field + +Declaring `accept_from_flagship: true` is not enough to be able to receive files from the Flagship app. The app should also declare which kind of files it can handle. + +The field `accept_documents_from_flagship` is an object containing all criteria that a file or a list of files should meet to be sharable with the cozy-app. + +#### `accepted_mime_types` criteria + +`accepted_mime_types` is used to declare each file type that can be handled by the cozy-app. + +This field should contain a list of all mime types that are supported by the cozy-app. + +Example of a cozy-app accepting PDF, and pictures: +```json +{ + //... + "accept_from_flagship": true, + "accept_documents_from_flagship": { + "accepted_mime_types": ["application/pdf", "image/jpeg", "image/png"], + } +} +``` + +In order to accept all files types, it is possible to use `'*/*'` mime type + +Example of a cozy-app accepting all types of documents: +```json +{ + //... + "accept_from_flagship": true, + "accept_documents_from_flagship": { + "accepted_mime_types": ["*/*"], + } +} +``` + +#### `max_number_of_files` criteria + +`max_number_of_files` is used to declare the maximum number of files that can be shared simultaneously with the cozy-app. + +Example of a cozy-app accepting only 1 document at a time: +```json +{ + //... + "accept_from_flagship": true, + "accept_documents_from_flagship": { + "max_number_of_files": 10, + } +} +``` + +Example of a cozy-app accepting up to 10 documents at a time: +```json +{ + //... + "accept_from_flagship": true, + "accept_documents_from_flagship": { + "max_number_of_files": 10, + } +} +``` + +Setting a limit is mandatory. The Flagship app doesn't support unlimited file number. + +#### `max_size_per_file_in_MB` criteria + +`max_size_per_file_in_MB` is used to declare the maximum size of files that can be handled by the cozy-app. + +The size limit is declared in MB. + +The size limit is per file. If multiple files are shared with the cozy-app, then each file size should be under that limit. + +Example of a cozy-app accepting documents up to 10MB: +```json +{ + //... + "accept_from_flagship": true, + "accept_documents_from_flagship": { + "max_size_per_file_in_MB": 10, + } +} +``` + +Setting a limit is mandatory. The Flagship app doesn't support unlimited file size. + +#### `route_to_upload` criteria + +`route_to_upload` is used to declare the cozy-app's route that should be used by the Flagship app when sharing files with the cozy-app. + +The app should then implement a page on that route that will be responsible to handle those documents (i.e. ask the user where to save the document, analyse the document etc) + +Example: +```json +{ + //... + "accept_from_flagship": true, + "accept_documents_from_flagship": { + "route_to_upload": "/#/upload?fromFlagshipUpload=true", + } +} +``` + +#### The complete manifest + +Here is an example of a `manifest.webapp` file for an app accepting only up to 10 picture files, with a maximum of 10MB: +```json +{ + "name": "Drive", + "name_prefix": "Cozy", + "slug": "drive", + //... + "accept_from_flagship": true, + "accept_documents_from_flagship": { + "accepted_mime_types": ["image/jpeg", "image/png"], + "max_number_of_files": 10, + "max_size_per_file_in_MB": 10, + "route_to_upload": "/#/upload?fromFlagshipUpload=true" + } + //... +} +``` + +Note that `accept_from_flagship` may seems to be redundant if `accept_documents_from_flagship` exists. This field is an optimization to allow cozy-client queries to filter only cozy-apps that accept sharings. + +## The API + +When a cozy-app is selected by the user to receive a shared file, this cozy-app is opened using the `route_to_upload` route. + +Then the cozy-app can use the Flagship OsReceive API to handle shared files. + +This API is documented [here](https://github.com/cozy/cozy-flagship-app/tree/master/src/app/domain/osReceive/os-receive-api.md) diff --git a/docs/apps.md b/docs/apps.md index da2c4a01839..2b5f14aca5e 100644 --- a/docs/apps.md +++ b/docs/apps.md @@ -21,30 +21,32 @@ didn't match our expectations. The is a better fit. We took a lot of inspirations from it, starting with the filename for this file: `manifest.webapp`. -| Field | Description | -| ----------------- | ---------------------------------------------------------------------------------------- | -| name | the name to display on the home | -| name_prefix | the prefix to display with the name | -| slug | the default slug (it can be changed at install time) | -| editor | the editor's name to display on the cozy-bar of the app | -| icon | an icon for the home | -| screenshots | an array of path to the screenshots of the application | -| category | the category of the application | -| short_description | a short description of the application | -| long_description | a long description of the application | -| source | where the files of the app can be downloaded | -| developer | `name` and `url` for the developer | -| locales | translations of the name and description fields in other locales | -| langs | list of languages tags supported by the application | -| version | the current version number | -| license | [the SPDX license identifier](https://spdx.org/licenses/) | -| platforms | a list of `type`, `url` values for derivate of the application for other devices | -| intents | a list of intents provided by this app (see [here](intents.md) for more details) | -| permissions | a map of permissions needed by the app (see [here](permissions.md) for more details) | -| notifications | a map of notifications needed by the app (see [here](notifications.md) for more details) | -| services | a map of the services associated with the app (see below for more details) | -| routes | a map of routes for the app (see below for more details) | -| mobile | information about app's mobile version (see below for more details) | +| Field | Description | +| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| name | the name to display on the home | +| name_prefix | the prefix to display with the name | +| slug | the default slug (it can be changed at install time) | +| editor | the editor's name to display on the cozy-bar of the app | +| icon | an icon for the home | +| screenshots | an array of path to the screenshots of the application | +| category | the category of the application | +| short_description | a short description of the application | +| long_description | a long description of the application | +| source | where the files of the app can be downloaded | +| developer | `name` and `url` for the developer | +| locales | translations of the name and description fields in other locales | +| langs | list of languages tags supported by the application | +| version | the current version number | +| license | [the SPDX license identifier](https://spdx.org/licenses/) | +| platforms | a list of `type`, `url` values for derivate of the application for other devices | +| intents | a list of intents provided by this app (see [here](intents.md) for more details) | +| permissions | a map of permissions needed by the app (see [here](permissions.md) for more details) | +| notifications | a map of notifications needed by the app (see [here](notifications.md) for more details) | +| services | a map of the services associated with the app (see below for more details) | +| routes | a map of routes for the app (see below for more details) | +| mobile | information about app's mobile version (see below for more details) | +| accept_from_flagship | boolean stating if the app is compatible with the Flagship app's "OS Receive" feature | +| accept_documents_from_flagship | when `accept_from_flagship` is `true`, defines what can be uploaded to the app (see [here](accept-from-flagship.md) for more details) | ### Routes