dc-content-managed-pwa-nextjs

This project is a sample React / NextJS application using Amplience Dynamic Content for content management.

Features

Content types that represent the content managed components
Fetch content from the Content Delivery API
Connect content to component props
Dynamically render components based on content
Automation of Content Schemas and Content Types using the Amplience CLI
Support for visualisation and time based preview

And a few niceties:

Dependencies

This project has various dependency packages all listed in the package.json files which include node and yarn. If you do not already have yarn, you can follow the online documentation and installation type of your choice here.

Getting Started

After you checkout the project, you can install the dependencies as follows:

yarn install

Project Packages

This project is a monorepo and contains two sub-projects:

packages/client

This package is the application itself, you can run it as you would any NestJS app:

yarn run dev

Which will launch the application on http://localhost:3000.

Storybook

The client package also contains Storybook for simple component UX showcase & editing. The components that make up the client app have been documented using Storybook. You can access this by running:

yarn run storybook

packages/configuration

This package is a set of configuration files that help automate setting up your Dynamic Content hub.

Guide to to setting up this application on your own account

By default, the application is loading its content and media from an Amplience demonstration sandbox for your initial tests. If you have your own Amplience account which you would like to use end to end, please follow the steps below.

Amplience Account Pre-Requisiites

You will need the following to set up this demo in your own Amplience account:

An Amplience account with access to Dynamic Content.
Your Amplience account should have Content Delivery V2 enabled.
Your user account should either be a Developer or an Admin to allow you to create content types.
Management API credendials (ClientID & Secret).
Your Amplience Hub ID which you will be using.
Your Content Delivery V2 publishing endpoint domain.

If you do not have any of these, please contact your Customer Success Manager or Amplience support directly.

Application Configuration

If you want to connect the app to your own hub rather than the demo account you need to update next.config.js. to your account CDV2 publishing endpoint domain (excluding protocol).

env: {
    contentApi: '<add your content publishing domain here>'
}

When you run your application this will now display dummy content asking you to have content with delivery keys. The application is now pointing to your account.

HTTPS visualisation

Amplience is a secure platform and does not allow embedded apps which are not delivered via SSL. However, you can preview by opening your visualisation away from the Amplience appplication by clicking the 'open in a new window' button.

Some options to enable your app SSL:

Deploy and host on an SSL server supporting SSR.
Create a localhost certificate and set your browser to trust. There are many guides available online such as this
Ammend your localhost application to run a HTTPS server.

Content Types and Content Schemas

As mentioned above, this is a monorepo. Under packages/configuration you will find the following sub folders:

content-schemas: These are your content models in JSON-Schema format. These content models map to components and also slots.
content-types: These are your settings for your schemas for use in Amplience. They contain names, icons, visualisations and which repositories they can be used in.
content-type-schemas: These tell the Amplience CLI how to provision your content types and schemas.

Import automation

You can automate the import of schemas and content types directly from your local machine using the Amplience DC CLI.

In your command line interface change directory to packages/configuration.
If not already installed, install the CLI using node package manager:

npm install -g @amplience/dc-cli

Check install

dc-cli configure --help

Configure your CLI with your account details ( clientId, clientSecret, hubId) by running the following with your credentials:

 dc-cli configure --clientId <YOUR_CLIENT_ID> --clientSecret <YOUR_CLIENT_SECRET> --hubId <YOUR_HUB_ID>

A message will display to say that you have succesfully configured the CLI

Sync to your account

yarn run sync

Your account will now be populated with the relavant Content Type Schemas and Content Types ready to use.

Manual import

You can also manually create your schemas and content types in the Amplience UI if you do not wish to use the Amplience CLI.

Content Creation

There a 4 content types included in this project to start:

Editorial Block
Gallery Block
Hero Banner Block
Navigation

In your content repository, we recommend that you create test content for each of the components listed above. See guidance for Content Creation.

These content types have been enabled with 2 visualisations:

PWA (Localhost): This points to your application to visualise the content as your application would render it.
JSON: This gets JSON content which an application would use directly from the Delivery APIs.

Both have parameterised substitution values for the domain to load content from (Staging content) and the id of the content to load.

Slot Creation

The application functions by loading content from Slots which map to locations on the PWA. See guidance for Slot Creation.

In this application there are 2 slot types:

Navigation Slot: Can hold a single piece of navigation content.
Page Slot: Can hold an ordered array of content. Accepted types of content are listed in the Page Slot Schema which include:
- Editorial Block
- Gallery Block
- Hero Banner Block

In your slots repository, create the following:

Instance of your Navigation Slot: With your example navigation content. You should also set the delivery key that your application is expecting for the navigtion which is slots/navigation.
Instance of your Page Slot: With one or many of your components. You should also set the delivery key that your application is expecting for the page which is slots/homepage-hero.

If you would like to see your application running from here pointing to the content that you have placed into these slots simply publish your 2 slots and go directly to your application at:

http://localhost:3000

Full application Preview

Amplience enables customers to plan and preview content in their applications through the context of time using the planning functionality in the marketing calendar.

Amplience Preview Configuration

This step gives a pointer to your application in the Planning calender.

Log into Dynamic Content and Navigate to: Settings --> Preview and add a preview application with the following URL and a label for your application (ie, 'PWA (Localhost)'):

http://localhost:3000?contentApi={{vse.domain}}

Relevant preview documentation can be found here.

Now you can create your marketing calendar with Campaigns (Events), Time based content drops (Editions) and choose where content is going to go at that time (Slots) with the abiliy to preview your content before it is published and schedule to automatically deploy.

Typical flow:

Create Event (Campaign)
Create Editions (Drops of content)
Assign slots (Navigation & home)
Put content into slots
Preview / Schedule
Auto publish on schedule

Guideance for using Planning.

Deploying your application

This application uses server side rendering, you should choose a hosting provider that supports SSR and SSL.

Some options but not limited to:

Once deployed you may also choose to ammend / add additional options for visualising and previewing your application which you can do manually in Dynamic Content or automatically using the CLI tool.

Areas of change: In packages/configuration/content-types/:

Change the domain of your cards to your hosted application.
Change or add an additional visualisation to point to your hosted application. You may wish to make the hosted version your default.

In the Dynamic Content application you may also want to change or add an additional preview URL pointed to your hosted environment following the steps in here.

License

This software is licensed under the Apache License, Version 2.0,

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

sweetenr / dc-content-managed-pwa-nextjs Goto Github PK