API FAQ

Help with enrichment and discovery

Can I try Bibblio on my staging account?

Yes, you can. We recommend keeping two separate accounts for your staging and live environments, or alternatively contact us so we can clear your catalogue once you’re done testing. This is to avoid recommendations on your site pointing to staging URLs.

What is discovery?

When we speak about discovery, we mean the process through which a user finds and interacts with content, whether that’s by traditional search, on-platform content recommendations, or in the form of a personalized newsletter.

What is a recommendation key?

Recommendation keys are Bibblio’s own access tokens you will need to access recommendations.

These keys are distinct from the standard OAuth mechanism for two important reasons:

  1. they only allow for the retrieval of recommendations and submission of recommendation-specific tracking activities. Recommendation Keys cannot be used to alter your account in any way. This makes them safe to expose on your website.
  2. they do not need to be regenerated for every request and can therefore be cached by your web servers. This allows you to continue leveraging any performance optimizations you may have implemented.

Which part of my content do you use to generate recommendations?

We only use the text to generate metadata. All other information you send us (tags, keywords, type of resource, etc) will not affect the indexing and is only there to organise your content and give you control over what you want to display on the module.

Does Bibblio use a content delivery network for serving the assets, or would Bibblio be serving them from my server?

We serve our assets via our own CDN for a faster installation and easy access to latest versions. If you would like to host the assets yourself instead they can be installed via Bower and npm.

We store the source URL and module image URL when you add the content, so we can easily populate the module and don’t double up on server storage. When the user clicks, we simply send the user to the original content URL.

How can I add Bibblio’s pre-built recommendation modules to my content pages?

Read our guide on how to get started.

Do I have to use your modules?

We recommend using our elegantly designed modules that are ready to go and fully customizable, for a faster installation. You can use CSS to override our style classes and make it match your site’s design. We track user behaviour and generate analytics stats through these modules, meaning you will immediately get visibility over the module’s performance from the moment it is live on your page.

When doing an API integration you can also build your own module but you will have to send us tracking events in order to get the recommendations to improve over time.

How do I need to format content for Bibblio’s API?

Content needs to be formatted in valid JSON to be pushed to our API via a POST request.

Is there a maximum file size for content?

The maximum size for an individual item of content is currently 200 KB.

When creating a content item, do I need to send you information for all the attributes listed?

We only require the following fields in order to generate recommendations: “url”, “text”, “name”.

We strongly recommend you add an image in “moduleImage”, and the “datePublished” if you are planning on using our recency parameter. A little excerpt of the article in “description” is also a nice-to-have if you’re planning on giving more information to the user when they hover over a recommendation.

The rest is entirely up to you and will depend on your internal taxonomy. Most of our API users supply a “customUniqueIdentifier” to match our content items to their internal blueprint.

I want to send you some information that does not match any of these attributes. How do I do that?

We follow the Schema.org CreativeWork format for attributes on content items. If you want to send us some information about a content item that does not correspond to any of the ones we already have, let us know which one and we’ll look to incorporate it in the next release.

How do I separate my content into groups?

Content items can be grouped into what we call ‘catalogues,’ which means you can organise your content to ensure that certain topics and genres are only recommended on certain parts of your platform. It can also be useful if your site supports different languages. Learn more about catalogue management.

Still haven't found what you’re looking for?

Please get in touch. We’ll get back to you as soon as we can.