Amplience

Amplience is a content platform for commerce teams. It lets marketing and merchandising staff create, manage, and publish shop content such as landing pages, hero banners, and category teasers without writing code.

The SCAYLE Storefront Application includes a built-in Amplience integration. Your team can build and update content in Amplience Dynamic Content and see it live on the storefront. Content changes do not require a new shop release.

Key Features

• Visual Preview: See how content looks on the real storefront while editing in Amplience.
• Ready-Made Content Blocks: Start from proven layouts for heroes, sliders, text sections, and calls to action.
• Multi-Market Content: Manage separate content for each country or language your shop serves.
• Rich Media: Use high-quality images and video for campaigns, banners, and promotional areas.
• Category Page Content: Add teaser and SEO content above and below product listings.
• Fast Publishing: Publish updates when they are ready, without waiting on development cycles.

Quick Links

• Amplience User Guide
• Amplience Dynamic Content docs

Getting Started

Prerequisites

Before setting up Amplience, ensure you have the following:

• Amplience account: Sign up at amplience.com.
• Dynamic Content hub: Create a hub with Content Delivery 2 enabled for your Storefront Application project.
• Content repository: A content repository with the Storefront content types enabled on it. Repositories store content items and slots.
• Access credentials:
  • Hub name: Used to fetch content during runtime.
  • Hub ID: Used to import and sync content schemas
  • Personal access token: Used to import the content model and generate local types.
• Virtual Staging Environment: Required for preview. See Virtual Staging Environment. Provisioning requires org admin access in the Amplience Account app.

Set up Your Amplience Storefront

The Amplience integration is included with the Storefront Application. To enable and configure it:

Step 1: Configure the Integration

Set the CMS provider and add the required environment variables to your .env file:

bash

Copy

Import the Storefront Application content model into your hub:

bash

Copy

Warning: Importing the content model is only intended for empty CMS hubs. Running it on hubs with existing content may cause issues.

Then pull the content model and regenerate TypeScript types locally:

bash

Copy

Step 2: Review Configuration

After configuration, your nuxt.config.ts will include:

typescript

Copy

The following environment variables are used in your local .env file:

• CMS_PROVIDER (required during build-time)
• NUXT_PUBLIC_CMS_HUB_NAME (required during runtime)
• NUXT_PUBLIC_CMS_LOCALE (optional during runtime)
• NUXT_PUBLIC_CMS_ALLOW_DRAFTS (optional during runtime)
• AMPLIENCE_PERSONAL_ACCESS_TOKEN (required for CLI commands)
• AMPLIENCE_HUB_ID (required for CLI commands)

Step 3: Environment Configuration & Deployment

The Amplience integration uses Nuxt's RuntimeConfig, which provides flexibility for different deployment environments.

Runtime vs Build-Time Configuration

Unlike traditional build-time configuration, most Amplience settings can be set at runtime. This means:

• During development: Set variables in your .env file.
• During deployment: Update environment variables on your hosting platform without rebuilding.
• Different environments: Use the same build for development, staging, and production with different variables.

Note that CMS_PROVIDER is read at build time and determines which CMS module is bundled.

Environment Variables Reference

All Amplience configuration settings can be set via environment variables:

bash

Copy

Production Deployment Checklist

• Set CMS_PROVIDER=amplience before building the application.
• Set NUXT_PUBLIC_CMS_HUB_NAME to your production hub.
• Optionally set NUXT_PUBLIC_CMS_ALLOW_DRAFTS=false in production.
• Keep preview enabled only in development and staging environments.
• Keep AMPLIENCE_PERSONAL_ACCESS_TOKEN and AMPLIENCE_HUB_ID for CLI use only, not in production runtime.
• Ensure all required environment variables are configured on your hosting platform.
• Test content loading in your production environment before going live.

Architecture & Integration

Amplience uses a content-item-based architecture where content is built from reusable content types. Each Amplience content type maps to a Vue component in your application, enabling a seamless bridge between your CMS and the Storefront Application.

Component Mapping Pattern

• Amplience content type Text → Vue component TextComponent.vue
• Amplience content type Image → Vue component ImageComponent.vue
• Amplience content type Section → Vue component SectionComponent.vue
• Amplience content type Product Listing Page → Vue component ProductListingPageComponent.vue

Shop Runtime Integration

The runtime integration between Amplience and the Storefront Application uses the Amplience Content Delivery SDK and a custom Nuxt Image provider for Dynamic Media assets.

The integration additionally relies on the @nuxt/image module to handle images used with Amplience components.

Video Delivery

The Storefront Application Video component uses an Amplience video-link field and Amplience Dynamic Media for playback.

Amplience serves playable video through transcode profiles. A URL without a profile returns the poster frame (or the first frame). A profiled URL such as /v/{endpoint}/{name}/mp4_720p returns the encoded stream.

The Storefront Application does not hardcode profile names. At runtime it:

1. Shows the poster (custom poster image, or the unprofiled Dynamic Media video URL) while metadata loads.
2. Fetches video metadata from the Amplience Media Delivery API:
   https://cdn.media.amplience.net/v/{endpoint}/{name}.json
3. Builds HTML5 <source> entries from the media array in that response (the profiles applied to that asset in Content Hub), ordered by bitrate.
4. Starts playback when sources are ready (or shows a play control when autoplay is disabled).

In Content Hub, apply the required video transcode profiles to each video asset and publish the asset. Profiles available on your hub can differ. If no profiles are applied, or metadata cannot be loaded, the storefront keeps showing the poster and does not attempt playback.

Content Organization Architecture

The Amplience integration uses a delivery key-based approach for organizing content across multiple languages and shops. Understanding delivery keys and naming conventions is essential for proper routing and content resolution.

Delivery Key Naming Conventions

• Use shop locales: Delivery keys must start with the shop locale (for example de-DE, en-GB), not the shop routing code (de, en).
• Homepage: Each locale needs a content item with delivery key {locale}/homepage for the root path (/).
• Content pages: General pages use {locale}/content/{slug} (for example de-DE/content/about).
• Categories: Product Listing Page content uses {locale}/c/c-{categoryId} (for example de-DE/c/c-91825).
• Consistent structure: Maintain the same delivery key pattern across all locales for easier management.
• Path mirroring: Delivery keys mirror your application's URL structure inside each locale.

Delivery Key Structure Example

text

Copy

Routing Mode Integration

The Amplience integration automatically handles delivery key resolution based on your Storefront Application's routing configuration. The routing mode is configured via the SHOP_SELECTOR_MODE environment variable.

All content uses locale-prefixed delivery keys regardless of which routing mode you use.

Path-Based Routing

Configuration: SHOP_SELECTOR_MODE=path

The integration builds the slug from the route and prepends the shop locale.
If the shop locale is unavailable, NUXT_PUBLIC_CMS_LOCALE is used as a fallback.

Domain-Based Routing

Configuration: SHOP_SELECTOR_MODE=domain

The integration determines the locale from the domain and prepends it to the path.

Path-Except-Default Routing

Configuration: SHOP_SELECTOR_MODE=path_or_default

Assuming de-DE is the default shop:

The integration automatically detects the current locale and constructs the appropriate delivery key.

Content Fetching Flow

When a user visits your Storefront Application, the integration follows this flow:

1. Route resolves: User navigates to a URL (e.g., /de/content/about).
2. Delivery key resolution: The integration resolves the route to an Amplience delivery key (e.g., de-DE/content/about).
3. API request: Content is fetched from the Amplience Content Delivery API.
4. Component mapping: Amplience content types are mapped to corresponding Vue components.
5. Rendering: Vue components render the content with proper styling and interactivity.

Visualization Integration

The Amplience Visualization enables you to see changes in your storefront as you edit content in Dynamic Content:

1. Editor detection: The integration detects the vse= query parameter in the URL.
2. Draft content: Draft versions are loaded instead of published versions when preview is enabled.
3. Save and refresh: Changes in Amplience appear after saving and reloading the preview.
4. Click to edit: Rendered elements carry attributes that let the editor overlay locate fields.

Configure Preview Access

To display unpublished changes in the Amplience editor, your environment must have a provisioned Virtual Staging Environment and NUXT_PUBLIC_CMS_ALLOW_DRAFTS=true.

Draft preview requires both the vse= query parameter Amplience injects into the visualization iframe and NUXT_PUBLIC_CMS_ALLOW_DRAFTS=true. Without allowDrafts, the storefront serves published content only. Leave NUXT_PUBLIC_CMS_ALLOW_DRAFTS unset in production.

Configure the Visualization Base URL

To set up the Visualization, configure visualization URIs on your page-level content types in Amplience Dynamic Content:

1. Open Settings for the Page and Product Listing Page content types.
2. Add a visualization entry per environment (for example Local Dev, Staging).
3. Enter your development environment URL (e.g., http://localhost:3000 for local development).
4. Include ?vse={{vse.domain}}&key={{delivery.key}} in the URL template.

Example for pages and homepage:

json

Copy

For Product Listing Page content, use a placeholder category path because the category ID cannot be injected from a custom schema field:

json

Copy

Amplience automatically substitutes template variables when opening preview.

Enable Draft Content

Set the following environment variable to display draft content:

bash

Copy

Visualization Support

Add data-amplience-entry-id and data-amplience-field-id attributes to field-editable elements in your Vue components. This tells Amplience which elements are editable and enables click-to-edit in the preview.

Test Live Preview

1. Open a content item in Amplience Dynamic Content.
2. Click the Preview button.
3. Verify the preview loads correctly.
4. Make changes in Amplience, save, and verify they appear after the iframe refreshes.

Embedding CMS Content in Existing Pages

You can enrich existing Storefront Application pages with CMS-managed sections without converting the entire page to CMS. For example, the Product Listing Page (PLP) demonstrates this pattern:

vue

Copy

This pattern lets you drop CMS-controlled blocks into any page region while keeping core page logic in your application.

Available Components

The integration provides pre-built components organized by function. These components serve as building blocks for your content. You can explore all components in our UI Component Overview.

Core Content Primitives

Interactive & Basic Content Blocks

Layout & Structural

Rich Content

E-Commerce Specific

Guidelines: Content

Create Locale Content Items

Organize your content in Amplience by creating one content item per locale for each page or block. Content items are created inside a content repository.

1. Create a Page content item for each locale homepage with delivery key {locale}/homepage.
2. Create Page items for general content under {locale}/content/{slug}.
3. Create Product Listing Page items per category under {locale}/c/c-{categoryId}.
4. Publish each item after setting its delivery key.
5. Maintain the same delivery key structure across all locales for consistency.

Using Base Components

The included pre-built components provide all the building blocks needed to create common e-commerce content patterns. Compose flexible sections that adapt to your brand and merchandising needs.

Composing E-Commerce Blocks

Hero Banner

Combine these components to create an impactful hero banner:

1. Use SectionComponent with a background image.
2. Add TextComponent for the headline and description.
3. Include one or more ButtonComponent instances for calls-to-action.
4. Use DividerComponent for vertical spacing.

Structure:

Amplience EditorOutcomeOutlinePreview

Copy

Category Teasers / Cards

Create a card grid layout:

1. Use GridComponent with four columns on desktop, two on mobile.
2. Inside each column, add SectionComponent with a background image.
3. Include ButtonComponent to link to the category page.

Structure:

Amplience EditorOutcomeOutlinePreview

Copy

Promotional Slider

Implement a carousel pattern:

1. Use SliderComponent as the container.
2. For each slide, use SectionComponent as a container.
3. Add TextComponent for each slide title.
4. Add DividerComponent as a separator.
5. Include ButtonComponent to drive users to listings or campaigns.

Structure:

Amplience EditorOutcomeOutlinePreview

Copy

Split Image & Text Section

Create a side-by-side layout:

1. Use GridComponent with two columns on desktop, one on mobile.
2. First column: SectionComponent with a background image.
3. Second column: TextComponent for headline/description and ButtonComponent for CTA.

Structure:

Amplience EditorOutcomeOutlinePreview

Copy

Creating Content for PLP

The Product Listing Page (PLP) is a main discovery point in the user journey. Our specialized component allows you to seamlessly inject custom, commerce-relevant content before and after your product stream.

Amplience EditorStep 1

Copy

Amplience EditorStep 2

Copy

Amplience EditorOutcomeStep 3

Copy

Amplience EditorOutcomeStep 4

Copy

Your customized PLP content is now ready to go live.

Guidelines: Development

Customizing Existing Components

You can customize existing components by modifying their Vue implementations to match your design system and requirements.

How Component Customization Works

All Amplience components are rendered through the AmplienceComponent registry. To customize a component:

1. Locate the component in modules/cms/providers/amplience/components/.
2. Modify the Vue component to match your design system.
3. Test in Live Preview to verify your changes.

Available Components to Customize

The integration provides a comprehensive set of pre-built components that can be customized:

• TextComponent.vue: Customize text rendering and styling.
• ImageComponent.vue: Customize image display and responsiveness.
• ButtonComponent.vue: Customize button appearance and interactions.
• SectionComponent.vue: Customize layout and spacing.
• GridComponent.vue: Customize grid columns and gaps.
• LinkComponent.vue: Customize link styling and behavior.
• ... and all other available components.

Each component is registered in AmplienceComponent.vue (see the Nested Components section for details on how this registry works).

Nested Components

Amplience content types can reference other content types, creating nested component hierarchies. AmplienceComponent.vue serves as the central registry that maps content palette entries to their corresponding Vue components.

How AmplienceComponent works:

The AmplienceComponent is a dynamic component dispatcher that:

1. Receives an Amplience content palette entry as a prop.
2. Examines the entry's componentType.
3. Renders the appropriate Vue component based on the type.
4. Passes the entry data to the mapped component.

Example: nested content

vue

Copy

Building New Components

Creating new Amplience components allows you to extend the pre-built library with custom functionality.

Step 1: Define in Amplience

1. Create the JSON schema at .scayle/cms/contentModel/amplience/schemas/schemas/{name}-component-schema.json.
2. Create the content type at .scayle/cms/contentModel/amplience/content-types/{name}-component.json.
3. Add a oneOf entry to the parent container's content palette.
4. Push the schema to your hub with CMS_PROVIDER=amplience pnpm cms:import.

Step 2: Add TypeScript Types

After defining your component in Amplience, types are automatically generated by running pnpm cms:sync from your Storefront Application root directory:

bash

Copy

This command pulls content types from your Amplience hub and generates TypeScript types in modules/cms/providers/amplience/types/gen/.

Warning: Never manually edit files in modules/cms/providers/amplience/types/gen/. These are auto-generated and will be overwritten when you run pnpm cms:sync again.

Step 3: Create Vue Component

Create a corresponding Vue component in your application. Components receive a contentElement prop containing the Amplience data:

vue

Copy

Step 4: Register Component

Register the component in AmplienceComponent.vue to make it renderable:

vue

Copy

Best Practices

Content Organization

• Mirror URL structure: Keep the same delivery key pattern in all locale content items.
• Consistent naming: Use the same slugs across locales when possible.
• One item per locale: Create a separate content item for each locale rather than sharing one item.

Translation Workflow

• Create default locale first: Start with one locale as the source of truth.
• Duplicate per locale: Create matching content items with translated field values.
• Review process: Implement a review process for translated content.

Performance

• Use caching: The Storefront Application caches Amplience responses.
• Lazy loading: Use lazy: true for below-the-fold content.
• Asset optimization: Use Dynamic Media for optimized image delivery.

SEO Considerations

• Unique meta tags: Ensure each locale has unique meta titles and descriptions.
• Hreflang tags: Implement hreflang tags for multilingual SEO.
• Canonical URLs: Set canonical URLs appropriately for each locale.
• Sitemap: Generate locale-specific sitemaps.

Development Workflow

• Use Live Preview: Enable Live Preview for content editors during development.
• Sync types regularly: Run pnpm cms:sync after content model changes.
• Test with draft content: Verify draft content displays correctly before publishing.
• Handle errors gracefully: Implement proper error boundaries and fallbacks.
• Test across routing modes: Verify content fetching works with your routing mode (path-based, domain-based, or path-except-default).

Troubleshooting

Content Not Found (404)

Problem

Content exists in Amplience but shows 404 or an empty state in the application.

Solutions

1. Ensure the delivery key uses the correct locale prefix (for example de-DE/content/about).
2. Confirm the locale matches your shop configuration.
3. Verify the delivery key matches the URL path.
4. Confirm the content item is published, or preview is enabled with a Virtual Staging Environment.

Debugging

• Check the delivery key in Amplience Dynamic Content matches what the storefront expects.
• Verify NUXT_PUBLIC_CMS_HUB_NAME points to the correct hub.
• Open browser DevTools and check for network errors on content requests.

Preview Not Working

Problem

Visualization preview doesn't load, shows published content only, or shows errors.

Solutions

1. Verify the visualization URL matches your routing mode and environment.
2. Set NUXT_PUBLIC_CMS_ALLOW_DRAFTS=true for preview.
3. Confirm the vse= query parameter is present in the iframe URL.
4. Verify a Virtual Staging Environment is provisioned for your hub.
5. For PLP preview, confirm the visualization uses /c/cms-preview-0 with key={{delivery.key}}.

Debugging

• Open browser DevTools and check for network errors.
• Verify vse= and key= query parameters are present in the URL.
• For ngrok origins, open the forwarding URL directly once to clear the interstitial warning.

Wrong Content Loaded

Problem

Content from the wrong locale is displayed.

Solutions

1. Verify the current shop locale is correct.
2. Ensure your routing mode is configured correctly.
3. If page cache is used, clear the cache if content is cached incorrectly.

Debugging

• Compare the shop locale from useCurrentShop() with the delivery key prefix in Amplience.
• Test the URL against the delivery key tables in the Routing Mode Integration section.

Delivery Key Mismatch

Problem

Delivery key resolution doesn't match the expected Amplience path.

Solutions

1. Verify the locale prefix matches the shop locale, not the shop routing code.
2. Confirm homepage, content, and category keys follow the documented patterns.
3. For PLP content, verify the key follows {locale}/c/c-{categoryId}.

Debugging

• Compare the delivery key set in Amplience with the URL you are visiting.
• For preview, check the key= query parameter matches the content item's delivery key.

Type Errors

Problem

TypeScript errors after changing the content model.

Solutions

1. Run CMS_PROVIDER=amplience pnpm cms:sync to regenerate types.
2. Add the matching typeguard in types/typeguards.ts for new palette entries.
3. Register new components in AmplienceComponent.vue.

Prevention

• Never edit files under types/gen/ manually.
• Run pnpm cms:sync after every content model change.

Images Not Loading

Problem

Images break in preview or on the live storefront.

Solutions

1. Confirm Dynamic Media is enabled on your hub.
2. Verify image fields include defaultHost, endpoint, and name.
3. In preview, unpublished-only assets may require signed Virtual Staging Environment media URLs.

Prevention

• Use Dynamic Media image fields rather than raw asset URLs in components.
• Publish image assets before relying on them in production content.

Hub Sync Fails with Cyclic Schema Reference

Problem

pnpm cms:import fails with a cyclic reference error when pushing schemas to the hub.

Solutions

1. Check whether a new schema references a container that references it back.
2. Keep nesting on one side of Slider → Section → Grid → Accordion → Accordion Item → leaves.
3. Compare against working schemas in .scayle/cms/contentModel/amplience/schemas/schemas/.

Prevention

• Follow the one-directional nesting chain when adding new container content types.
• Avoid Section inside Section or Grid inside Grid in schema definitions.