Preview configuration

Jan Cerman, David Klement

10 minutes

Preview

Download PDF

Set up content preview for your Kontent.ai projects so that your content creators can preview unpublished content and review it with confidence.

Explore your path to mastery

Reap the benefits of preview when setting up your website.
Take your preview to the next level with Web Spotlight.

Preview your latest content via API

Start by teaching your app how to fetch the latest versions of your content. This means making requests to Delivery Preview API. Every request to the API must be authenticated with a Delivery API key. Remember that server-side technology is required to keep your API keys secret.

To create Delivery API keys for previewing content, you need to be a Project manager. Here’s an example of how you can get the latest version of a My article content item:

Java

// Tip: Find more about Java SDK at https://kontent.ai/learn/java
import kontent.ai.delivery.*;

// Initializes a DeliveryClient for preview
DeliveryClient client = new DeliveryClient(
    DeliveryOptions.builder()
        .projectId("<YOUR_ENVIRONMENT_ID>")
        .previewApiKey("<YOUR_PREVIEW_API_KEY>")
        .usePreviewApi(true)
        .build();
);

// Tip: Create strongly typed models according to https://kontent.ai/learn/strongly-typed-models
// Registers the model class for articles
client.registerType(Article.class);

// Gets the latest version of an item
CompletionStage<Article> article = client.getItem(
    "my_article",
    Article.class
);

Prepare your app for preview

When your app can display the content it gets from a Kontent.ai project, the next step is to prepare your app for previewing unpublished content. We recommend using Delivery SDKs to make all this easier. To follow the best practices and avoid using your production app for fetching non-production data (preview), you need two separate instances of your app:

Production instance: Fetches published content via Delivery API. This instance serves content via example.org URL, for example.
Preview instance: Fetches the latest version of your content, even if it's not published yet, via Delivery Preview API. This instance serves content via preview.example.org URL, for example.

You can distinguish the instances by providing or omitting the Preview API key. If the key’s present, your app will run the preview instance, if it’s not, that’s a sign to run the production instance.

Secure your unpublished contentWe highly recommend implementing an authentication system for your preview URLs to secure unpublished content. You can use single sign-on (SSO), password protection, or any other form of authentication. This important step ensures the confidentiality of your unpublished content, which only authorized individuals can access before the content gets published.

Set up multiple previews with spaces

Check out how to set up multiple previews in your project.

Define preview URLs for content types

To preview your content, you need to set up preview URLs for your content types. The URLs may be different for each combination of space and content type.

In Environment settings > Preview URLs > Preview URLs for content types, click Set up preview for a content type.
Select a content type.
In Used in spaces, select a space you’re setting the URL for.
- If you don’t use spaces, select All spaces. Similarly, use All spaces for a preview URL that’s universal across all your spaces.
Type in the preview URL.

The preview URLs must be:

Absolute paths in the format https://domain/path
Shorter than 1024 characters

Use a secure connectionPreview URLs require the https:// protocol and URLs accessible to Kontent.ai. Without a valid SSL certificate, Kontent.ai responds with secure connection errors. When developing apps locally, you can serve pages over HTTPS

in combination with ngrok

's forwarded address.

Dynamic preview URLs with macros

If you’re setting up URLs that need to be dynamic, there are a few macros you can use:

{Space}: space domain
{URLslug}: content item’s URL slug element value
{Lang}: codename of the selected language
{Codename}: content item’s codename
{ItemId}: content item’s internal ID
{Collection}: content item’s collection codename
- This macro is available if you have collections enabled for your subscription.

You can create SEO-friendly URLs using the URL slug element with the {URLslug} macro: https://preview.example.org/articles/{URLslug}. Alternatively, you can use the {Codename} or {ItemId} macros to identify the content items in your preview URLs. In multi-regional projects, use the {Lang} macro to get the currently selected language codename, such as en-us or ja-jp. You can combine the macros. A preview URL https://preview.example.org/{Lang}/articles/{URLslug} would resolve to https://preview.example.org/en-ca/articles/previewing-content-items, for example.

Multiple content items can have the same URL slugKontent.ai doesn't check if a URL slug value is unique across your project. This means you can have multiple items with the same URL slug. However, if you need unique URL slugs, you have several options to ensure that you don't end up with multiple same URL slugs. Check out your options to achieve unique URL slugs.

Static preview URLs

Your home page, for instance, doesn’t need a dynamic preview URL, because it's static (it's unique and in one location). For example, a home page’s preview URL for an app running at https://preview.example.org would be https://preview.example.org or https://{Space}.

Set up a preview for Web Spotlight

When setting up Web Spotlight, you set up a preview just like you would without Web Spotlight.

Because your app will be loaded and sandboxed in an <iframe> within Kontent.ai, you need to ensure a few things:

Always use a secured connection (HTTPS) for your URLs, such as https://preview.example.org.
Allow your app to load within Kontent.ai using the Content-Security-Policy header and the frame-ancestors directive: frame-ancestors https://app.kontent.ai.
To enable opening external links from your app, such as PDFs stored as assets in Kontent.ai, you need to set sandbox directives using the Content-Security-Policy header. For example, the directive allow-popups-to-escape-sandbox allows opening external links, allow-forms allows submitting forms, allow-downloads allows downloads after users click a link, and so on.
Make sure your web browser allows third-party cookies and that your cookies are designed for a 3rd-party context by setting cookies attributes SameSite=None; Secure.
If you first want to test your implementation locally, you need to generate a self-signed HTTPS certificate.

Web Spotlight and spaces

Web Spotlight uses a content item of the Web Spotlight root content type as its top-level (root) content item. The rest of the tree is under this item. Setting up a preview for Web Spotlight with multiple spaces is no different from setting it up for Web Spotlight in a project with only a single space. You set up the preview for the Web Spotlight root content type and for all the other types under it. Specify different preview URLs for different combinations of spaces and content types.

Set up edit buttons in your preview

Once you have a preview working in both your app and Kontent.ai project, it’s a good idea to add edit buttons to your application. They can look like what you see below.

For content creators, this small addition means they can go straight to editing in Kontent.ai just by clicking the button. This will help them in case they need to fix minor errors or typos right after they spot them when previewing their content. If your editors have problems opening items through the edit links, verify their user roles.