API addition

nsIBrowserSearchService.idl

  /**
   * Selects a new search engine to use as the current engine.
   *
   * Behaviour is to require explicit confirmation from
   * the user through a browser-provided dialog.  Add-ons must use
   * this API to modify search behaviours or face blocklisting
   *
   * @param  engine
   *         The engine to select.
   * @param  addonID
   *         the ID of the add-on requesting the change
   *
   * @throws NS_ERROR_INVALID_ARG if engine is unknown or addonID is invalid
   */
  void selectEngine(in nsISearchEngine engine,
                    in AString addonID);

Implementation notes:

• addonID should be used to get the name (at least) of the add-on triggering the prompt to include as the requester. Invalid
• addonID + version should be recorded, and multiple prompt attempts blocked if the user chooses to keep current.
• [optional] To reduce bad behaviour, we should attempt to identify the source of the API call and verify it's the same add-on as passed in. Bad behaviours should be recorded/reported somehow.

UI Treatment

Constraints

• Users must make a positive choice to select the engine (no next button)
• Source of the request must be identified
• We should use the biggest images that make sense in context.
• Learn more link should point to SUMO

Mockup

Follows the Win7 style wizard model of making a user choose an option. Cancel means nothing changes. Choosing current means the add-on can't re-prompt with the same version again. Ideally this should use the larger images introduced for new tab search, falling back to 32x32 or 16x16 icons if unavailable.

+-------------------------------------------------------+
| Change Search Provider?                               |
+-------------------------------------------------------+
|                                                       |
| Bob's Super Happy Toolbar wants you to change your    |
| search provider to Ask.com   _Learn More_             |
|                                                       |
| [ [ Google ] Keep using Google (currently in use)   ] |
|                                                       |
| [ [Ask.com ] Change my search to Ask.com            ] |
|                                                       |
+-------------------------------------------------------+
| (?)                                          [Cancel] |
+-------------------------------------------------------+