Increasing FAQ content flexibility with a native UI and Prismic

Towards the end of 2020, at Qonto, we moved to using Intercom as our customer service platform. This meant finding a new solution to provide users with an in-app FAQ. We took this opportunity to improve the FAQ’s user experience by building a custom user interface (UI) while using a content management system (CMS) to edit content. This article explains how we revamped our FAQ and share some details about the Android implementation.

Why build a custom FAQ?

The previous FAQ in our app was powered by our previous customer service platform’s SDK. We felt it had some flaws that could be fixed by implementing our own solution. We experienced some crashes over which we had no control as they happened inside the SDK. Available styling and theming configurations in the SDK were limited which caused the FAQ user interface to be inconsistent with the rest of the app. Increasing consistency by overriding SDK XML resources is possible but leads to very brittle code.

To illustrate this, let’s look at a screenshot of the FAQ main screen. We see that the See all 10 articles button is too small to be read.

Previous FAQ with difficult to read button

When looking at the following FAQ article, we notice that the formatting is somewhat basic. There are only titles, section titles, and paragraphs, which makes reading an article rather tedious. These UI issues were not easy to solve with the SDK we were using due to its lack of flexibility regarding theming.

Previous FAQ article with outlined parts

Taking back control

To solve these shortcomings, we decided to build a custom UI and use Prismic, a headless CMS. Prismic lets product and marketing teams manage content without a developer’s intervention. At Qonto, we are big fans of Prismic, so much that the web front-end team recently open-sourced an Ember package to easily render content from Prismic.

Fetching an article

Prismic provides an API to query the content created by our product marketing and customer success teams. Fetching data requires configuration and adding mandatory query parameters to each request to handle things like localization. We built a PrismicClient class to manage interactions with the Prismic API and abstract the API complexity behind a few functions.

Article UI representation

The screenshot shows the different parts of an article from the new FAQ.

New FAQ article with outlined parts

The different parts outlined are :

1. Heading 1
2. Paragraph
3. Heading 2
4. Paragraph
5. List item
6. List item
7. Paragraph

To display an article, we first had to create its UI representation. We came up with a UI model consisting of a list of “article part” items. An article part can be either some text or an image. The Text sealed class contains a child for each type of text we want to render (heading 1, heading 2, paragraph, list item, etc.). The FaqArticleUiModel is what the view model exposes to the fragment.

Each Text child specifies its style via the textViewStyle property. The text property contains the text to display while spanItems are a representation of Android Spans applied on top of the textViewStyle.

Displaying an article

Displaying an article is done by plugging the article UI model into a RecyclerView backed by a FaqArticleAdapter.

In the rest of the article, we will focus on what it takes to display text article parts. FaqArticleAdapter displays a list of FaqTextArticlePartViewHolder.

The following diagram sums up the architecture used to display an FAQ article:

Custom FAQ architecture

Formatting an article

With a single ViewHolder to represent any text, how do we achieve displaying different text types? Unfortunately, it's not possible to programmatically change the style of a view. Since our textViewStyle is essentially a text appearance and a line spacing extra, we use a combination of setTextAppearance and setLineSpacing to achieve the same result.

Now, what if our content editors want to use bold text to draw the user’s attention? We need a way to get information on the text to highlight. In the Prismic response, each text item optionally contains a list of spans. To render the text:

Some important information coming from Prismic

The Prismic API response would be:

We map spans to classes based on the type property: "strong" to Bold, "em" to Italic, and so on. start and end determine the index range that should be formatted. The previous JSON is mapped to FaqTextSpanItem.Bold(startIndex = 5, endIndex = 26).

ArticleTextFormatter processes these spanItems and outputs spans which contain the required formatting information.

1. We create a SpannableString from the text String to be able to insert spans. Spans hold the formatting information. If you want to know more about spans, there is an in-depth article on the topic from Florina Muntenescu.
2. We create a span from our span item. For instance, FaqTextSpanItem.Bold is converted into StyleSpan(Typeface.BOLD)
3. Finally, we apply the span to the spannable created during step 1.

What did we achieve?

Here you can see the same article as shown previously:

New FAQ article

We notice a few things compared to the previous FAQ we had using a third-party SDK.

1. We can display a breadth of text types (heading 1, heading 2, heading 3, paragraph, bullet point lists, numbered lists)
2. We have multiple formatting options to highlight text parts: bold and italic
3. Vertical spacing between text blocks makes the overall article clearer

We gained a lot of flexibility by implementing the FAQ UI ourselves. Articles are easy to read and users can quickly find relevant information.

What did we learn?

It’s easy to let a third-party SDK handle our in-app FAQ and consider it as an afterthought. That’s what we did for a while until we realized our users would greatly benefit from an improved user experience. Freeing ourselves of a third-party SDK constraints gave us the flexibility required to create and display content worth reading. Looking back on our endeavor from a developer’s perspective, the engineering effort we invested was well worth it. The Android implementation is fairly straightforward and will allow us to handle ever-evolving requirements in the future such as adding new item types inside an article. Building a custom FAQ and using Prismic allowed us to focus on giving our users an improved app usage experience while giving our product marketing managers the tools to create quality content for our users.

About Qonto

Qonto is a neobank for SMEs and freelancers founded in 2016 by Steve Anavi and Alexandre Prot. Since the launch in July 2017, Qonto has made business banking easy for more than 150,000 companies. Thanks to Qonto, business owners save time (streamlined account opening before a day-to-day user experience with unlimited history, accounting exports, expense management feature), have more control while giving their teams autonomy (real-time notifications, user right management system) and have improved visibility on cash-flows (smart dashboards, transactions auto-tagging, and cash-flow monitoring). They also enjoy stellar customer support, at a fair and transparent price.

Interested in joining a challenging and game changer company? Consult our job offers!