orbit-love / orbit-browser-extension

The Orbit extension: all your community data, right at your fingertips.

Orbit Browser Extension

Community data at your fingertips, available inside GitHub, Twitter, LinkedIn, and Gmail.
Get it on the Chrome web store (requires an Orbit account).

Local installation

Clone the repository and install the dependencies:

git clone [email protected]:orbit-love/orbit-browser-extension.git
cd orbit-browser-extension
yarn && yarn build

On Google Chrome:

1. Open chrome://extensions;
2. Toggle the “developer mode” (wink wink) in the top-right corner;
3. Click on “Load unpacked”;
4. Select the orbit-browser-extension/dist folder;
5. An Orbit logo should appear in the top-right corner of Chrome indicating that the extension is active;
6. Right-click on this logo, then click on Options;
7. Sign in with your Orbit account and select a workspace;
8. Go to any GitHub issue/PR/Discussion, LinkedIn profile, Twitter profile, or Gmail email;
9. You should see the Orbit widget: you’re all set!

Development

Run yarn start to watch the changes. Run yarn test to start the test suite, or yarn test:watch to run them continuously.

To reload the extension after some changes, open chrome://extensions and click on the “reload” button for the Orbit one.

To use the local API instead of the prod one, change ORBIT_ROOT_URL in orbit-helper.js to your ngrok tunnel address.

Contributing

Pull requests & issues welcome!

Accessibility

Accessibility is a fundamental part of web design, and something we consider critical to the further development of this extension. Future contirbutions should aim to meet WCAG2.1 AA—if you notice any areas where we're failing, please raise them as issues or submit PRs to address them.

Common issues to check:

1. Verify all functionality is usable with keyboard-only control
2. Open your screenreader (VoiceOver is built-in for macOS, or Narrator in Windows) and confirm navigating across the widget provides clear, contextual, and useful information akin to what is shown visually.
3. Confirm colours satisfy contrast requirements using a tool such as colourcontrast.cc

Code overview

The extension's functionality mainly relies on two views:

1. Options View - Located in the src/options/ directory. This view displays the page users see when they access the extension's options using the specified chrome-extension URL. Here, you'll find both the markup and behavior logic for the options page.

2. Widget View - Found in src/components/widget.js, this view represents the popup that appears when users open the extension on a supported page they're browsing.

If you're new to developing browser extensions, there are a couple of crucial parts you need to be aware of:

1. Manifest File - Located at src/manifest.json. This file instructs the browser when to run which scripts (for example, "on a page that matches a GitHub pull request, run the github entrypoint"). If you plan to extend our extension's capabilities to new sites, you'll have to update this file accordingly.

2. Background Runner - The src/background.js file handles requests to the Orbit API in a separate thread, ensuring smooth performance. Look for instances of chrome.runtime.sendMessage to see examples of how this communication is performed.

The Code Flow

There exists a dedicated entrypoint for each supported site, like src/widget/githubEntrypoint.js. This script is responsible for determining the right moment to attempt loading the widget: on page load, after a specific element is visible on screen, after a navigation event - this varies depending on a site-by-site basis.

During initialization, the entrypoint script also sets up an array of Page objects. Each Page represents a specific type of page on the website where our widget can load (e.g. a GitHub Issue, a GitHub Discussion). They handle all the site-specific logic. For instance, to confirm we're on a particular type of page, a Page object would use the #detect() method. Or, to figure out where to place our widget, it would use #findInsertionPoint(). You can get more insights into these functions in the superclass at src/pages/page.js.

The entry point's final task is to kickstart the src/widget/widgetOrchestrator.js. This script checks if our widget can load on the current page and inserts a button, the widget, and a slot for additional data in appropriate zones on the supported sites.

Lastly, most of the remaining logic takes place in src/components/widget.js, which handles interactions with the Orbit API and manages the widget's various display states.

Adding Support for a New Site

For an example of this process being followed: #45

To add support for a new site to the extension:

1. Create a New Entrypoint

Start by creating a new entry point file, similar to src/widget/githubEntrypoint.js. This will require understanding when to load the widget for this specific site. Broadly speaking, listening for the DOMContentLoaded event is a good place to start. However different sites have different requirements, so it will require some investigation to identify the appropriate events to observe for the page load lifecycle. You can have a look at how this currently works for GitHub, Twitter and Gmail for inspiration.

In creating this, you'll reach a point where you need to define the pages to pass to the widget orchestrator. So...

2. Create a New Page Class

Create a new Page class for the new site by extending src/pages/page.js. This class will handles page-specific logic - see the comments in the superclass for details on the functions to implement, and take inspiration from the existing types of pages.

3. Create a Page-Specific Button

This is a custom element that needs to match the styling of the new site. This will be the button that users click to open the widget. By default the widget should be named obe-#{platform}-button where platform is an identifier for the new site (ie "github"), but you can customise this by overriding the #getButtonElementName function in your page.

4. Modify the Manifest.json File

Update src/manifest.json to specify on which URLs the new entry point script should run. Be sure to follow the correct Google Chrome extension manifest version specifications.

5. (Optional) Display additional data for this specific site

The widget contains a slot called additionalData, which you can update with site-specific content. For example, on GitHub we show the number of GitHub contributions the member has made.

Remember to conduct thorough testing to ensure the new site is supported correctly and that existing functionality is not compromised. Implement automated tests, if possible, to prevent future regressions.

Deployment

To deploy a new version of the browser extension:

• Create a new Release in GitHub:
  • Create a new commit on main titled Prepare release X.Y.Z with version bumps in package.json, src/manifest.json, and a CHANGELOG entry;
  • Tag that commit with the new version: git tag -a X.Y.Z -m 'vX.Y.Z'
  • Push the commit and the tags: git push && git push --tags
  • Create a new release in GitHub
• Run yarn build;
• Zip the dist folder;
• On the Google Webstore Developer Dashboard (requires authentication), upload the zip file and submit a new version.

About Orbit

Thousands of businesses use Orbit to grow and measure their community across any platform.

orbit-browser-extension's Issues

Twitter button does not align with twitter themes

On twitter, you can set your theme to something different than your system settings (for example you can have systemwide dark theme, but manually set twitter to "Light")

We only check system settings, so this can cause misalignment and make the button difficult to read

Add support for Firefox

I use Firefox as my daily driver. Could you support that?

I attempted to load it manually but hit some errors. Using Install Add-on from File... doesn't see the extension in the dist directory. I think Firefox looks for an .xpi file here?

Using Deb Add-ons and then Load Temporary Add-on... and selecting manifest.json it gets me to the "Thanks for installing the Orbit extension" page but the authentication URL doesn't work.

An error has occurred

The requested redirect uri is malformed or doesn't match client redirect URI.

I'd love to run this in Firefox please! Sling me test builds if you want me to test.

Unexpected UI formatting on GitHub discussion

Overview

I'd expect to see these buttons side by side, but I'm seeing them stacked vertically. The issue appears to be occurring on GitHub Discussion posts.

Odd behavior on merged Orbit members

It seems for members that were merged (i.e., they had a member account that was created from Twitter and one from GH) that they don't work quite properly with this extension. When I click on "show X's profile on Orbit" it leads to a 404 as the path for that member isn't what the extension thinks it should be.

For example, the gh user joeduffy tries to go to https://app.orbit.love/REDACTED/members/joeduffy but since that account was merged, it returns a 404 and the actual URL for that user is https://app.orbit.love/REDACTED/members/funcofjoe because it was merged with that Twitter member.

Broken image in README

First-time caller and long-time listener. I wanted to mention there is a broken image in your README.

Github orgs with many repos prevent the extension from saving data

Using latest Edge, etc.

I have about 300 github repos in my org. When I try to save my settings, this error pops up in the console, but the extension reports success:

Uncaught (in promise) Error: QUOTA_BYTES_PER_ITEM quota exceeded
    at chrome-extension-async.js:46:1
(anonymous) @ chrome-extension-async.js:46

Would love to see this on Safari

It would be great to see this as a Safari extension and/or a Mac/iOS app with a share sheet.

Open the Options page on first install and upon clicking the Orbit toolbar button

The benefits would be twofold:

• Opening the Options page on first install streamlines the installation process;
• Opening the Options page when clicking the toolbar button is what a user (or at the very least, me) would expect.

When navigating from a repository page, the widget doesn’t show up

This issue has been present for a while, though I just now found out a consistent reproduction pattern.

When navigating to an issue/PR/discussion from the repository root, the Orbit widget does not show up. However, it does after a page refresh:

CleanShot.2023-04-26.at.17.18.30.mp4

I think I know what’s up: in the manifest.json’s content_scripts.matches key, we’re currently only matching issues/PRs/discussions URLs:

orbit-browser-extension/manifest.json

Lines 13 to 18 in e624385

	"matches": [
	"https://github.com/*/*/pulls*",
	"https://github.com/*/*/pull/*",
	"https://github.com/*/*/issues*",
	"https://github.com/*/*/discussions*"
	],

However, because GitHub uses Turbo for navigation between pages, when navigating from a repository page (which does not run the JavaScript code, since it’s not matching the URLs listed above) to an issue/PR/discussion page, no full-page reload occur, and thus the extension never kicks in.

A potential solution would be to change content_scripts.matches to match on all GitHub URLs, so that we’re sure that by the time a user navigates to an issue/PR/discussion, the extension is already running. This is what the fantastic refined-github extension is doing:

https://github.com/refined-github/refined-github/blob/3a356e54cd49486d4449edbf3b73a451d988f847/source/manifest.json#L41-L49

Feature Request: Support for GH Discussions

Minor thing that would be helpful - it would be great if this extension also showed Orbit info on members on posts/threads in GitHub Discussions (I know that Orbit doesn't integrate with Discussions yet, but being able to see the Orbit info that we do have would be great!)

The “nth contribution on this repo” information is inaccurate in some cases

Currently, in order to get this information, we get the last 25 activities for a member and look, among those, which ones are in this repo. However, if a member has more than 25 activities, we’re missing out on the older ones and thus give an inaccurate number in such cases.

In order to fix this, we’ll need to change the endpoint from /members/:member_id/activities to /activities?member_id=<member_id>&properties=<github_repo>. Note: this is dependent on a change in the Orbit API’s CORS policy to allow this new route.