How Ultralinks Work

To broadly explain how Ultralink technology works, we are going to examine what goes on when it's loaded inside of a webpage. Make sure you are already familiar with What An Ultralink Is before reading this.

This is a high-level overview of a few core Ultralink concepts. Some of the processes below have more detailed descriptions elsewhere on the site.


To enable Ultralinks on a web page, ultralink.js (or a variation of that file) needs to be loaded. This can happen any number of different ways. The Ultralink browser extensions automatically load this JavaScript file inside every webpage a user surfs to.

In most cases, this file can be loaded by adding just a single script tag to a webpage like so:

In the case of the Ultralink bookmarklet, activating it will add the above tag to the webpage the user is currently on. If the user has installed one of our site plugins (like WordPress) then the JavaScript file is included on every page of the website and Ultralinks are enabled for all visitors.

Likewise, you can always manually add that single script to your webpages and automatically enable Ultralinks for all visitors.

ultralink.js Load Process

Once the ultralink.js file is loaded, it takes a look at the environment around it and configures itself accordingly. It first loads any dependencies that are not yet satisfied. Then it checks to see if there are any other copies of ultralink.js running (like when a user with the browser extension visits a site that already has Ultralinks enabled). And finally, it waits for the page to fully load before going to work on adding the Ultralinks.

The first thing ultralink.js does after the page has loaded, is to examine the format of the page and find where the primary textual content is. It does this through a number of smart heuristics that have been refined over time and are continally improving. Our document on Content Targeting discusses how this works in detail.

It then slices the content into paragraph sized chunks called fragments. It then uses the content of the fragment and the URL of the webpage to construct a unique URL that points to an Ultralink Server. The content located at this URL is the set of Ultralinks contained inside that particular fragment. If the server has never seen this content before, it asks ultralink.js to send the actual text up for Fragment Analysis and then returns the Ultralinks for that fragment.

This URL format is condusive to caching systems that can allow a single Ultralink Server to scale up to thousands of concurrent clients. To read a detailed description of how the caching system of works, check out our blog post CloudFlare as a DB Read Cache.

This process of automatic content analysis is the default behavior. If you wish though, you can instead customize and specify exactly what you want done with any particular content in the page and give it special instructions through options called Scanning Guides.

Ultralink Injection

ultralink.js is smart about when it decides to retrieve the Ultralinks for a given fragment. It is very sensitive to page performance and responsiveness. Thus, it only initially loads the Ultralinks for the fragments that are currently visible. After that, it gradually loads the Ultralinks for subsequent fragments under the visible portion of the webpage so that as the user scrolls down the page, the Ultralinks are already there waiting. Of course, if the user jumps to a different part of the page, then the Ultralinks for those fragments are immediately retrived if they havn't been already.

To inject the actual Ultralinks into the page, ultralink.js simply adds a <uword> tag around all the strings in the fragment that have Ultralinks associated with them. The information about the Ultralink is kept in memory and attached to the <uword> element. This keeps the DOM intrusion low and maximizes website compatability.

This injection process happens silently. Because Ultralinks have no visual callout by default, the user doesn't notice this process happening. To the user, Ultralinks are already there waiting for them. It is for this reason that we sometimes refer to this process as overlaying Ultralinks on the page to emphasize the minimal footprint and disruption.

Once Ultralinks have been injected into a fragment, the user can interact with them. On browsers with cursors, the default behavior is to fade-in a subtle text shadow under the Ultralinks as the cursor hovers near them (this behavior is customizable and not enabled on this site for example). When the user wants to learn more about something on the page, they simply click on the text and the Ultralink appears.

Ultralink User Interface

When invoked, the Ultralink itself hovers over the clicked word and presents a set of relevant links for the subject as defined by an Ultralink Database, the user's personal preferences and language/country settings. In addition, sets of releveant images (if any exist) are dispalyed and cycled through. The Ultralink floats above all the other content on the page so as not to interfere, and smartly configures itself depending on its position in the page or if it's in a width constricted view like on mobile devices. Visit the Anatomy Of An Ultralink page to take a quick visual tour of the Ultralink's user interface if you haven't already.

When a user clicks on a link that has a blue shadow, it simply takes them to that linked page. When they click on a link with a black shadow, an Inline Pane pops up that contains a view of the content behind the link. This Inline Pane is an iframe either to the remote link itself (link types like YouTube and Google Maps) or it's to a page with custom functionality called an Inline View.

Inside an Inline View, various API calls can be made and information gathered for quick and simple display within the iframe. The design and function of these pages is easily extensible and with a little effort, you can create your own. The iframe sandboxes the content and ensures that there is no functionality or information leakage between the Inline Pane and the containing page. This allows you to deploy complex functionality securely to any website immediately without any configuration or changes to the website itself.

To get a good idea on how to use Ultralinks from a user's perspective and learn how make the most of the Ultralink browser extensions, check out our How To Use Ultralinks page.

Ultralink Configuration

If you are looking at integrating Ultralinks into one of your projects or sites, we recommend first including ultralink-me.js instead of ultralink.js. ultralink-me.js is pre-configured for general usage and is the quickest way to get things up and running. By including that one script, everything is done automatically and no other setup or configuration is required.

When you use the standard ultralink.js script, the loading process stops short of actually analyzing the page and performing any Ultralink injection. This allows you to make specific configuration choices when you invoke Ultralink.start(), which then kicks off the analysis and injection processes. By passing in an Options Object to this function, you can override or customize much of the Ultralink functionality in the page. There is also a global Ultralink Object that you can interact with for additional integration.

Ultralink Storage

Ultralinks fundamentally offload the process of link creation from the content author to the Ultralink Database. Content authors now can simply create content without having to give as much thought to which concepts inside the content should be linked to. There is also no need to worry about links growing stale or stress over deciding which word occurrences to link anymore.

Instead, Ultralink Databases are created and maintained inside an Ultralink Server which can intelligently disambiguate and understand what the content is actually talking about. Ultralinks can be sync'd into the server from other databases, created and modified automatically through our APIs or constructed manually by hand.

To learn how to create Ultralinks through the Dashboard and find out how their settings can influence results, check out the How To Edit Ultralinks page.

Also, it is of note that you are not always required to source Ultralinks from a database (although this is usually the best solution). You can also create them on the fly through Ultralink Autogeneration.

Being A Good Houseguest

We have an operating philosophy that we like to call being a "Good Houseguest". Websites, like houses, come in all sorts of varieties. Some are big, some are small. Some are clean and some are dirty. And every house has its own specific rules.

We have taken pains to make ultralink.js a good houseguest on whatever website it's deployed on. It knows how to find the primary content in almost any page format thrown at it. It is also super optimized to have a very minor performance impact (even on mobile browsers and older platforms) and takes care to not modify or disrupt the underlying content and functionality.

Deployment of ultralink.js on a website just works, regardless of browser, tech stack, page design or page size.