PDP Dropin

PDP Installation

Our dropins are designed for the browser’s JavaScript run-time without the need for a bundler. But they can also be installed and executed in a build-time environment with bundlers like Webpack and Vite. The installation steps for both run-time and build-time environments are the same after the initial dropin package imports.

Big picture

The steps for installing the Product Details dropin are as follows:

Step-by-step

The following steps show how to install the Product Details dropin into your site.

Install the packages

Use a CDN or NPM (recommended for performance) to install the dropin tools (@dropins/tools) and Product Details (@dropins/storefront-pdp) packages.

npm install @dropins/tools @dropins/storefront-pdp

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Your Storefront</title>

  <script src="https://cdn.jsdelivr.net/npm/@dropins/tools@latest"></script>
  <script src="https://cdn.jsdelivr.net/npm/@dropins/storefront-pdp@latest"></script>
</head>

Map the packages

In the <head> tag of your index.html or head.html file, use an importmap pointed to the node_modules directory, a custom local directory, or CDN (for run-time environments).

This example shows an importmap added to a head.html The importmap points both packages to the local node_modules directory that contains your installed dropin files from the dropin tools (@dropins/tools) and the PDP dropin (@dropins/storefront-pdp):

<script type="importmap">
  {
    "imports": {
      "@dropins/tools/": "/node_modules/@dropins/tools/",
      "@dropins/storefront-pdp/": "/node_modules/@dropins/storefront-pdp/",
    }
  }
</script>
<script src="/scripts/scripts.js" type="module"></script>

This example shows an importmap added to a head.html The importmap points both packages to local directories that contain all the optimized/minified files from the dropin tools (@dropins/tools) and the Product Details dropin (@dropins/storefront-pdp):

<script type="importmap">
  {
    "imports": {
      "@dropins/tools/": "/scripts/__dropins__/tools/",
      "@dropins/storefront-pdp/": "/scripts/__dropins__/storefront-pdp/",
    }
  }
</script>
<script src="/scripts/scripts.js" type="module"></script>

This example shows an importmap pointing both packages to a CDN for the dropin tools (@dropins/tools) and the Product Details dropin (@dropins/storefront-pdp):

<head>
  <script type="importmap">
    {
      "imports": {

        "@dropins/tools/": "https://cdn.jsdelivr.net/npm/@dropins/tools@latest",
        "@dropins/storefront-pdp/": "https://cdn.jsdelivr.net/npm/@dropins/storefront-pdp@latest",
      }
    }
  </script>
</head>

With the importmap defined for both run-time and build-time environments, you can now import the required files from these packages into your PDP dropin JavaScript file as described in the next step.

Import the required files

Import the required files from the dropins tools (@dropin/tools/initializers.js) and the Product Details dropin (@dropins/storefront-pdp) into a JavaScript file for your PDP dropin. The example here shows the imports added to a product-details.js file. These imports constitute the minimum imports you need to create a fully functioning Product Details dropin for your site:

// Dropin Tools
import { initializers } from '@dropins/tools/initializer.js';

// Dropin Functions
import * as product from '@dropins/storefront-pdp/api.js';

// Dropin Provider
import { render as productRenderer } from '@dropins/storefront-pdp/render.js';

// Dropin Container
import ProductDetails from '@dropins/storefront-pdp/containers/ProductDetails.js';

Connect to the endpoint

Connect your Product Details dropin to the Catalog Service GraphQL endpoint and set the required headers as shown in the example below. Replace the endpoint URL and header placeholder values with the actual values from your Commerce backend services:

// Set endpoint configuration
product.setEndpoint('https://<catalog-service-endpoint>/graphql');

product.setFetchGraphQlHeaders({
  // Environment required headers
  'Magento-Environment-Id': 'your-environment-id',
  'Magento-Store-View-Code': 'your-store-view-code',
  'Magento-Website-Code': 'your-website-code',
  'x-api-key': 'your-api-key',
  'Magento-Store-Code': 'main_website_store',
  'Magento-Customer-Group': 'your-customer-group',
  'Content-Type': 'application/json',
});

Register and load the dropin

The code below shows how to register the Product Details dropin, load it (mount), and enable the logger for debugging purposes. You can add these functions within a <script> tag in your Product Details HTML page as shown here:

<script type="module">
  // more code above...

  // Register and load the Product Details dropin
  initializers.register(pdp.initialize);

  // Mount Initializers (must be called after all initializers are registered)
  window.addEventListener('load', initializers.mount);
</script>

This function registers the Product Details dropin to be loaded on the page by the initializers.mount function.
This event handler triggers the initializers.mount function to load the Product Details dropin after the page has loaded.

Render the dropin

Render the Product Details dropin on the page. The example below provides the minimal configuration options required to render the default Product Details dropin:

// Render Product Details
productRenderer(ProductDetails, {
  sku: 'SKU-001',
  // other configuration options
  // slots for adding custom elements, components, and functions
})(document.getElementById('your-pdp-element'));

Test the Product Details dropin by viewing your PDP page in a browswer, or running your local dev or build server. If you see the Product Details dropin rendered in the browser, congrats!, you have a successful installation. If not, check the console for any errors and verify that you have followed all the steps correctly.

Summary

The installation of all dropins follows the same pattern demonstrated by installing the PDP dropin: Install, Map, Import, Connect, Register, and Render. We like to call the process iMICRR for short, pronounced eye-mike-er. Actually, we don’t call it that, but if it helps…Enjoy!