Betterlink Documentation

everything you want to know


Advanced Setup

Customization options, dynamic content, mobile redirection -- we've got you covered.

The basic setup works for most sites, but we know that some sites have different needs (our own homepage is a great example!). This resource will help you when you need more than the one-size-fits-all version of Betterlink.


Mobile + Desktop Support

This is probably the most important item to check-off. We want to ensure that anything that one of your visitors selects on your site can be easily accessed by a friend visiting on their mobile device. The good news: Betterlink supports this right out of the box.

Although we care about a lot of differnet elements of a submission (the URL of the page, where the submission sits relative to the whole webpage, or your browser version), what's most important is the actual content that's selected. As long as this text exists on both the desktop and mobile versions of your site, chances are we'll be able to find it.

This is important because even if you're not using a responsive version of a single webpage, but an entirely different page for mobile content, it will still be possible for Betterlink to provide the right experience for your visitors. However, it is critical that you pass along URL parameters to your mobile-specific web address during a site redirection.

Here's what we mean: Wikipedia

The exact URL for this link is http://en.wikipedia.org/wiki/Hyperlink?bl-sid=1. But if you visit this link from a mobile device, you'll land at http://en.m.wikipedia.org/wiki/Hyperlink?bl-sid=1. It's subtle, but the subdomain was changed to en.m.

Because the Betterlink Selection ID (bl-sid) was transferred to the new web address, everything works as expected.

The details for how to accomplish this are specific to your website and how you have configured your webserver.


Dynamic and User-Generated Content

Similar to our notes on Mobile Support, what's most important for Betterlink is that the text content that was previously selected can be found on your webpage the next time it is loaded. A few items could complicate this:

  • Manual edits to the page content (ex: a correction in a news article)
  • In-page pagination (ex: comment pages or a slideshow)
  • Content that lazy-loads after the rest of the page has loaded
  • Landing pages with daily content (ex: any news homepage)

There are a few tactics we can use to resolve these situations.

Tactic 1: Permanent Links

Betterlink supports a special configuration option that can be supplied at any point during or after initialization: permalink. In the most common example, this should be used for blog posts where the URL is dynamic and may change.

Use is simple. The following JavaScript can be applied at any point after the Betterlink global variable has loaded:

    betterlink.config.permalink = "http://example.org/your-website?example_param=true";

After this property is set, any subsequent URL submissions will use this as the base of the newly-generated URL.

Permalinks + Daily Content

Suppose you're running a blog where the frontpage is the most recently-posted article. Joel Spolsky's blog can serve as a good example: http://joelonsoftware.com/.

In this example, on page load, you should set Betterlink's permalink as the address of the source article. For a more complete solution, you may need to account for multiple articles on the same page.

Permalinks + lazy-loading

In some instances, it makes sense to delay loading content on your page until other more-important content has loaded. Comment threads are a common example of content that loads after a user has scrolled far enough down the page. However, Betterlink will have trouble finding this content when your page is loading.

Sometimes these comment sections, especially third-party solutions, have their own permalinks or other parameters that can be added to your page URL to force the content to load early. If you supply these same parameters to Betterlink as part of betterlink.config.permalink, then visitors will have no trouble finding your content.

Tactic 2: Fragment Identifiers (Hashes)

Fragment identifiers are a technique that often allow a webpage to load dynamic content. You can see examples of this on the Betterlink homepage -- each of the small Frequently Asked Question links uses a URL with a fragment identifier to update the page. For example: http://www.betterlink.io/#placement-tips. That #placement-tips is the fragment identifer (often called a hash).

Hashes + pagination and dynamic content

Betterlink has special configuration option, preserveHash, that lets us load dynamic content on webpages. With this option, we'll be able to load URLs like http://www.betterlink.io/?bl-sid=4#internationalization (notice how it contains both a Betterlink Selection ID and a hash) to use Betterlink on pages that require a hash to show the desired content.

Unlike the previous permalink option, this feature must be enabled before Betterlink's initialization. Since inititalization happens automatically, we'll need to take a few extra steps for setup.

  1. Use betterlink-bespoke.js
  2. Set preserveHash
  3. Call Betterlink initialization

1. betterlink-bespoke.js is a special build of Betterlink that pauses initialization and allows us to set configuration options. Using it is easy: simply replace your request for betterlink.js. The full path can be found at:

    //code.betterlink.io/betterlink-bespoke.js

2. After Betterlink loads, set the appropriate configuration option.

    betterlink.config.preserveHash = true;

3. Finally, initialize Betterlink. In the below example, we're additionally passing an initialization option into Betterlink to inform us of the source of the script (for example, within the source of the page, instead of injected by a Chrome Extension).

    betterlink.init({setScriptSource: 'within source'});

To make our lives easier, this type of implementation is best executed with a Script Loader. Below is a simplified version of the script that is used on the homepage for betterlink.io.

    <script src="//cdnjs.cloudflare.com/ajax/libs/labjs/2.0.3/LAB.min.js"></script>
    <script>
      $LAB.script("//code.betterlink.io/betterlink-bespoke.js")
          .wait(function() {
            betterlink.config.preserveHash = true;
            betterlink.init({setScriptSource: 'within source'});
          });
    </script>