Using version 2 of the Frontend SDK

Configure the SDK

• locale - String - Required. The combination of the language and country code in ISO 639-1 and ISO 3166-1 format respectively. For example, en-DE or en_DE. In your code, you can access the locale from the PageProps.params.locale (Next.js 12) or using the useParams() hook (Next.js 13).
• currency - String - Required. The three-letter ISO 4217 Currency Code. For example, EUR. For more information, see supported currencies.
• endpoint - String - Required. The full URL of the API hub endpoint.
• extensionVersion - String - Required. The extension bundle version to connect to.
• useCurrencyInLocale - Boolean - Optional. If true, the currency is required in the locale in the format LOCALE@CURRENCY. Defaults to false. Overrides the currency option.
• sessionLifetime - Number - Optional. This is the amount of time in milliseconds for which a user's session persists before needing to log in again. Overrides the default session lifetime of three months.
• customHeaderValue - String - Optional. This is the value sent as the coFE-Custom-Configuration header value with every request. You can override this value on a specific request by setting the customHeaderValue option in the API methods. To access this value globally, call the SDK.customHeaderValue() function.
• cookieHandlingOverride - CookieManager - Optional. This option gives the user the ability to extend or override the default base SDK's CookieHandler.
  The following code example shows how to extend the default cookie handling using the defaultConfigure method in the SDK template file.
  Example code to specify custom cookie handling logicts

  import { sdk } from 'src/sdk';
  import { CookieHandler, ServerOptions } from '@commercetools/frontend-sdk';
  
  const cookieHandler = new CookieHandler();
  
  sdk.configure({
    ...
    cookieHandlingOverride: {
      setCookie: async (key: string, data: any, options?: ServerOptions) => {
        cookieHandler.setCookie(key, data, options);
      },
      getCookie: async (key: string, options?: ServerOptions) => {
        return cookieHandler.getCookie(key, options);
      },
      getCookies: async (options?: ServerOptions) => {
        return cookieHandler.getCookies(options);
      },
      deleteCookie: async (key: string, options?: ServerOptions) => {
        return cookieHandler.deleteCookie(key, options);
      },
      hasCookie: async (key: string, options?: ServerOptions) => {
        return cookieHandler.hasCookie(key, options);
      },
    },
  });
  
• redactionHandlingOverride - RedactionManager and RedactionManagerConfig - Optional. This option lets the user override the default redaction behavior of the base SDK's events, such as redacting passwords from event properties and URL parameters.
  You can extend or override the default functionality by passing a class or object that implements the RedactionManager interface.
  You can override the default redaction rules by passing a RedactionManagerConfig object.
  The following code example shows how to extend or override the default redaction handling methods using the defaultConfigure method in the SDK template file.
  Example of custom redaction handling logicts

  import { sdk } from 'src/sdk';
  import { RedactionHandler, ServerOptions } from '@commercetools/frontend-sdk';
  
  const redactionHandler = new RedactionHandler();
  
  sdk.configure({
    ...
    redactionHandlingOverride: {
      redact: async <T>(data: T) => {
        return redactionHandler.redact(data);
      },
      redactUrl: async (url: string) => {
        return redactionHandler.redactUrl(data);
      }
    },
  });
  
  The following code example shows how to override the default redaction handling configuration using the defaultConfigure method in the SDK template file.
  Example code to specify custom redaction handling configurationts

  import { sdk } from 'src/sdk';
  import { RedactionManagerConfig, ServerOptions } from '@commercetools/frontend-sdk';
  
  const customRedactConfig: RedactionManagerConfig = {
    paths: [{ value: "my.path.toRedact", caseSensitive: true }],
    properties: [],
    whitelistPaths: [{ "my.non_sensitive.password", caseSensitive: true }],
    includes: [{ value: "password" }, { value: "token" }],
    jsonRedactionText: "<CUSTOM_REDACT_TEXT>",
    urlRedactionText: "CUSTOM_URL_REDACT_TEXT",
  }
  
  sdk.configure({
    ...
    redactionHandlingOverride: customRedactConfig,
  });
  

API methods

callAction

• actionName - String - Required. The name of the action extension to call. For example, use product/getProduct to call the following extension: { actions: { product: { getProduct: (...) => { ... } } } }.
• payload - AcceptedPayloadTypes - Optional. A payload object with key-value pairs to be serialized into the request body.
• query - AcceptedQueryTypes - Optional. An object of key-value pairs to be serialized into the request query parameters.
• parallel - Boolean - Optional. Defaults to true. If set to true, the action is executed asynchronously. If set to false, the action is added to a queue and executed in sequence. Setting to false is useful for actions that may cause race conditions.
• customHeaderValue - String - Optional. The value to assign to the coFE-Custom-Configuration header value. Overrides the global customHeaderValue option set when configuring the SDK.
• serverOptions - ServerOptions - Optional for client-side configuration and required for server-side session management. Contains the req object of type IncomingMessage and res object of type ServerResponse with cookies.

const response = await sdk.callAction<Customer>({
  actionName: 'customActions/getCustomerCoupons',
  payload: { customer: { email: 'username@example.com' } },
  query: { customerId: '4' },
  parallel: false,
  customHeaderValue: '{"customerAuthId":9188377992}',
});

if (response.isError) {
  setError(response.error);
} else {
  setCustomer(response.data);
}

getPage

• path - String - Required. The relative path of the page of which you want to fetch the data. For example, /sale or /home/best-sellers.
• query - Object - Optional. An object of key-value pairs to be serialized into the URL query parameters. It accepts the value types specified in AcceptedQueryTypes.
• customHeaderValue - String - Optional. The value to assign to the coFE-Custom-Configuration header value. Overrides the global customHeaderValue option set when configuring the SDK.
• serverOptions - ServerOptions - Optional for client-side configuration and required for server-side session management. Contains the req object of type IncomingMessage and res object of type ServerResponse with cookies.

const response = await sdk.page.getPage({
  path: '/sale',
  query: { size: 'M' },
  customHeaderValue: '{"customerAuthId":9188377992}',
});

if (response.isError) {
  const router = useRouter();
  router.push('/404');
} else {
  setPageData(response.data);
}

getPreview

• previewId - String - Required. A string representing the ID of the preview to fetch.
• customHeaderValue - String - Optional. The value to assign to the coFE-Custom-Configuration header value. Overrides the global customHeaderValue option set when configuring the SDK.
• serverOptions - ServerOptions - Optional for client-side configuration and required for server-side session management. Contains the req object of type IncomingMessage and res object of type ServerResponse with cookies.

const response = await sdk.page.getPreview({
  previewId: 'p9986b2d', // Replace this with the variable containing the previewId
  customHeaderValue: '{"customerAuthId":9188377992}',
});

if (response.isError) {
  handleError(response.error);
} else {
  setPreviewData(response.data);
}

getPages

• path - String - Optional. Defaults to /. The relative path of the page of which you want to fetch the data.
• depth - Number - Optional. Defaults to 16. The depth of the page folder tree up to which you want to fetch the data.
• types - String - Optional. Defaults to static. The types of pages to fetch.
• customHeaderValue - String - Optional. Defaults to an empty string. The value to assign to the coFE-Custom-Configuration header value. Overrides the global customHeaderValue option set when configuring the SDK.
• serverOptions - ServerOptions - Optional for client-side configuration and required for server-side session management. Contains the req object of type IncomingMessage and res object of type ServerResponse with cookies.

const response = await sdk.page.getPages({
  path: '/sale',
  depth: 2,
  customHeaderValue: '{"customerAuthId":9188377992}',
});

if (response.isError) {
  handleError(response.error);
} else {
  generateSitemap(response.data.pageFolderStructure);
}

Add SDK integrations

//.... Other code
  constructor() {
    super();
    // customIntegration is an example name here
    this.customIntegration = new CustomIntegration(this);
  }
//.... Other code

Additionally, any custom events must be added to the SDK generic type as a type intersection. For example:

class CommercetoolsSDK extends SDK<ComposableCommerceEvents & CustomIntegrationEvents> {
  ...
}

The backend actions must be added to your backend service to extend your extensions API.

The event engine

Following is a description of the three methods available on the SDK to manage event handlers:

• trigger is called to trigger an event, for which an instance of the Event class from @comercetools/frontend-sdk is passed.
  An event is constructed with eventName and data. The eventName corresponds to the [key: string] value in @comercetools/frontend-sdk's StandardEvents. In custom events data corresponds to the type of value set for the event.
  For example, to trigger the marketingBannerClicked custom event, trigger is called on the sdk and an event constructed with eventName: 'marketingBannerClicked' and data: { id: "<string>" } is passed.
• on is called to add an event handler for an event. The method takes the eventName and handler arguments.
  For example, for the marketingBannerClicked custom event, marketingBannerClicked is passed for the eventName argument and a function with event parameter of type { data: { id: "<string>" } } is passed for the handler argument.
• off is called to remove an event handler. For example, to persist the handler only for the lifecycle of a particular component.
  The function takes the same arguments as the on function. For it to work, a named function for the handler argument must be defined. To successfully pass a named function to the handler parameter, the event type in the function's argument must be fully typed, as shown in the following examples.

Events are likely to be triggered only during action calls. The integrations you use may also create handlers so they can communicate with other integrations. However, you must be careful to avoid infinite recursion by mistakenly triggering events from event handlers.

Create custom events handlers

The commercetools Frontend SDK lets you create custom events that you can trigger from within the application, such as when clicking on a particular component or holding the pointer over it.

By default, event triggers and handlers will exist for the website's lifetime. However, you may want some to exist only during the lifetime of a specific React component. In that case, you must remove the event handlers on component unmounts. Otherwise, events can stack up due to component unmounting and remounting and may attempt to perform state updates on unmounted components, depending on the nature of the custom events.

To add custom event triggers to the SDK event definition, follow these steps:

1. Create a MyCustomEvents.ts file in the packages/PROJECT_NAME/frontend/sdk folder with the following content:
   Custom events type definitionts

   // packages/PROJECT_NAME/frontend/sdk/MyCustomEvents.ts
   export type MyCustomEvents = {
     marketingBannerClicked: { id: string };
   };
   
2. Add the type you created to the CommercetoolsSDK class in the generic SDK argument. The type must be added in the form of an intersection, as shown in the following example:
   Extend the base SDK type with custom events typets

   // packages/PROJECT_NAME/frontend/sdk/CommercetoolsSDK.ts
   import { SDK } from "@commercetools/frontend-sdk";
   import {
       ComposableCommerce,
       ComposableCommerceEvents
   } from "@commercetools/frontend-composable-commerce";
   import { MyCustomEvents } from "./MyCustomEvents";
   
   class CommercetoolsSDK extends SDK<ComposableCommerceEvents & MyCustomEvents> {
     ...
   }
   ...
   
3. Implement the MarketingBanner React component. In this example, we're making a simple banner component with an image.
   MarketingBanner React component implementation with event handlerstsx

   import Image from 'next/image';
   import { useEffect } from 'react';
   import { sdk } from '../../sdk';
   import { Event } from '@commercetools/frontend-sdk';
   
   interface Props {
     marketingId: string;
     imageSrc: string;
   }
   
   const MarketingBanner = ({ marketingId, imageSrc }: Props) => {
     const marketingBannerClickedHandler = (
       event: Event<
         'marketingBannerClicked',
         {
           id: string;
         }
       >
     ) => {
       // Perform custom event handling logic here.
       console.log('Marketing banner clicked, id: ' + event.data.id);
     };
   
     const clickHandler = (id: string) => {
       sdk.trigger(
         new Event({
           eventName: 'marketingBannerClicked',
           data: {
             id: id,
           },
         })
       );
     };
   
     useEffect(() => {
       sdk.on('marketingBannerClicked', marketingBannerClickedHandler);
   
       return () => {
         sdk.off('marketingBannerClicked', marketingBannerClickedHandler);
       };
     }, []);
   
     return <Image src={imageSrc} onClick={() => clickHandler(marketingId)} />;
   };
   
   export default MarketingBanner;
   
   We define a function named marketingBannerClickedHandler that takes a parameter event of class Event from the @commercetools/frontend-sdk library. This class takes the EventName and EventData parameters as the generic arguments, matching the event we defined earlier in the MyCustomEvents.ts file by name (key) and data (value) respectively.
   Then, we define a function clickHandler that constructs the marketingBannerClicked event and triggers it using the sdk.trigger method. The event has the following properties:
   • eventName: the name of the custom event.
   • data: value of the custom event where id is the identifier of the clicked marketing banner.
   Then, we use the React useEffect hook to call sdk.on to set up the event handler on component mount and sdk.off to remove the handler on component unmount by passing the named handler on both occasions.
   Finally we call the clickHandler from the onClick event of the Image component.