Skip to main content

Adding Acoustic data

tip

This tutorial assumes you have completed the basic tutorial and have the artifacts from that already present in Uniform.

Let's add some content data from Acoustic into your Uniform Canvas-powered Next app. To do this we will need to add a new Acoustic-powered parameter to your component type, and then tell your Next app how to fetch and parse the Acoustic data to display it. Canvas provides a framework for enhancing data in your Canvas composition with data from other tools, like CMSes, DAMs, commerce, and search indexes. This enhancement is done on the app side, leaving full flexibility to the developer as to the best and most efficient way to get the data.

First let's connect Uniform to Acoustic by installing the integration. You'll need a Acoustic account to do this (a free one is fine).

  1. Go to Settings on your on https://uniform.app project, then click Integrations
  2. Find the Acoustic integration and add it
  3. Click the button to add a content source
  4. Provide the API Url, API Key for the Acoustic project that you want to bring content from into Canvas

Now that we're connected to Acoustic, we can add a new parameter to our Canvas component type that links to a Acoustic content item.

  1. Go to your Component Library settings
  2. Open your component type (there should be only one, if you've been following along)
  3. Click (+) next to Parameters
  4. Name your parameter something like 'Acoustic Content Item', choose Acoustic Content Item as the type, pick a Acoustic source from which content item will be selected, pick Acoustic content type(s) that can be linked, and as before choose a public ID to use as the name in code. (e.g. acousticContentItem)

Now that the parameter is added to the component type, we need to link the composition we have been rendering to an actual Acoustic content item.:

  1. Click Compositions, then open your composition from earlier
  2. You should see a Acoustic parameter alongside the text parameter we created before
  3. Choose a Acoustic content item to link to and save your composition
  4. That's it - you've linked to a Acoustic content item in your composition

With the data schema setup complete, now let's set up Next.js. Right now we're doing nothing with the Acoustic data - the Next app will look exactly the same as it did before, except it has a new parameter we're doing nothing with. To get the Acoustic data, we need to add an enhancer to the Next app's data fetching so that Canvas knows what to do with Acoustic parameters.

  1. Install the @uniformdev/canvas-acoustic package, which contains the Canvas Acoustic enhancer and the Acoustic Client.

  2. Open your pages/index.js file and import the Acoustic enhancer, and add enhance to the existing canvas import:

    import {
    AcousticClientList,
    createAcousticClient,
    createAcousticContentItemEnhancer,
    createAcousticMultiContentItemEnhancer,
    CANVAS_ACOUSTIC_CONTENT_ITEM_PARAMETER_TYPES,
    CANVAS_ACOUSTIC_MULTI_CONTENT_ITEM_PARAMETER_TYPES,
    } from '@uniformdev/canvas-acoustic';
    import { enhance, CanvasClient, EnhancerBuilder } from '@uniformdev/canvas';
  3. In getStaticProps, create the enhancer and configure it to connect to Acoustic and enhance your composition data:

    // ...fetching the composition here

    // NOTE: for production code ensure you use environment variables to
    // configure Acoustic, not hard-coded values.

    // API URL can be found in your Acoustic Account: Tenant -> Developer -> URL information.
    // Example: https://content-us-1.content-cms.com/api/{tenant-specific-id}/
    const acousticApiUrl = `ACOUSTIC-API-URL`;

    // Example: https://content-us-1-preview.content-cms.com/api/{tenant-specific-id}/
    // Read more: https://developer.goacoustic.com/acoustic-content/docs/preview-content
    const acousticPreviewApiUrl = `ACOUSTIC-PREVIEW-API-URL`;

    // Acoustic API Key is needed if you want to use preview client.
    // API Key can be created in your Acoustic Account: Tenant -> Manage -> API keys.
    const acousticApiKey = `ACOUSTIC-API-KEY`

    const client = createAcousticClient({
    apiUrl: acousticApiUrl,
    });

    const previewClient = createAcousticClient({
    apiUrl: acousticPreviewApiUrl,
    auth: {
    apiKey: acousticApiKey,
    },
    });

    const clients = new AcousticClientList({ client, previewClient });

    // apply the enhancers to the composition data, enhancing it with external data
    // In this case, the _value_ of the Acoustic parameter you created is enhanced
    // with data from the Acoustic content item you selected in the Acoustic content item selector.
    // You can create your own enhancers easily; they are a simple function.
    await enhance({
    composition,
    enhancers: new EnhancerBuilder()
    .parameterType(
    CANVAS_ACOUSTIC_CONTENT_ITEM_PARAMETER_TYPES,
    createAcousticContentItemEnhancer({ clients })
    )
    .parameterType(
    CANVAS_ACOUSTIC_MULTI_CONTENT_ITEM_PARAMETER_TYPES,
    createAcousticMultiContentItemEnhancer({ clients })
    ),
    context: {},
    });

    // ...returning the props

    The Next app should still be working, but we're not rendering any of the Acoustic data yet. Let's do that!

  4. In the Home component implementation, get the Acoustic parameter value and pick a field from it:

    export default function Home({ composition }) {
    return (
    <Composition data={composition}>
    {/* note: `acousticContentItem` is the "public id" value you provided for
    the Acoustic Content Item parameter. */}
    {({ greeting, acousticContentItem }) => (
    <article>
    <p>{greeting}</p>
    {/* we assume your content type has an element called 'title' on it */}
    <p>{acousticContentItem?.elements.title?.value}</p>
    </article>
    )}
    </Composition>
    );
    }
  5. That's it - now you're rendering data from Acoustic! The default structure of the enhancer result is that of a single Acoustic content item fetched from the Acoustic REST API.

tip

Use TypeScript? So do we. Here's the same code with TypeScript.

TypeScript Code
import { enhance, CanvasClient, EnhancerBuilder, ComponentInstance } from '@uniformdev/canvas';
import { Composition } from '@uniformdev/canvas-react';
import {
AcousticContentItemEnhancerResult,
AcousticClientList,
createAcousticClient,
createAcousticContentItemEnhancer,
createAcousticMultiContentItemEnhancer,
CANVAS_ACOUSTIC_CONTENT_ITEM_PARAMETER_TYPES,
CANVAS_ACOUSTIC_MULTI_CONTENT_ITEM_PARAMETER_TYPES,
} from '@uniformdev/canvas-acoustic';
import { GetStaticProps } from 'next';

type HomeProps = {
composition: ComponentInstance;
};

type MyCanvasComponentType = {
greeting: string;
acousticContentItem: AcousticContentItemEnhancerResult;
};

export default function Home({ composition }: HomeProps) {
return (
<Composition<MyCanvasComponentType> data={composition}>
{({ greeting, acousticContentItem }) => (
<article>
<p>{greeting}</p>
<p>{acousticContentItem?.elements.title?.value}</p>
</article>
)}
</Composition>
);
}

export const getStaticProps: GetStaticProps<HomeProps> = async () => {
// create the Canvas client
const canvasClient = new CanvasClient({
// if this weren't a tutorial, ↙ should be in an environment variable :)
apiKey: 'your-api-key-here',
// if this weren't a tutorial, ↙ should be in an environment variable :)
projectId: 'your-project-id-here',
});

// fetch the composition from Canvas
const { composition } = await canvasClient.getCompositionBySlug({
// if you used something else as your slug, use that here instead
slug: '/',
});

// NOTE: for production code ensure you use environment variables to
// configure Acoustic, not hard-coded values.

// API URL can be found in your Acoustic Account: Tenant -> Developer -> URL information.
// Example: https://content-us-1.content-cms.com/api/{tenant-specific-id}/
const acousticApiUrl = `ACOUSTIC-API-URL`;

// Example: https://content-us-1-preview.content-cms.com/api/{tenant-specific-id}/
// Read more: https://developer.goacoustic.com/acoustic-content/docs/preview-content
const acousticPreviewApiUrl = `ACOUSTIC-PREVIEW-API-URL`;

// Acoustic API Key is needed if you want to use preview client.
// API Key can be created in your Acoustic Account: Tenant -> Manage -> API keys.
const acousticApiKey = `ACOUSTIC-API-KEY`

const client = createAcousticClient({
apiUrl: acousticApiUrl,
});

const previewClient = createAcousticClient({
apiUrl: acousticPreviewApiUrl,
auth: {
apiKey: acousticApiKey,
},
});

const clients = new AcousticClientList({ client, previewClient });

// apply the enhancers to the composition data, enhancing it with external data
// In this case, the _value_ of the Acoustic parameter you created is enhanced
// with data from the Acoustic content item you selected in the Acoustic content item selector.
// You can create your own enhancers easily; they are a simple function.
await enhance({
composition,
enhancers: new EnhancerBuilder()
.parameterType(
CANVAS_ACOUSTIC_CONTENT_ITEM_PARAMETER_TYPES,
createAcousticContentItemEnhancer({ clients })
)
.parameterType(
CANVAS_ACOUSTIC_MULTI_CONTENT_ITEM_PARAMETER_TYPES,
createAcousticMultiContentItemEnhancer({ clients })
),
context: {},
});

return {
props: {
composition,
},
};
};