Skip to main content

Swell integration for Uniform Mesh

Swell is a developer friendly headless commerce platform.

This integration allows business users to build personalized landing pages and storefronts by repurposing product content from your Swell product catalog and enables developers to use modern performance-optimized front-end tooling like Next.js and have a fantastic developer experience.

This section describes how to configure and use this integration.

Pre-requisites​

  1. Using your developer access to your Swell store (sign up here for free), retrieve the following from the admin console (Developer>API Keys). We will need these to connect Mesh integration with your store:

    • Store ID
    • Secret key

  2. Uniform account with at least one project. Signup for free here.

Step 1: Install and configure the integration​

  1. Locate the Swell integration in the list of available integrations within your Uniform project's Settings -> Integrations:

  2. Click on the plus icon to install the integration.

  3. After the installation, the empty configuration screen will display, fill out the configuration settings as described (use the Store ID and Secret key from the earlier step):

  4. Click "Test" to verify the connection details.

  5. If the test was successful, click "Save" to accept the connection details. If you are getting an error, please double check the connection details and if you are experiencing any issues, please let us know.

SUCCESS!

That's it, the Mesh integration for Swell is installed and configured.

Step 2: Create a component parameter​

Now let's connect the product data with one of your components in Canvas.

The integration ships with two types of Swell parameters, each targeting a specific scenario:

"Product Selector" parameter type​

Allows to pick one or many products from a specific catalog. This type saves a specific product selection within a given parameter.

  1. Let's add a new parameter to any of the existing or new components in Canvas Component library.

    For example, let's create a new component called Product and add a new parameter:

  2. Specify a name "Product" (remember the name as we will be referring to it from our component's front-end code using Public ID).

  3. Pick the "Swell Product Selector" parameter type from the list of types and select a specific catalog.

    You have many parameter configuration options here:

    1. Ability to constrain the selection to the specific product types.
    2. Ability to enable multi-selection of products.
    3. Override the display field, which allows picking the product attribute as main display attribute of the product selector.
    4. Ability to mark the parameter required.

  4. Make this component a composition component by toggling the Composition checkbox:

    Unless you have other composition component already, then allow this component into a slot of another composition component by clicking "Allow in slot":

  5. In order to create an instance of this component, head over to the Composition section and create a new composition.

  6. After the composition is created and the newly created/modified component with the Product parameter is placed, you should be able to see the following experience, allowing to pick one or many products (if multi-select is allowed) from your catalog and save the component:

"Product Selector" parameter value​

If you are wondering what value does Uniform store, here is a sample below. The value contains the selected product ids.

"product": {
  "type": "swell-product-selector",
  "value": {
    "products": [
      {
        "id": "5e5198ce72f5542e005fa4c8"
      },
      {
        "id": "5e31e67be53f9a59d89600f1"
      }
    ]
  }
}
important

Uniform doesn't store the actual product details data. This is a job of an Enhancer to resolve at build-time or run-time, depending on your application architecture. Enhancers can be added to your web app, or deployed separately as an API proxy. The section below describes how the enhancers are added.

"Product Query" parameter type​

Allows to create a query criteria for your product catalog. In contrast to the Product Selector type, this parameter type does not persist the specific product matches, and it saves the search criteria iteself, which allows to defer the product selection to runtime.

The process of adding the Product Query parameter is identical to the one described above.

The difference is in the way the component UX is implemented and what value is stored in Uniform.

Here is how this parameter type is configured:

The UX of this parameter type allows to configure a query criteria:

"Product Query" parameter value​

If you are wondering what value does Uniform store, here is a sample below. The value includes the query criteria parameters, if specified:

  • count
  • category ids
  • catalog id
  • keyword
  • sorting parameters
"productQuery": {
  "type": "swell-product-query",
  "value": {
    "options": {
      "count": 1,
      "categories": ["5e31dbc0ae1309046a52f1a2", "5e31dbf3ae1309046a52f45f"],
      "keyword": "",
      "sort": "price",
      "sortOrder": "desc"
    }
  }
}
important

Uniform doesn't store the actual product details data. This is a job of an Enhancer to resolve at build-time or run-time, depending on your application architecture. Enhancers can be added to your web app, or deployed separately as an API proxy. The section below describes how the enhancers are added.

What else can you do?​

Now that you have the components that are connected to your commerce content, you can leverage Uniform Personalization and A/B testing, as well as activating the Swell integration with your web application.

Step 3: Wire up your app​

tip

Before wiring up your app, please make sure to get familiar with the concept of Data Enhancers. This chapter will walk you through the process of adding Swell specific enhancers to your web application.

Pre-requisites​

Make sure you already have a web application wired up to Canvas with Uniform API key and Project Id in the env vars.

If you don't have the Canvas enabled app up and running yet, please go through one this tutorials:

Adding Swell enhancers to a Next.js app​

info

This tutorial will use a Next.js application as an example, but the same concepts apply to any other JavaScript framework.

  1. Install our Data Enhancer for Swell with this command:

    npm install @uniformdev/canvas-swell

  2. Add the following Swell specific environment variables to your web app's .env file:

    SWELL_STORE_ID=<SWELL_STORE_ID>
    SWELL_SECRET_KEY=<SWELL_SECRET_KEY>

  3. Find the location where you retrieve your page content. In a Next.js app, this is typically a page file under /pages (index.tsx, [slug].tsx, etc.)

  4. Find the location of the getStaticProps or getServerSideProps function (depending on what you use).

  5. Add the following lines of code after the code that retrieves the raw composition from Canvas APIs:

    • A: import ehnancer for Swell
    • B: run the enhance function, with will return post-enhanced composition
    • C: register enhancer for Swell
    • D: return the post-enhanced composition as a page prop
/pages/[slug].js
// A. import ehnancer for Swell
import { swellEnhancer, SWELL_PARAMETER_TYPES } from '@uniformdev/canvas-swell';

export async function getStaticProps(context: GetStaticPropsContext) {
  // retrieving the raw composition content form Uniform Canvas API, before enhancing
  const compositionId = context?.params?.compositionId ?? '';
  const compositionString = Array.isArray(compositionId) ? compositionId.join('/') : compositionId;
  const { composition } = await canvasClient.getCompositionById({ compositionId: compositionString });

  // B: run the enhance function, with will return post-enhanced composition
  await enhance({
    composition,
    // C: register enhancer for Swell:
    enhancers: new EnhancerBuilder().parameterType(CANVAS_SWELL_PARAMETER_TYPES, swellEnhancer()),
    context,
  });

  // D: return the post-enhanced composition as a page prop
  return {
    props: {
      composition,
    },
  };
}

Please note that your way of reading the environment variables may be different.

success

Congratulations! You successfully added Swell Mesh integration to your Uniform project and your Uniform Canvas-enabled app. Now the composition JSON is expected to contain the data from Swell, and you can proceed building amazing front-end experiences.

Next steps​

If you haven't already done so, activate Personalization and A/B testing within your app by following this tutorial. This will enable your business users to personalize shopping experiences without developer effort.