Usage

Alokai integration for Amplience ships with a framework-agnostic Typescript SDK. You can use it to:

fetch your content from the Amplience Content Delivery API,
initialize the visualizations feature.

Before you read

Visit Alokai SDK documentation to learn how to access sdk in both Next and Nuxt.

Fetching items collections

Your primary method for fetching content items should be getContentItems(). It allows you to fetch a collection of items and build sophisticated search queries (e.g. specifying the desired locale to resolve the content in).

const { responses } = await sdk.amplience.getContentItems([
  {
    key: "test-banner",
  }, 
  {
    id: "7b0a6dca-50a6-48f8-aeeb-1e802c3d4d23b"
  }
], {
  locale: 'en-GB'
});

Alternatively, you can use the fetchContentItems(). It is more verbose but yields the same results.

const { responses } = await sdk.amplience.fetchContentItems({
  requests: [
    { id: '09099a62-2416-4f6d-9072-48e9b33eced0' }
  ],
});

Fetching item by ID or key

To fetch a single item by ID, you can use the getContentItemById() method.

const item = await sdk.amplience.getContentItemById('dd1ecf28-e19c-4666-bd68-2a725c446ceb');

To fetch a single item by deliveryKey, you can use the getContentItemByKey() method.

const item = await sdk.amplience.getContentItemByKey('test-banner');

Unfortunately, neither of these methods supports resolving localized content.

Enabling visualizations

To enable visualizations for individual components or whole pages, use the initLivePreview() utility method.

This guide assumes the visualization URLs you have defined for your content types include the contentItemId query parameter.

http://localhost:3000/amplience-visualization?contentItemId={{content.sys.id}}

page.tsx

import type { SearchParams } from 'nuqs/parsers';
import { getSdk } from '@/sdk/sdk.server';
import LivePreview from './live-preview';

type PageProps = {
  content: any,
  params: {
    slug?: string[];
  };
  searchParams: SearchParams;
};

export default async function AmpliencePage(props: PageProps) {
  const sdk = getSdk();

  const content = props.content ?? await getContent();

  async function rerender(content: any) {
    "use server"
    return <AmpliencePage {...props} content={content} />
  }

  async function getContent() {
    const content = await sdk.amplience.getContentItems(
      [{
        id: props.searchParams.contentItemId as string,
      }],
      {
        locale: 'en-GB',
      }
    );

    return content.responses[0];
  }

  return (
    <>
      <div id="ssr-content">
        {/* your content goes here */}
      </div>
      <LivePreview rerender={rerender} />
    </>
  );
}

live-preview.tsx

'use client';
import { ReactNode } from 'react';
import { useEffect, useState } from 'react';

import { useSdk } from '@/sdk/alokai-context';

export interface LivePreviewProps {
  /**
   * The server callback function to be called when the content is updated
   */
  rerender: (content: any) => Promise<ReactNode>;
}

export default function LivePreview({ rerender }: LivePreviewProps) {
  const sdk = useSdk();
  const [previewContent, setPreviewContent] = useState<ReactNode>(null);
  
  useEffect(() => {
    sdk.amplience.utils.initLivePreview({
      callback: async (updatedContent) => {
        setPreviewContent(await rerender(updatedContent));
      }
    });
  }, []);
  
  useEffect(() => {
    const ssrContent = document.getElementById('ssr-content');
    if (previewContent && ssrContent) {
      /**
       * Hide the old SSR content when the preview is ready
       */
      ssrContent.style.display = 'none';
    }
  }, [previewContent]);
  
  return previewContent;
}