wiki:SimpleAttach

Version 3 (modified by davea, 9 years ago) (diff)

--

  1. Improved attach process
    1. Current attach process
    2. Project front page
      1. Android case
      2. Non-Android case
      3. What projects must do
    3. Implementation
      1. browser_platform_supported()
      2. join_button()
      3. The concierte.php script
      4. Manager
    4. Comments

Improved attach process

This document proposes changes to the process by which volunteers 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 a lot of steps, and we lose a fraction of volunteers at each step.
  • If the computer is of a type for which the project has no apps, the user doesn't learn this until BOINC has already been installed. Ideally they should learn this immediately.
  • It doesn't take into account whether the project uses VirtualBox. If it does, 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.

Project front page

If the user's computer is of a type for which the project has no apps, they see a message like

This project doesn't currently support Mac OS X computers. A list of supported computer types is [here].

Android case

For Android devices, the front page says

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

Non-Android case

For non-Android computers, the front page says:

  • To participate, the BOINC software must be installed.
  • (big green button): Join (install BOINC)
  • (smaller text): If BOINC is already installed, click [here]

If the project has VBox apps for this platform, the above is replaced with

  • To participate, the BOINC and VirtualBox software must be installed.
  • (big green button): Join (install BOINC and VirtualBox)
  • (smaller text): If BOINC and VirtualBox are already installed, click [here]

For new volunteers, the process is:

  1. Visit project web site, click on Join (install BOINC). Download happens, browser remains on project web site (see below). Possibly (depending on OS/browser) goes to a page describing how to run the installer after download is done.
  2. When download is done, click on installer.
  3. Click on Defaults in installer
  4. Manager runs and brings up Attach wizard at the "enter email/password" page; no need to select project etc. This page also has name/info of project. Enter email/password.

Existing volunteers click on the "already installed" link, and see a page telling them to open the BOINC Manager and select Add Project.

What projects must do

Add the following to config.xml:

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

In the home page:

  • Call browser_platform_supported(). If this returns false, show the "platform not supported" text, and link to supported_platforms.php.
  • Call join_button() as: 
    list($url, $text) = join_button();
    and display a button linking to the returned URL. $text is either "BOINC" or "BOINC and VirtualBox".
  • Show the "already installed" link, pointing to attach.php.

Implementation

browser_platform_supported()

This gets the platform from the user agent string, then finds the supported platforms by enumerating the app_version and platform tables.

join_button()

This extracts from config.xml:

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

It sees whether VBox is used by enumerating the app_version table.

These data are passed as URL args to a URL on the BOINC web server (concierge.php). If the user is logged in on the project site, it also passes

  • the user name
  • the user authenticator

The concierte.php script

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

It 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_required is present, it uses the BOINC+Vbox installer).

It then 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 (if present)
attach_auth
the user authenticator (if present)

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

The script 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.

Manager

When the manager starts up, 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 the email/password page.

Comments

There are actually four scenarios, corresponding to:

  1. Whether the user has installed BOINC on the computer.
  2. Whether the user has an account on this project.

This design is geared to the cases where 2 is false. We should handle the other cases as well.