Web Gallery Spec

Written by Jono Bacon (jono At ubuntu DOT com).

One of the most wonderful elements of the Ubuntu Accomplishments system is being able to show others which accomplishments you have earned from your community contributions as well as things you have done on your computer. Currently these trophies are exposed via the Accomplishments Information viewer and/or the Trophies dash lens.

This spec outlines the plan for a web application that you can use show your trophies online to others.

Account Registration

It is important that we respect the privacy of our users, and as such the web display of user trophies should be switched on as opposed to be on by default.

Enabling this is a two step process:

• The user enabled their trophies to be viewed on the web.
• The user can choose a username

Let's look at these both.

User enables their trophies to be displayed on the web

There will be an option exposed in the graphical client to show your trophies online (which will in turn use a daemon function to switch on the support).

Support will be enabled by the daemon adding a file called WEBVIEW into the base directory of the user's Ubuntu One trophy share.

The app will then load up a web page and pass it the id of the users share (e.g. http://trophies.ubuntu.com/id=Jono-23423423423423423423234234). - this web allows the user to pick a username.

User can pick their username

We first ask the user to authenticate using Ubuntu Single Sign on.

We then allow the user to add a username. Usernames will be stored in an accounts table and the suggested username will be checked for duplicates against this table. If the username is not taken, it is assigned to the user.

The username will be mapped to the URL (e.g. http://trophies.ubuntu.com/jonobacon).

Other Accounts Issues

User wants to stop showing trophies online

In this case, we delete the WEBVIEW file from the users Ubuntu One share which indicate the trophies are now not for online viewing.

User wants to change their username

We can expose an option in the web UI where the user can pick a different username.

A user's share gets deleted or changes

If a user with a registered account on the web viewer has his/her share lost, we can resolve this with the following approach:

1. The user re-creates the share in the desktop client.

2. We will expose an option in the desktop client to add the share to the web account. This will load an URL with the shareid added (e.g. http://trophies.ubuntu.com/jonobacon/addshare&id=Jono-534589345983459834589734598)

3. The share will then be added to the user's profile.

User Experience

This section will walk through some of the core features of viewing the trophies online in different ways.

Please note: this spec only covers how to view trophies and doesn't include many other interesting types of functionality such as statistics, graphs, leaderboards etc.

Viewing All Trophies

When the user visits the URL for the user they will see a view of all trophies, divided up into different collections:

We could potentially include some filtering at a collection level, but the above design should keep it simple for now.

At the top of the screen you can see the different collection as buttons and the user can click one of these buttons to see a particular collection in more detail.

Viewing Trophies in a Collection

The collection view presents each category as a section:

Viewing Latest Trophies

Another potential view could be showing the latest accomplishments:

Viewing a Trophy's Details

Whenever the user clicks on a trophy, they will see the details of that specific trophy:

This is inspired by the trophy information shown in our main desktop app:

Implementation

We have discussed that we will create this app using Django and the Ubuntu theme.

This web app will run on the server and it's primary source of data will be the Ubuntu One/Shared With Me share that contains all the different shares. Below are some examples of how these different features could be implemented.

How Shares Work

I am going to present a bit of background information about how the validation server works and what is in the shares. This should be useful for those of you unfamiliar with the system.

This is how a trophy gets validated:

1. The users desktop Ubuntu Accomplishments installation detects that he has accomplished something.

2. A .trophy file is created and added to ~/.local/share/accomplishments/trophies/<collection> (e.g. the collection could be ubuntu-community for Ubuntu Community Accomplishments.

3. The .trophy includes details of the accomplishment as well as the identification information of the user.

4. On the validation server all the users shares are in 'Ubuntu One/Shared With Me. The server scans for .trophy files that don't have an accompanying .trophy.asc` file (this is the signed file) and it validates them.

5. The final .trophy.asc file is added to the same share dir as the .trophy file and it is synced back to the users desktop machine.

There are a few key points here:

• The Web Gallery should only display trophies that have the following conditions:

  • The .trophy has a .trophy.asc file too (these are for validated accomplishments).

  • If the .trophy has no needs-signing field or the needs-signing field is set to false (these are for local accomplishments that are not validated (e.g. the ones in the Ubuntu Desktop Accomplishments collection).

Share Schema

This web gallery app will work on the collection of user shares that is on the validation server. An example dump of these shares is available at http://ubuntuone.com/4PeIrXYFxCfEaNrwdWYXnr

Some notes:

• The structure of the share is like this:
  • - local username (e.g. cielak) - "Trophies Folder" - timestamp that the share was added (e.g. 4234234.24) - validation server name (e.g. The Matrix) - share ID - (e.g. 935e72dd-d336-4da2-a6fa-f48c5452f7fa)
• Inside each share dir are the collections (e.g. ubuntu-community). Note that some collections may be local collections and thus have trophies that are not validated (e.g. ubuntu-desktop).

• Inside each collection dir are a list of .trophy and .trophy.asc files. The .trophy files are the trophies that are generated on the client machine and the .trophy.asc files are the signed trophies. IMPORTANT: we should only ever process .trophy.asc trophies, and not .trophy files - we only want to show signed trophies. We should check in each .trophy files if needs-signing = true to check if we should process the .trophy.asc file or not. For local accomplishments (e.g. ubuntu-desktop) that have needs-signing = false or no needs-signing field, we can just show the .trophy files.

Displaying a user's trophies

Data Required

• username
• share-id

• WEBVIEW file in their share that indicates that the user consents to web viewing.

Logic

1. User goes to http://trophies.ubuntu.com/<username>.

2. We use the username to look up the share-id.
3. We use the share-id to find the share on the filesystem.

4. We read in all of the .trophy.asc files (these are the signed trophies) and build a dictionary of accomplishments that we can use to search and present the trophies in different ways.

Viewing a specific trophy (and getting infromation from the accomplishment file)

Data Required

• username
• share-id

• WEBVIEW file in their share that indicates that the user consents to web viewing.

Logic

1. User clicks on an accomplishment and the URL reflects the username and accomplishment ID (the accomplishment ID is in the format <collection>/<accomplishment>. As an example: http://trophies.ubuntu.com/<username>/<accomplishment-id> and something such as http://trophies.ubuntu.com/jonobacon/ubuntu-community/registered-on-launchpad - this page gives us the username and accomplishment-id that we need.

2. We use the username to look up the share-id.
3. We use the share-id to find the share on the filesystem.= Comments =

Feel free to add comments below.

1. We search for the accomplishment based on accomplishment-id (e.g. the accomplishment-id ubuntu-community/registered-on-launchpad could map to Ubuntu One/Shared With Me/<share>/ubuntu-community/registered-on-launchpad.trophy.asc).

2. Because we know the accomplishment-id we can also look the accomplishment details easily too.

Database Schema

Here's our current schema, but we would love to get additional input from a Django expert.

Getting Involved

We are actively looking for developers to get involved in writing the Ubuntu Accomplishments Web Gallery. If you have experience writing Django, we would love to have you participate.

Here is how to get started:

• Please join our mailing list at https://launchpad.net/~ubuntu-accomplishments-contributors and the IRC channel at #ubuntu-accomplishments on the Freenode IRC network and let us know you are interested in helping.

• The main project page is at https://launchpad.net/ubuntu-accomplishments-web

• Grab the code: bzr branch lp:ubuntu-accomplishments-web

• You can see the pending tasks and bugs on Launchpad: https://bugs.launchpad.net/ubuntu-accomplishments-web - feel free to pick a task and assign it to yourself!

• Old tasks were tracked on this Trello board we don't use anymore: https://trello.com/board/accomplishments-web-gallery/4fc37826d4b78c516336198f

We look forward to seeing you on the team!