[[PageOutline]]
= 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).
 1. Click on "Download" on the project site, taking you to the BOINC download page.
 1. Click on "Download BOINC" or "Download BOINC + VBox".
 1. When the download is done, click on the installer.
 1. Click on "defaults" in the installer.
 1. The Manager runs and brings up the Attach wizard.  Click on Add Project.
 1. 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.
 1. Click on New User.
 1. 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).
 1. Open the BOINC Manager.
 1. Open Attach wizard.
 1. Click on Add Project.
 1. Find project in list or enter URL.
 1. Click on Existing User.
 1. 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.
 1. When download is done, click on installer.
 1. Click on Defaults in installer
 1. 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.
 1. 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.