Introduction

Base synchronization ensures the locally hosted copy of a base used by a deployed experience matches the cloud-hosted master version of that base. This synchronization process occurs in one of two ways:

1. Automatic base synchronization when an experience is first run. This sync process is unavoidable.
2. Requested synchronizations initiated by a trigger. This sync process occurs at the moments specified by the Composer user.

Whenever these occur, displaying content informing the user that they need to wait for an update to complete is a good practice. This is accomplished using the Sync triggers and actions available with every instance of a Headless CMS Interface Asset. 

Experience launch: Waiting for synchronization to complete

Synchronization between the local copy of a base and its cloud-hosted master always occurs when an experience first launches. This synchronization can take a while, so we recommend implementing a "loading screen" using a dedicated scene or an experience layer to display a message until the sync process completes.

In this example, we've created a "Sync scene" displayed whenever H-CMS base loading/synchronization occurs.

The "Sync scene" is the first scene displayed when the experience runs. Associated with this scene is a "Has been entered" trigger, which calls the "Sync local base" action. Even though the initial synchronization occurs automatically, we add this action so the scene can be used at later times during the experience run.

To explicitly warn the user that experience content is being loaded, the "Sync scene" should contain some message/animation informing the user that content is loading. This information can be displayed right away, or its appearance could be caused by the "Sync started" trigger.

Use the "Sync completed" trigger to identify when the sync process has been completed, and then navigate to the first content scene using the "Go to scene" action. You may also want to consider adding an alternative trigger/action pair for the "Sync failed" trigger in case of a synchronization problem.

Triggered synchronization

Other than after the initial launch of an experience, base synchronization will not occur automatically. What you can do is identify moments when synchronization can safely occur - such as when the experience times out due to lack of interaction - and use that moment to send the experience to the "Sync scene", causing another synchronization.

More information about triggered synchronization is in our article about using Headless CMS in an experience.

Experience launch: display the base synchronization progress in percentage

You can use the the HCMS Sync percent completed property to display the progression of the base loading in percentage on your loading/waiting screen scene. 
This property can be accessed through a binding available from the HCMS base X-Ray panel.



You can add a sync in progress trigger at the HCMS base level that will display the percentage completion of the base with a Set text action targeting a Text Asset.



To display the percentage symbol, you just need to add a Binding Converter with a simple Text Manipulation Concatenate converter.

Sample

You can download a sample showcasing these synchronization examples by clicking this link.

Video Explanation - Synchronize the local H-CMS base

You will find in the Quarterly Q&A Live - Summer Edition 2023 video, a detailed example of how to ensure the synchronization of the local Headless CMS base before permitting experience interaction.