Quick Start Troubleshooting

Common issues resolved for the Quick Start wizard

I’ve gone through the installation steps, but the module is not appearing

  1. Code is missing or erroring

    Open the developer tools on one of your article pages and check for our code in the head and the body. Performing a text search for bib- will likely reveal us. If it’s all there, check for error messages in the Console. This will help you solve the issue.

  2. Domain has not been whitelisted

    You need to whitelist the exact domain you want to use Bibblio on, including staging sites and subdomains. The whitelisting is case-sensitive, so mydomainname.com will work but MyDomainName.com will not.

  3. Unable to determine canonical URL for auto ingestion

    Check out how to specify a customUniqueIdentifier, or add a canonical tag.

    We use canonical urls to automatically generate post IDs which are essential to index your content. If you don’t have canonical URL tags, it’s very helpful to create one for your posts (and not just to use Bibblio!). You can however still use Bibblio without them by providing your own set of IDs.

    Not sure what the deal is for your site? Open your dev console on one of your article pages and do a search for “canonical”. It should look something like this:

    <link rel="canonical" href="https://www.bibblio.org/blog/making-most-of-every-page">

  4. Error returned is "customUniqueIdentifier must be unique or null"

    This is normal when you first install the module, or on an article that has just been published. You should wait 10-15 minutes, clear your cache and recommendations will appear. If you feel like you’ve been waiting a while, make sure at least five URLs have been visited on your site or get in touch with support.

  5. The module is ad blocked

    If you added our code snippet using Ad Inserter or a similar plugin, chances are our module will get ad blocked. Simply revert to adding the code via an HTML inserter or directly to your template.

The recommendations are linking to my staging environment

We recommend using two accounts for live and staging. If you want to use the same email address for both accounts, use the + function, if your mail system permits. For example, jane.smith@mail.com and jane.smith+staging@mail.com.

If you want to keep one account only, you need to clear your content so you can start fresh before deploying your site to your live environment.

My recommendations aren’t relevant to the content

If you applied a recency boost, you may want to decrease it to keep a good balance between recency and relevance.

Bibblio uses machine-learning to predict which items are most likely to get clicked on: the recommendations improve overtime as we get feedback from user interaction. There may be an initial "cold start" period when you first install Bibblio and don't have a lot of traffic. If that's the case, you can revert to a non-optimised algorithm by adding data-recommendation-type="related" to the div tag in your snippet of code.

I'm seeing non-article pages appearing as recommendations

We use the div snippet you've added to your site to import your pages to your Bibblio account and generate recommendations. This div snippet will import every page it loads on, so make sure you're only adding it to a location in your theme that corresponds to the content you want to display in the module.

If you only want articles to appear in the module, make sure our snippet is placed in the appropriate content template. If you are using the same template for different types of content (for example, videos and articles) but only want Bibblio to index some of that content you’ll need to specify a condition to selectively load our module on the right pages.

You will need to ask us to delete your contents once you’ve made the changes so we can re-ingest again.

My thumbnails are displaying a gray image

The module defaults to a gray background when we have not found an image in your article. If you don’t have any images, you can change to a text-only display with your own CSS, or add some generic images to the background of your Bibblio tiles.

For example, you could some generic stock images that would suit the site's type of content. You can resize them to around 500px and compress them so they aren't too heavy.

You can then add the following custom css:

.bib__link--1 .bib__image {background-image: url('https://site.com/image1.jpg');}

.bib__link--2 .bib__image {background-image: url('https://site.com/image2.jpg');}

.bib__link--3 .bib__image {background-image: url('https://site.com/image3.jpg');}

If you do have images in your posts but we didn't import them, this may be related to how they are being added to your template. Did you insert your images using a content container that executes JS? Did you implement lazy loading? In order to import your content to Bibblio as quickly as possible, we use a crawler that does not execute JS on its first attempt. Any images inserted this way may not have been picked up.

My recommendations are too old.

Use the recency setting to remove older articles from appearing in the recommendations. The recency slider is located in the Content tab of your Bibblio account. Any changes to the recency setting will take up to 24h to apply.

Enabling the recency setting has two effects on a corpus:

  • Boost: Content published within a chosen time-frame will receive a “boost”, making it more likely to appear in the recommendations.
  • Truncation: Content published before the truncation period will still display recommendations but will not appear in the recommendations.

You can refer to the following table when deciding on your own boost setting:




The module is recommending the page I'm currently on

Each item imported to Bibblio gets its own Bibblio content item ID, which we use to ensure a content item cannot appear in its own set of recommendations. If you're on a page and see the same content item appear in the recommendations this means the same page has been imported twice to Bibblio with two different Bibblio IDs. Read the next section to find out how to solve this issue.

I'm seeing duplicates in the recommendations

The following things could be causing items to be imported several times to Bibblio:

  1. Switching from the Wordpress plugin to Quick Start

    If you were previously using our plugin but recently made a change to our Quick Start code, you need to make sure your storage is empty before making the switch to prevent items from being imported twice. Visit this page to find out how to delete a catalogue.

  2. Same content, different URLs

    You might have the same piece of content published under two different URLs on your site, for example https://www.domain.com/my-article and https://www.domain.com/category/archives/my-article

    Unless these have the same canonical tag our importer will treat them as two separate items. To prevent this from happening, either make sure they share the same canonical value or place our snippet in a section of your theme that will only import one content type.

  3. Changing your canonical tag or customUniqueIdentifier value

    Our standard snippet looks for the canonical tags on your URL pages to create unique ids for the items you've imported to Bibblio. Changing that canonical tag will cause our code to think this is a new item and will therefore import it a second time.

    If you've supplied your own set of ids via the customUniqueIdentifier field, make sure that value doesn't change when an article is updated on your site.

The module is pulling the wrong image, author or date etc.

The crawler used by our Quick Start code is designed to work across a wide variety of sites, from news publishers to e-commerce sites. However, because each site is unique, it can sometimes miss out on the right data to extract. If you feel the Quick Start snippet regularly imports your posts with the wrong title, image, publication date, or author, contact support so we can fix it on our side.


If you haven't found the answer, perhaps our Quick Start FAQ or our Quick Start Installation Guide can help.