From MozillaWiki
< Gaia‎ | Contacts
Jump to: navigation, search

Contact Bookmarks

User story

As a user I want to be able to add contacts to the home screen so I can quickly and easily initiate communication with my favorite contacts.

Acceptance Criteria

  • if contact is deleted then pinned contact should be removed from homecreen
  • if contact has a picture then that picture should be used when pinned to homescreen
  • if contact has no picture then placeholder should be used when pinned to homescreen
  • if there are multiple number I want to be able to choose which number is used.
  • if a number is deleted in the contact details then that activity should not be possible and user should not be offered the option when he taps the pinned contact

UX Proposal

The wirefames for this feature can be found at File:Contacts Bookmark to Home V0.1.pdf

Visual proposal

ContactBookmark proposal2.png

Implementation proposal (WIP)

Bookmarking stuff (contacts in this case)

We already have a bookmarking mechanism in place that allows users to add web pages to the homescreen. The core piece of this mechanism is implemented by the Bookmark application. This application maintains a DataStore (bookmarks_store) where the bookmarks data is saved. We save an object of this form per each bookmark:

 {name, icon, url}

The Bookmark application also exposes web activities to allow saving and removing bookmarks. But it only allows urls with http://, https:// or rtsp:// schemes.

The Homescreen application is the one responsible for rendering the bookmark icons in the screen and handling clicks on these icons. What we are currently doing when a user clicks on a bookmark is a simple with the url of the bookmark and a few extra parameters. This ends up triggering a mozbrowseropenwindow event that creates the new chrome browser window embedding the content of the bookmarked url.

We would like to take advantage of the current bookmarking mechanism and propose a way to allow apps to bookmark urls to their own content.

Adding and removing bookmarks now

As mentioned above the current existing mechanism only allows bookmarking http://, https:// or rtsp:// urls which unfortunately is not enough for our needs. What we would like to bookmark is app:// urls for the general use case so we can deeplink any page in an app. For the contacts case we would like to be able to bookmark urls like app:// To do this the first piece that we need is App Scopes implemented in the platform.

We also want apps to be in control of their own bookmarks and don't allow other apps to read or modify them. The current bookmarks solution based on datastore has no control about who owns the data. We give read/write access to any app. This is ok as long as the DataStore API is open to certified apps only, but we need to change this once DataStore is also allowed to privileged apps. Ideally the only ones that should access to a bookmarks data are the owner of the bookmark and the homescreen (including 3rd party homescreen). To make this happen with DataStore, we need a way to give access to a datastore by permission. So for example a 3rd party homescreen that should already have the homescreen-webapps-manage permission should be able to access the bookmarks datastore while an app without this permission shouldn't. We could easily have this by adding this permission requirement to the manifest datastore definition. In any case, since DataStore for privileged apps is something that does not seem to be happening for 2.2, this shouldn't block us for now.

Another feature that we want is to have the owner of a bookmark and the homescreen in synchrony. This means that if I add a bookmark from the Contacts app and I remove it from the Homescreen, the Contacts app should be aware of this removal. This allows the bookmark owner to modify its UI accordingly. For the Contacts app specific use case, we can show in the contact details if the contact is pinned or not. Unfortunately, we don't see a way to do this with the current implementation for adding and editing bookmarks based on web activities only. An example scenario:

  • We have the ideal security model for the DataStore API where we can give access to apps by permission or even by origin.
  • We have the bookmarks datastore accessible only to homescreens and its owner (the Bookmarks app).
  • A 3rd party app *with no direct read or write access* to the bookmarks datastore creates a bookmark through the save-bookmark activity that is handled by the Bookmarks app and in the end by the Homescreen app.
  • The 3rd party app updates its UI to indicate the existence of a homescreen bookmark.
  • The bookmark is removed from the homescreen.
  • The 3rd party app cannot update its UI to indicate that the homescreen bookmark was removed (it gets no notification and it cannot access the bookmarks store to check it).

We propose to augment the current web activities based model for addition and removal with local bookmarks datastores per bookmark provider.

Bookmarks datastores proposal



Bookmarks app

The Bookmarks app is the one responsible for keeping the information about all the bookmarks added in the device whichever its owner is. It keeps a datastore named bookmarks_store that should have readonly access for apps having the homescreen-webapps-manage permission, so the Gaia Homescreen app and 3rd party homescreens should be able to access this data and subscribe to changes to it. Ideally, all the changes in this datastore should be done by the Bookmarks app, but we will keep allowing certified apps to also modified its content as it is currently being modified by the bookmarks migration processes. The data contained in this store will be obtained from the bookmark providers via web activities.

Bookmark providers

Bookmark providers are the apps that want to add bookmarks to the homescreen. The way bookmark providers add new bookmarks is via the save-bookmark activity. This will wake the Bookmarks app up and will present the appropriate UI before adding the bookmark to the homescreen. Once the user confirms the addition of the bookmark and to allow the bookmark provider to be in synchronization with the homescreen, the Bookmark app will write the bookmark also in a datastore named bookmarks_providers owned by the bookmark provider. This will allow the provider to receive notifications when a bookmark is edited or removed from the homescreen. This datastore will have readwrite access for certified app, but the only app actually modifying it will be the Bookmarks app (for additions and removals) and the bookmark provider (for editions).


The homescreen(s) will be the one showing the bookmarks (along with the bookmark owner). It will also allow users to remove bookmarks and this will be done by directly removing it from the bookmarks_store datastore, which will trigger the onchange event or datastore-change-bookmarks_store system message that will be received by the Bookmarks app. This app will update the bookmark provider's datastore owner of the removed bookmark, so the owner can update its UI accordingly.

Contact bookmark window

So we can already add a bookmark to a contact and open the Contacts app with the bookmarked information when a click is done on its icon. But we still need to do the hardest part of this feature: to show the contact details overlaying the Homescreen app. And as far as I know that cannot be done by apps so far. Every Gaia app is placed on an iframe that it is at the same level as the Homescreen because the Homescreen is simply another app. So even if we could make the contacts app background transparent (which we normally can't) we would only see the wallpaper without icons.

Overlay window

What we need to implement for the contact bookmarks feature is a way for apps to place content overlaying other app.

This functionality has the following issues:

  1. Security issues, like adding a vector for clickjacking attacks or spoofing of the system UI.
  2. Visual issues. We will be running a new process for the content embedded in the overlay and it is possible that the app that is taken to the background gets killed by the OOM killer. That would leave us with a white background or a wallpaper without icons. We need a way to avoid this.

To mitigate the first issue, we will be protecting this feature under a new permission named overlay-window similar to the already existing attention-window one.

To solve the second issue, we will be closing the overlay window if the background app is killed (except for the homescreen that is automatically restarted). And we will probably be showing screenshots of the background content anyway once bug 1034001 is fixed, so in the case of the homescreen, if it is restarted the user won't notice it.

The way an app requests opening an overlay window will be via with a new feature option named overlay similar to the currently existing attention' one.

Trusted UI

The inability for apps to overlay the Homescreen is the sole reason of the existence of the Trusted UI. However it has already been said in a few occasions how useless it is from an UX point of view and how it fails as way of transmitting trustworthiness to the user. So in case you are wondering how the trusted UI interferes with this proposal, I believe it shouldn't interfere, as the Trusted UI should be gone soon. We already have most of the new Haida features mentioned on this thread and we can add the missing ones (like a better SSL status indicator) that I don't think are a blocker to finally get rid of the trusted UI.


Implementation status