Developer experience

Introduction

This guide aims to introduce you to Bloomreach content as a developer and help you get up and running. It focuses on a technical developer audience and the SaaS version of Bloomreach Content.

📘

Sign up for the Content SaaS Developer Foundations course at Bloomreach Academy! The course is designed to get developers like yourself ready and able to work on their very first project with Bloomreach Content.

There are regular live classes as well as an on-demand class to do at your own pace.

High-level overview

Let’s dive right into it. You have been granted access to a dedicated Bloomreach Content account (login URL, access credentials, and more). Upon configuring your password, you can log into the Bloomreach Content UI at the login URL.

👍

If your organization doesn't have a dedicated Content account yet, you can use the public trial environment.

Channel templates

If you navigate to the Experience manager app in a brand new Bloomreach Content account, you will find that there aren't any channels yet. However, Bloomreach Content provides channel templates for several different storefront integrations. Each template can be used to bootstrap a fully functional channel complete with pre-populated site configuration and a generic, hosted and shared frontend SPA, such that you can manage content and configuration of that channel through the Bloomreach Content UI. Try it out!

Reference SPA + channel

One of the channel templates uses the Reference SPA, a generic React-based commerce integration including pre-populated site configuration and a generic SPA frontend.

Throughout the Bloomreach Content documentation, you will find that instructions, examples, and tutorials are based on this Reference SPA. However, all documentation should be equally applicable to the other available storefront integrations with only minor adjustments. Specific instructions for individual storefront integrations are available on their respective documentation pages.

Local SPA

We expect the first thing a new Bloomreach Content developer might want to do is to get started with their own frontend application. To do so, retrieve a copy (git clone) of the Reference SPA, so you can run it locally and make and test your changes. Check the Reference SPA’s README for instructions on how to run it locally. By using a clone of the Reference SPA, you don’t have to worry much about the Bloomreach Content configuration just yet, so you can get acquainted with the SPA SDK used by the SPA, as well as the Delivery API output.

For the local SPA to work, you need to tell it how to access the back-end (Delivery API), and in order to be able to manage content and configuration of your SPA, you need to tell Bloomreach Content how to load your local SPA into the Experience manager app. The former is done through the SPA’s .env file. The Delivery API's Pages endpoint base URL will look like <your-brx-host>/delivery/site/v1/channels/brxsaas/pages. The latter is done by creating a new Development project in the Projects app, associating the desired channel(s) with it and setting a project- or user-specific “SPA URL” for the Experience manager app to load.

Custom configuration

When you’re familiar with how the SPA interacts with the Bloomreach Content back end, you’ll reach a point where you want to make more significant changes to the back-end configuration than what you can do in the Experience manager app only. You’ll want to start making developer changes. Developer changes can include updates to site configuration, such as adding a new component to the catalog via the Site Management API or simply rearranging components in a standard page template. You can also change content models or edit the content itself, and test this alongside your configuration changes before updating the live production site.

Site configuration

Site configuration is accessed and updated through the Site Management API or using the Site development app, a GUI layer on top of the API. You can access the API at <your-brx-host>/management/site/v1/channels. You need to obtain and use an authorization token. You can explore the Site Management API in our API reference. Your changes to the site configuration will be associated with the developer project created when setting up your local SPA, and you must select that project when previewing your changes in the Experience manager app.

Content modeling

Content modeling, i.e. defining the content types you need in your Content module, is exposed through the content type editor. You can access it in the Bloomreach Content UI. Navigate to the Content app and then select Content types from the Documents drop-down. 

The content type editor links changes to content types with an in-progress developer project. At this time, only one developer project at a time may include content type changes.

Reviewing and publishing your changes

When your changes to the front-end and the back-end configuration have been completed, you want to integrate them into your live workspace in a controlled way. Use the Projects workflow to do so: first, deploy your new version of the frontend to a publicly accessible URL and update the channel’s frontend URL to point to the new version of the SPA. Ensure that the SPA works as expected. Next, put the project into review state and have it reviewed and approved. Finally, merge your project into the live workspace. You should now be able to access the new frontend outside of the Experience manager app while it successfully connects to your updated Bloomreach Content backend.