Changes between Version 2 and Version 3 of SimpleAttach


Ignore:
Timestamp:
Dec 31, 2014, 1:17:53 PM (10 years ago)
Author:
davea
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • SimpleAttach

    v2 v3  
    1 = Simplified Attach =
     1[[PageOutline]]
     2= Improved attach process =
     3
     4This document proposes changes to the process by which volunteers attach to projects.
    25
    36== Current attach process ==
    47
    5 The process of attaching to a project, for a first-time volunteer,
    6 involves several steps:
     8Suppose a first-time volunteer wants to participate in a BOINC project
     9that uses the standard PHP code for its front page.
     10The steps are:
    711
    812 1. Visit the project web site (say, via a link in a news story).
    913 1. Click on "Download" on the project site, taking you to the BOINC download page.
    10  1. Click on "Download BOINC".
     14 1. Click on "Download BOINC" or "Download BOINC + VBox".
    1115 1. When the download is done, click on the installer.
    1216 1. Click on "defaults" in the installer.
     
    2024 1. Enter email address and password.
    2125
    22 This is a lot of steps, and we lose a fraction of volunteers at each step.
    23 
    24 For existing volunteers (already running BOINC on this computer) the steps are:
     26For existing volunteers (i.e. already running BOINC on this computer) the steps are:
    2527
    2628 1. Visit project web site; figure out what to do next
    27    (standard project front page doesn't say).
     29   (the standard front page doesn't say).
    2830 1. Open the BOINC Manager.
    2931 1. Open Attach wizard.
    3032 1. Click on Add Project.
    31  1. Find project in list.
    32  1. Click on New User.
     33 1. Find project in list or enter URL.
     34 1. Click on Existing User.
    3335 1. Enter password (email should be pre-populated from previous attach).
    3436
    35 == Proposed attach process ==
     37Problems with this design:
    3638
    37 This document describes a new scheme that simplifies both scenarios.
     39 * In each case there are a lot of steps, and we lose a fraction of volunteers at each step.
     40 * If the computer is of a type for which the project has no apps,
     41   the user doesn't learn this until BOINC has already been installed.
     42   Ideally they should learn this immediately.
     43 * It doesn't take into account whether the project uses !VirtualBox.
     44   If it does, the user should be required to download BOINC+VBox.
     45 * The scheme applies to non-Android computers.
     46  For Android users the process is similar, except that BOINC must be downloaded from
     47  the Google or Amazon app store.
     48  The standard project front page says nothing about Android.
    3849
    39 Project web sites have 2 buttons:
    40  * "Join (download BOINC)"
    41  * "Join (already running BOINC)"
     50This document describes a new scheme that addresses these problems.
    4251
    43 New volunteer case:
     52== Project front page ==
    4453
    45  1. Visit project web site, click on "Join (download BOINC)".
     54If the user's computer is of a type for which the project has no apps,
     55they see a message like
     56
     57'''This project doesn't currently support Mac OS X computers.
     58A list of supported computer types is [here].'''
     59
     60=== Android case ===
     61
     62For Android devices, the front page says
     63
     64 * '''[Download BOINC]''' (link to Google or Amazon app store)
     65 * '''Open BOINC, select Add Project, and choose (project name)'''
     66
     67=== Non-Android case ===
     68
     69For non-Android computers, the front page says:
     70
     71 * '''To participate, the BOINC software must be installed.'''
     72 * (big green button): '''Join (install BOINC)'''
     73 * (smaller text): '''If BOINC is already installed, click [here]'''
     74
     75If the project has VBox apps for this platform, the above is replaced with
     76
     77 * '''To participate, the BOINC and !VirtualBox software must be installed.'''
     78 * (big green button): '''Join (install BOINC and !VirtualBox)'''
     79 * (smaller text): '''If BOINC and !VirtualBox are already installed, click [here]'''
     80
     81For new volunteers, the process is:
     82
     83 1. Visit project web site, click on '''Join (install BOINC)'''.
    4684   Download happens, browser remains on project web site (see below).
    4785   Possibly (depending on OS/browser) goes to a page describing how to
     
    5492   Enter email/password.
    5593
    56 Existing volunteer case:
    57  
    58  1. Visit project web site, click on "Join (already running BOINC)".
    59  1. Taken to page saying "open BOINC Manager" and select Add Project.
    60  1. When they do that, it brings up Attach wizard at "enter email/password" page.
     94Existing volunteers click on the "already installed" link,
     95and see a page telling them to open the BOINC Manager and select Add Project.
     96
     97=== What projects must do ===
     98
     99Add the following to config.xml:
     100 * <project_desc>: a few-sentence description of the project.
     101 * <project_inst>: the host institution (optional).
     102
     103In the home page:
     104
     105 * Call '''browser_platform_supported()'''.
     106   If this returns false, show the "platform not supported" text,
     107   and link to '''supported_platforms.php'''.
     108 * Call '''join_button()''' as:
     109{{{
     110list($url, $text) = join_button();
     111}}}
     112   and display a button linking to the returned URL.
     113   '''$text''' is either "BOINC" or "BOINC and !VirtualBox".
     114 * Show the "already installed" link, pointing to '''attach.php'''.
    61115
    62116== Implementation ==
    63117
    64 === What projects must do ===
     118=== '''browser_platform_supported()''' ===
    65119
    66 Project must add the following to config.xml:
    67  * <project_desc>: a few-sentence description of the project
    68  * <project_inst>: the host institution
    69  * <vbox_required/> : if present, this project requires VirtualBox
     120This gets the platform from the user agent string,
     121then finds the supported platforms by enumerating
     122the app_version and platform tables.
    70123
    71 In the home page, put:
    72  * a "Join (download BOINC)" button
    73   linked to the URL returned by ''join_download_url()'' PHP function in util.inc.
    74  * a "Join (already running BOINC)" button
    75   linked to the URL returned by ''join_no_download_url()'' PHP function in util.inc.
     124=== join_button() ===
    76125
    77 If this project requires VBox, replace "BOINC" by "BOINC+VirtualBox" in the above.
    78 
    79 === The join_x_url() functions ===
    80 
    81 The ''join_x_url()'' functions extract from config.xml:
     126This extracts from config.xml:
    82127 * the master URL
    83128 * the project name
    84129 * the project description
    85130 * the project institution
    86  * vbox_required
    87131
    88 and pass these as URL args to a URL on the BOINC web server (concierge.php).
     132It sees whether VBox is used by enumerating the app_version table.
     133
     134These data are passed as URL args to a URL on the BOINC web server (concierge.php).
    89135If the user is logged in on the project site, it also passes
    90136 * the user name
    91137 * the user authenticator
    92 
    93 '''join_download_url()''' also passes a "download_required" flag.
    94138
    95139=== The concierte.php script ===
     
    97141The concierge.php script looks at the master URL to see if the project is in BOINC's list.
    98142
    99 If "download_required" is set,
    100 it looks at the user agent string to find the computer's platform,
     143It looks at the user agent string to find the computer's platform,
    101144and gets the URL of the current BOINC installer for that platform.
    102145(If vbox_required is present, it uses the BOINC+Vbox installer).
     
    104147It then sends the following cookies (from the boinc.berkeley.edu domain):
    105148
    106 '''attach_known''':: 1 if the project is known to BOINC
    107 '''attach_master_url''':: the master URL
    108 '''attach_project_name''':: the project name
    109 '''attach_project_desc''':: the project description
    110 '''attach_project_inst''':: the project institution
    111 '''attach_user_name''':: the user name (if present)
    112 '''attach_auth''':: the user authenticator (if present)
     149 '''attach_known''':: 1 if the project is known to BOINC
     150 '''attach_master_url''':: the master URL
     151 '''attach_project_name''':: the project name
     152 '''attach_project_desc''':: the project description
     153 '''attach_project_inst''':: the project institution
     154 '''attach_user_name''':: the user name (if present)
     155 '''attach_auth''':: the user authenticator (if present)
    113156
    114157These cookies are sent with a 24-hour expiration time.
    115158
    116 If "download_required" is set,
    117 the script then redirects to the URL of the installer file.
     159The script then redirects to the URL of the installer file.
    118160On current browsers this doesn't change the web page
    119161(which is still the project's main page);
    120162it starts a download of the BOINC installer,
    121163which is displayed in the status bar or elsewhere.
    122 
    123 If "download_required" is not set, it does something
    124 to avoid showing a web page (need to figure this out).
    125164
    126165=== Manager ===
     
    130169If this is present, it puts up the Attach Wizard,
    131170at the email/password page.
    132 
    133 It does the same check when
    134171
    135172== Comments ==
     
    142179This design is geared to the cases where 2 is false.
    143180We should handle the other cases as well.
     181