Personium interface is basically REST API based and does not provide any GUI tools. However, it is better to provide GUI tools to end-users.
Personium Project has implemented several sample GUI tools to demonstrate the functions of Personium. App developers are free to modify the published sample GUI tools.
However, Personium App developer should note that other Personium App developers are involved in this open ecosystem. Therefore, it is inevitable that all of us should follow certain basic developer guidelines (Likewise for any other OSS communities).
Types of Personium App
In Personium, App is categorized according to the level of permission of APIs the App can use. There are basically 3 types of Apps. For details on how APIs are categorized, please refer to the Personium Concepts.
In the following sections, definitions and deployment procedures for the above GUI types will be explained.
For detailed deployment procedures, please check out each repository's "How to deploy" section.
1. General Apps
General App is a Box level GUI that can perform operation on data contained in a dedicated Box which is only accessible to the corresponding App.
App developer designs what kind of data (files, DB, etc.) must be installed onto the user's Cell to provide services on the Personium Platform.
Most App developers implements Apps in this category.
Both App users and developers can benefit from this arrangement.
App user (data subject)
- All data is contained in the App user's PDS (Personium Cell) while a variety of services can be used.
- The user can reduce the risk of information leakage by customizing the access control configurations of the data provided to the service provider.
App developer (service provider)
- Since data management and access control are already performed by the App user, the App developer only need to provide minimal data management on the service side.
- The App developer can ask for permission to access data which is created by other Apps.
An easy way to conduct marketing research or survey.
All source codes are available on GitHub.
- Minimal App - Personium's Hello World App
- MyBoard - Provide data access control using Role only
- Calorie Smile Sync - Synchronize data from another Web service and provide data access control using Relation and Role
- Personal Data Brokering (Wakaba Municipal Information Bank)
How to deploy an App and provide service
In this section, we will explain the basic rules and recommendations on setting up an repository. By following these rules and recommendations, it makes deploying the Personium App on Personium Cell easier.
A simple example is available.
The following diagram shows the folder structure of a very simple Personium App.
Calorie Smile Sync has a more complicated bar folder.
│ launch.json │ profile.json │ relations.json │ roles.json │ ├─bar │ └─00_meta │ 00_manifest.json │ 90_rootprops.xml │ ├─doc │ ├─icon │ ├─locales │ ├─en │ │ profile.json │ │ │ └─ja │ profile.json │ └─src └─html │ app.html │ ├─css │ common.css │ ├─Engine │ getAppAuthToken.js │ ├─img │ github.png │ ├─js │ app.js │ common.js │ common_personium.js │ └─locales ├─en │ common.json │ glossary.json │ └─ja common.json glossary.json
Explanation and deployment procedures
|1||bar||Contains definitions and contents needed to create a BAR file which will be installed as Box onto the user's Cell. Compress (zip) this folder and name the compressed file with a ".bar" extension.|
|2||icon||Icon to be displayed in HomeApp.|
|3||launch.json||Contains information used by the HomeApp to lauch the app. Sample file has entry that allow launching native App (Android/iOS) which will be supported in the near future.|
|4||Defaults to be used when the App developer decides not to provide multilingual support.|
|profile.json||Contains information (Name/Description/Images, etc.) about the App. (Sample file)|
|relations.json||Contains display name, description and image of the relation(s) defined by the App. |
If relation is not defined, write a JSON file with an empty hash.
|roles.json||Contains display name, description and image of the role(s) defined by the App.|
If role is not defined, write a JSON file with an empty hash.
If role is defined, write necessary information. (Sample file)
|5||Multilingual files of the App|
|locales/ja/*.json||Japanese version. (Sample file)|
|6||src/android||Source codes for Android App.|
|7||src/html||Source codes for mobile browser App. Usually can be deployed on a Web server.|
|8||src/ios||Source codes for iOS App.|
2. Cell Management Clients
Cell Management Client is the GUI tool for managing Cell.
Cell level APIs allow administrative operations to be performed on the Cell.
For details, see here.
The Cell management client provides the following functions.
- Data management through Cell management authority (root)
- Registration/Modification of Cell control objects such as account and Role, or user profile
- Register relationship with other Cell, request registration by message (like typical friends registration)
- After relation registration, access data in another Cell that is permitted to access
- Installation of a Box (data structure) attached to an App
- Launch an App
- Send and receive messages not associated with Box
The following functions are under planning.
- App usage data privilege management, BOX uninstallation
- Cell data explorer
- Implementation of native App
- Automated Cell URL input by QR code, NFC etc.
- Configuration of user defined event, browsing of trigger log
3. Unit Management Clients
Unit management clients are Unit level management tools that helps you manage Personium cell(s).
The above management tools require a special token (issued by the corresponding UnitAdmin Cell) which possesses Unit management permission. Therefore, the following information is required during user authentication.
- Personium Unit URL
- UnitAdmin Cell name (Specified in the Personium Unit's UnitConfig file)
- UnitAdmin account name
- UnitAdmin account password
How to deploy
Similar to HomeApp, Unit/Cell Manager can also be deployed on a normal Web server instead of a Personium Cell.
We are also considering to build our next version of management tool in Electron.
In the Personium Apps ecosystem, in order to defend against unauthorized phishing Apps against PDS, App authentication must be enabled for the Box defined by the same App.
App authentication means that the App that accesses the data must be authenticated by the App Cell in addition to the User's Cell authentication, and see here for details.
When the App developer cannot start the App from the HomeApp properly, in order to access the Box, it is necessary to separately acquire a token after App authentication.
Note: App authentication is planning to support multiple schemas (implement URL hash).
Source codes based example is available here.