Gravatar for magnus.pihl@gmail.com

Question by Magnus, Oct 13, 2017 11:46 AM

Custom UI Components: What API calls should be made

For our current project, our frontender would greatly prefer to build our own UI components from scratch, rather than using the Coveo search-ui framework. This is due to wanting to minimize our toolchain, avoid libs we don't otherwise use, and having more tight control over presentation.

When I attended a Coveo training course I was strongly discouraged from doing this, however, since the coupling between the UI and API code in search-ui is so tight.

I'm not terribly worried about the actual search results, but when it comes to analytics and other "behind the scenes" logic, I'm a little more apprehensive.

Is there any documentation that outlines which API calls should be made to which endpoints to enable the same analytics features that search-ui implements?

Are there any other endpoints than search and analytics that I should call?

4 Replies
Gravatar for sbelzile@coveo.com

Answer by Sébastien Belzile, Oct 13, 2017 12:51 PM

Still trying to discourage you from doing this: the majority of people we have seen doing this get site with a less than ideal search, and/or poor relevance, and/or missing some key features.

Before answering your question: somebody is currently writing documentation about this internally. Should be available in a near future.

Answer:

You can find the UA API documentation here. What the UI for UA is quite simple: they log what happens in the interface (clicks and searches). The API to log these events is intuitive enough for that purpose: use the click endpoint to log a click, the search endpoint to log a search result, etc. If you get stuck, you can still have a look at what the JS UI does.

The search API is documented here.

> Are there any other endpoints than search and analytics that I should call?
Not from the UI.

Gravatar for olamothe@coveo.com

Answer by olamothe, Oct 13, 2017 1:01 PM

Hello,

You are right that basic functionalities should be very easy to implement. Getting a list of result with a searchbox would be extremely easy to implement. Like in any other software project, getting 80% of the way there will be easy, the last 20% will take time and effort.

For Usage analytics, @Wim Nijmeijer is currently working on providing examples and "gotchas" that partner that want to implement their own UI would need to follow. So this should be pretty helpful for you.

The other advanced feature in the Coveo API is the API that powers the facets. Those are called group by requests. They are documented ( see : https://developers.coveo.com/display/SearchREST/Group+By+Parameters and https://developers.coveo.com/display/SearchREST/Group+By+Results ).

But this only explains "what" they are, not really "how" to use them. This is something that we are aware is lacking in the documentation, and that we want to fix. But in the meantime, this is what is available.

To get multi selection in "OR" working properly in facets, for example, you will need to dig pretty deep in the API to understand how it all work with "query override, constant query override, etc.". Once again, if you only wish to have simple filtering capabilities, it is relatively easy to implement. Implementing the more advanced features could take you a lot of time, though.

Gravatar for wnijmeijer@coveo.com

Answer by Wim Nijmeijer, Oct 16, 2017 1:28 PM

Hi. I still totally agree with Sebastien. We strongly advise to use our OTB JS UI.

This page will show you what kind of events you need to make it all to work.

sendanalyticspublichtml.zip

Gravatar for dbouffard@coveo.com

Comment by Dave_Bouffard, Jan 25, 2018 9:58 PM

@Wim Nijmeijer. We are working with a customer on a GSA replacement for which we will be implementing Coveo using their UI (100% custom, in a AEM site) but the Coveo API. In 99% of the cases, you are all right. Much better to use the JS UI Framework.

In their case, they are not using any GSA UI components, they have a huge quantity of logic/business tools UI side and they have a tight deadline. But, the search call that they are doing against GSA are very simple. They do not use facets, tabs or any fancy stuff. In this specific scenario, the GSA calls can easily be replaced by Calls to Coveo's Search API (successfully tested this week), and it's the way we are going to do it in order to meet their February deadline. We will need to implement Coveo Usage Analytics event in their UI (in addition to their existing tracking system). In a later phase, we will be replacing the whole UI and client side logic with Coveo components (JS UI, pipeline, client side code using Coveo events).

The html page and code you provided is exactly what we need short term! Awesome job !

Is it the latest version ?

Gravatar for magnus.pihl@gmail.com

Answer by Magnus, Oct 16, 2017 3:00 PM

Thanks, everyone, for your answers and recommendations.

Whether I end up using the OTB components or not, I appreciate understanding what's going on behind the scenes.

Ask a question