Documentation

BigCommerce ImageEngine Integration

This article will demonstrate how to use ImageEngine with BigCommerce. BigCommerce is tightly-bundled with Akamai Image Manager. The best way to configure ImageEngine in front of Akamai Image Manager is to edit the templates. This can easily be done in the BigCommerce admin interface.

TL;DR:

If you have your ImageEngine address ready, the theme files referencing images must be changed. The ImageEngine address must prefix all image urls generated by BigCommerce. Typically, an image tag may look like this:

<img src="//<your-unique-id>.cdn.imgeng.in/{{getImageSrcset image 1x=(default fallback_size '1080w')}}" alt="{{image.alt}}" title="{{image.alt}}">

This will make the image urls look like this:

<img src="//<your-unique-id>.cdn.imgeng.in/https://cdn11.bigcommerce.com/path/img.jpg" alt="alt text" title="{{alt text}}">

# Have Your ImageEngine Account Ready

To configure your BigCommerce site with ImageEngine, you’ll need an ImageEngine delivery address. You easily obtain this when you sign up for an account. Alternatively, reach out to our Customer Success team for assistance.

# Edit Your BigCommerce Theme

For the purpose of this demo, we’ll be using one of the default themes that are available in BigCommerce: Cornerstone.

If you’re using a different theme, or a custom theme, the theme files you’ll be editing (and their contents), may be different.

The key takeaway is how to change the image references - the <img src=""> tag. This is the same procedure regardless of themes and files.

# 1) Make a Copy of the BigCommerce Theme

First, log on to your Bigcommerce account.

From the left hand menu, go to “Storefront” -> “My themes” and make a copy of the current active theme. This is where we’ll be editing.

Bigcommerce Image CDN ImageEngine copy theme files

Once the theme is copied, it is listed under “My themes” on the same page (you may Apply the theme again now if you want to do the changes on the “live” site).

# 2) Edit the Theme Stencil Files

The basic change needed to integrate ImageEngine is only to prefix any image url with the ImageEngine delivery address.

Next click “Edit Theme Files”

Bigcommerce Image CDN ImageEngine Edit theme stencil with ImageEngine delivery address

Now you’re looking at the Stencil file editor. It looks like a file explorer window and different files are organized in folders. How files are organized in this view depends on your theme.

You can also choose to download the theme files, do the changes locally, and then upload the theme again.

# Editorial Images

Editorial images, used in blog posts for example, are not served by Akamai ImageManager and are much easier to optimize with ImageEngine.

This method works regardless of theme.

In BigCommerce, you can simply define custom CDN endpoints to use with the CDN Handlebars helper.

All you need to do is to define custom CDN endpoints in your theme’s config.json file like illustrated with the custom CDN endpoint below:

{
  "name": "Cornerstone",
  "version": "1.3.5",
  "settings": {
    "homepage_new_products_count": 12,
    "homepage_featured_products_count": 8,
    "cdn": {
            "customcdn": "<your-unique-id>.cdn.imgeng.in"
          }
     }
}

After defining an endpoint, you can use the short name in the same way as you would use a webdav: abbreviation:

<img src="{{cdn 'customcdn:img/image.jpg'}}" />

In local development, that helper would return:

<img src="/assets/cdn/customcdn/img/image.jpg" />

Whereas in production, it would return:

<img src="https://<your-unique-id>.cdn.imgeng.in/img/image.jpg" />

As highlighted above, the helper is configured to rewrite local URLs to a assets/cdn/ subfolder. The stencil bundle command will exclude this local assets/cdn/ subfolder from the bundle that it creates. This filtering circumvents the 50 MB size limit on the resulting .zip file.

Read more about how to integrate ImageEngine and BigCommerce on developer.bigcommerce.com.

# Product Images

In the case of the Cornerstone theme, well need to edit these files in order update the image references for product images:

  • templates > components > common > responsive-img.html
  • templates > components > products > product-view.html

The procedure is the same for all template files with product images, so we’ll focus on responsive-img.html. In Cornerstone, this template is responsible for displaying most of the images.

The default content of the file is pretty verbose. With ImageEngine this will be dramatically simplified. You can make use of any of the lazy loading features and LQIP (low quality image placeholders) built in to the theme if you want. However, in this example we’ll simplify and focus on the image references. Feel free to build out with additional features.

Take note of {{getImageSrcset}} and {{image.alt}}. We’ll need these parts in the updated image tag.

Next, replace all content in the template with this:

<img src="//<your-unique-id>.cdn.imgeng.in/{{getImageSrcset image 1x=(default fallback_size '1080w')}}" alt="{{image.alt}}" title="{{image.alt}}">

Replace <your-unique-id>.cdn.imgeng.in with the ImageEngine delivery address obtained above.

Click the “Save and Apply” button in the bottom right corner to save the changes.

At this point, all images rendered with the responsive-img.html, like the hero images in the carousel in the Cornerstone theme, are now served through ImageEngine. You’ll notice that the image tag looks something like this if you view the source of the page:

<img src="//<your-unique-id>.cdn.imgeng.in/https://cdn11.bigcommerce.com/s-owncnz90jw/images/stencil/1280w/image.jpg?c=1" alt="alt text" title="alt text">

# Further enhancements

The next template listed above, product-view.html, is a good place to talk about changes that needs to happen in all templates referencing images. Where, and how many templates this is, depends on your theme. A tip is to go through templates an look for {{getImage ...}} references or {{getImageSrcset this use_default_sizes=true}}

Handling {{getImage ...}} is pretty easy. Just prefix it with the ImageEngine delivery address: //<your-unique-id>.cdn.imgeng.in/{{getImage ... }}. Then ImageEngine will serve the images.

For references similar to {{getImageSrcset this use_default_sizes=true}} it is recommended to remove it entirely. Simply because getImageSrcset returns a long string which doesn’t allow individual image sources to be prefixed. You can still use getImageSrcset when requesting one image size like demonstrated above.

More specifically in product-view.html, you want to change (or prefix) these variables using {{getImageSrcset}} with your ImageEngine delivery address:

  • data-zoom-image
  • data-image-gallery-new-image-url
  • data-image-gallery-zoom-image-url

Remove entirely because it outputs the entire string of the srcset:

  • data-image-gallery-new-image-srcset

Look through all templates displaying images and look for similar references. Double check templates for category listings, shopping cart and other relevant templates in your theme.

# Setting the size of the images

It is also a good idea to try to define an image size in the markup. This is not straight forward in all themes. Default sizes may be defined in the site settings (config.json). If you have a setting that is used to define sizes on product thumbnails, say productview_thumb_size_px: 200, you can set the fall back size, and an additional sizes attribute to make use of ImageEngine’s Client Hints support.

{{> components/common/responsive-img
	image=product.main_image
	fallback_size= theme_settings.productview_thumb_size
	width=theme_settings.productview_thumb_size_px
	img_compression=70
}}

To make use of width you’ll have to update responsive-img.html by adding this attribute to the image tag: width="{{width}}". The img_compression example above shows how you can pass values to ImageEngines directives. This is an example of custom compression level. To make use of the snippet above, the tag must be updated to :

<img src="//<your-unique-id>.cdn.imgeng.in/w_auto,{{width}/cmpr_{{img_compression}}/{{getImageSrcset image 1x=(default fallback_size '1080w')}}">

You can use the same method to make use of all ImageEngine directives.

Unfortunately, there is no way to enable client hints for image optimization in BigCommerce.

# Add resource hint

To make the browser connect to ImageEngine as soon as possible, add this line inside the <head> element on the site:

<link rel="preconnect" href="//<your-unique-id>.imgeng.in">

Again, depending on your theme, you’ll need to find where the <head> content is defined. In the case on the Cornerstone theme, it’s located in templates > layouts > base.html

# 3) Apply the Theme Changes

If you did the changes offline, then after you have changed all the image references, you need to activate the theme with the changes on your site.

Bigcommerce Image CDN ImageEngine Enable

Do so by clicking the meat-ball icon and click Apply.

Once applied, check your site and make sure image urls are prefixed with the ImageEngine delivery address.

# Alternative JavaScript implementation

If changing template files is not an option for your site, ImageEngine can also be implemented using the Script Manager in BigCommerce. Read more about that option here.