wiki:SimpleAttach

Simplified registration/download process

This document proposes changes to the process by which volunteers download BOINC and attach to projects.

Current attach process

Suppose a first-time volunteer wants to participate in a BOINC project that uses the standard PHP code for its front page. The steps are:

  1. Visit the project web site (say, via a link in a news story).
  2. Click on "Download" on the project site, taking you to the BOINC download page.
  3. Click on "Download BOINC" or "Download BOINC + VBox".
  4. When the download is done, click on the installer.
  5. Click on "defaults" in the installer.
  6. The Manager runs and brings up the Attach wizard. Click on Add Project.
  7. Find the project in the project list (hopefully you still remember its name). Note: if the project is new and is not in the list, you need to go back to its web site, find the URL, and copy/paste it into the wizard. New volunteers are unlikely to figure this out.
  8. Click on New User.
  9. Enter email address and password.

For existing volunteers (i.e. already running BOINC on this computer) the steps are:

  1. Visit project web site; figure out what to do next (the standard front page doesn't say).
  2. Open the BOINC Manager.
  3. Open Attach wizard.
  4. Click on Add Project.
  5. Find project in list or enter URL.
  6. Click on Existing User.
  7. Enter password (email should be pre-populated from previous attach).

Problems with this design:

  • In each case there are many steps, and we lose a fraction of volunteers at each step.
  • For non-listed projects, users have to type or copy/paste a URL. Bad.
  • If the project requires VirtualBox, the user should be required to download BOINC+VBox.
  • The scheme applies to non-Android computers. For Android users the process is similar, except that BOINC must be downloaded from the Google or Amazon app store. The standard project front page says nothing about Android.

This document describes a new scheme that addresses these problems.

Proposed attach process

Front page

The project front page has a "Join" button, linked to a "registration" page.

Registration page

The registration page shows two forms side by side:

  • Create account (for users new to this project)
  • Log in (for existing users)

Submission of either form goes to the Download page (below).

If the user is already logged in on this project, the page redirects to Download page.

Download page

This page tells the user what software they need to install, and lets them either download it or confirm that it's already installed.

Android case

Show:

  • [Download BOINC] (link to Google or Amazon app store)
  • Open BOINC, select Add Project, and choose (project name)

Note: we can improve this, but it will take changes to the Android GUI.

Non-Android case

A project's config file can specify whether it needs VBox, and whether it has a min client version. The Download page says something like:

  • To participate in X, your computer must have BOINC (and VBox) installed.
  • If these are already installed, [click here]
  • [Download BOINC (and VBox)].

The "click here" link goes to a page that:

  • Sends some cookies (see below)
  • Tells the user to open the Manager and choose Add Project.

The Download link does to a page that

  • Sends some cookies (see below)
  • Initiates a download
  • Tells the user to double-click on the installer when download is done

User experience

In summary, the new-user process is:

  1. Visit project web site, click on Join".
  2. Enter email/passwd, click OK
  3. Click Download
  4. Click on installer, choose defaults
  5. Manager runs, brings up confirmation/welcome dialog

Note the following improvements:

  1. User doesn't leave the project web site (e.g. doesn't land on BOINC web site)
  2. User doesn't see list of all projects

What projects must do

Add to config.xml:

  • <project_desc>: a few-sentence description of the project.
  • <project_inst>: the host institution (optional).

Add to config.xml if needed:

  • <min_core_client_version>
  • <need_vbox>

In the home page:

  • put a button linking to register.php

Implementation

Register page: use existing code for forms

Download page: extract from config.xml:

  • the master URL
  • the project name
  • the project description
  • the project institution
  • software requirements

These first 4 items are passed as URL args to a script on the BOINC web server (concierge.php). Also passed:

  • the user name
  • the user authenticator
  • whether a download is required
  • whether VBox is needed

The concierge.php script

The concierge.php script looks at the master URL to see if the project is in BOINC's list.

It sends the following cookies (from the boinc.berkeley.edu domain):

attach_known
1 if the project is known to BOINC
attach_master_url
the master URL
attach_project_name
the project name
attach_project_desc
the project description
attach_project_inst
the project institution
attach_user_name
the user name
attach_auth
the user authenticator

These cookies are sent with a 24-hour expiration time.

If the "download" arg is set, the script looks at the user agent string to find the computer's platform, and gets the URL of the current BOINC installer for that platform. (If VBox is needed, it uses the BOINC+Vbox installer). It then redirects to the URL of the installer file. On current browsers this doesn't change the web page (which is still the project's main page); it starts a download of the BOINC installer, which is displayed in the status bar or elsewhere.

If there is no installer for the computer's platform, it goes to the BOINC "Download all" page.

Cookieless Installs

For unsupported browsers or projects with custom installers, the required information will be passed as part of the filename of the package downloaded from the server.

When the BOINC installer is launched, it'll detect the required information and add/update project_init.xml which in turn will be consumed via the client software on startup.

Package name parameters are as follows:

amu
the master URL
an
the project name
aa
the user authenticator
asc
the setup cookie

Usage Rules:

  • Each parameter is broken up into name/value pairs
  • Each name/value pair is separated by an underscore
  • Each value is base64 encoded

Example package name (Windows):

boinc_setup_amu_aHR0cDovL3NldGlhdGhvbWUuYmVya2VsZXkuZWR1Lw==_aa_ODU0NjVfZWEwYWJkNjc4NDc2MjllMWFlOWVkM2I4YWRmZmZmZmY=.exe

Example package name (Mac):

boinc_setup_amu_aHR0cDovL3NldGlhdGhvbWUuYmVya2VsZXkuZWR1Lw==_aa_ODU0NjVfZWEwYWJkNjc4NDc2MjllMWFlOWVkM2I4YWRmZmZmZmY=.zip

Note: Using the setup cookie is more desirable than storing the authenticator as part of the executable name. Setup cookies are created by the project server and expire after a given period of time. During the manager's attach process, it'll use the lookup account RPC to convert the setup cookie into the user's weak authenticator.

Manager

When the manager starts up, or the Add Project command is given, it looks for the attach_master_url cookie from the boinc.berkeley.edu domain. If this is present, it puts up the Attach Wizard, at a confirmation page that shows

  • the project name, description, and institution
  • the user name
  • whether the project is known to BOINC

Anonymous registration

The join process can be further simplified if we eliminate the email address and password associated with accounts. This might be selected by the project (using a config flag) or by the volunteer (by an "anonymous" checkbox in the Register page).

In each case, the Register page would create an account with random strings for email address and password.

We may want to add the following features:

  • Let volunteers with anonymous accounts log in to the project web site via links in the Manager.
  • Let anonymous accounts be made non-anonymous (i.e. given an email address, name, and password).

Unsupported platforms

One issue not addressed by this proposal: what if the computer is of a type for which the project has no apps? The user should learn this immediately. E.g. viewed from an Android device, the front page could say something like:

This project is not able to use Android devices. Please visit this site from a Windows, Mac, or Linux computer.

Last modified 20 months ago Last modified on 09/21/15 13:29:21