Guide

Display media items in carousel format

MEDIA COLLECTIONS HAVE BEEN DEPRECATED AND DECOMMISSIONED. This topic hasn't been removed only for archive/reference purposes.

Suggest Edits

❗️

Media Collections Viewer is deprecated

As of May 31, 2024, Media Collections Viewer functionality will be officially decommissioned. Contact your account representative for more details.

🚧

Product viewer is not PCI-compliant

The product viewer is not PCI-compliant at this time. Using the product viewer on any pages that handle card holder data (such as shopping carts) could put this information at risk.

In certain contexts, it can be cleaner and more visually appealing to display a collection of related images or videos in carousel format. Media carousels are frequently used to display product images and short-form videos on retail websites.

You can use Image and Video Manager to create media carousels on your website. The items in each media collection are displayed as a carousel of thumbnails. Your media collection can contain images, short-form videos, and 360 spin sets. Images can be in any supported format, and videos must be in MP4 or WebM format.

The breakpoint widths configured in the policies applied to the items in your media collection determine the size of the thumbnails in the carousel. You can also use policies to apply artistic transformations to the images in your media collection.

To create media carousels on your website, you need to:

Optionally, you can add 360 spin sets to your media collections and set poster images for your videos.

Prerequisites

Before you begin, you need to:

  • Make sure Image and Video Manager is configured and enabled.

  • Define your media collections.

  • Download and extract the contents of the Product Viewer Package to your origin or CDN. This package can be downloaded from the Image and Video Manager Media Collections page in ​Akamai Control Center​.

  • Note the location of two files: akamai-viewer.css and akamai-viewer.js.

Create a new media collection

Create a media collection for each set of related images and videos. For example, if you are using media carousels to display a set of images for each product, you will need to create a media collection for each product.

  1. Log in to ​Akamai Control Center​ and select ☰ > CDN > Image and Video Manager > Media Collections.

    The Media Collections page opens.

  2. Select the correct contract.

  3. Select the correct policy set, then click Manage Collections.

    If the policy set already contains media collections, they appear.

  4. Click Add New Collection.

    The New Collection page opens.

  5. Enter a collection ID and description for your media collection.

    👍

    If your media collection is for a product, consider using the product code (SKU or similar) as the collection ID and using the description to add a human-readable identifier. The collection ID must be unique within ithe policy set.

  6. Click Add Media Items.

    The Add New Media dialog box opens.

  7. Select Add Images or Videos.

  8. In the URLs field, enter the list of URLs for the images and videos you wish to include in this collection. This list must be a comma-delimited and contain absolute URLs (http:// or https:// and the filename).

    📘

    The order of the URLs in this list determines the order they will appear in your collection. You can change this order after you have added all of your items.

  9. In the Tags to Apply to All Items field, enter the tags to apply to all media items in this list.

    You can modify the tags for individual items later. These tags are the labels for the items that will appear in the product viewer.

  10. Click Add Items.

    The Media Collection Details page opens.

  11. When you are ready to save, click Save Changes. When prompted, confirm that the collection ID is correct.

    Once saved, the collection ID cannot be changed.

Add 360 spin sets

A 360 spin set shows a series of images in succession, much like an animation. Typically, the images in a 360 spin set are multiple views of the same item or product. When the images appear in order, the product seems to rotate, displaying all sides to the user.

You can use Image and Video Manager to create spin sets and add them to your media collection.

  1. On the Media Collections page, select the contract and policy set containing your media collection, and click Manage Collections.

  2. Click the name of the media collection to which you are adding the 360 spin set.

    The Media Collection Details page opens.

  3. Click Add Media Items.

    The Add Media Items dialog box opens.

  4. Select Add 360 Spin Set.

  5. In the URLs field, type or paste the list of URLs for the images you wish to include in the spin set. This must be a comma-delimited list of absolute URLs that contain http:// or https:// and the filename.

    📘

    The order of the URLs in this list determines their sequence in the spin animation. You can change their order after adding items.

  6. In the Tags to Apply to Spin Set field, enter the tags you want to apply to the set.

  7. Click Add Items.

  8. When you are ready to save, click Save Changes.

Your spin set is created as part of your media collection.

👍

Preview your 360 spin set animation

You can preview your 360 spin set animation by locating the spin set you wish to preview and clicking Preview 360 Spin button.

Set poster images for your videos

By default, a black thumbnail with a play symbol appears in the product viewer for any video you have included in your media collection. You can change the appearance of this thumbnail by specifying a poster image for each video.

  1. On the Media Collections page, select the contract and policy set containing your media collection, and click Manage Collections.

  2. Click the name of the media collection to which you are adding poster images for videos.

    The Media Collection Details page opens.

  3. Set the poster image for a video by selecting the Specify Poster Image URL checkbox and entering the absolute URL of the of the image you wish to use.

  4. Repeat for any other videos in your media collection.

  5. Click Save Changes.

Integrate the product viewer into your webpages

To integrate the product viewer into your website pages, you need to make certain changes to the page's HTML. These changes are described below. For detailed instructions and examples, see the README file in the Product Viewer Package that you downloaded from the Image and Video Manager Media Collections page.

  1. Open the HTML for the webpage where you want to display the product viewer.

  2. In the <head>element, include the CSS and JS files and specify the paths to the location on your origin or CDN where these files are located, for example:

    <link rel="stylesheet" href="//locationOfViewerCSS/akamai-viewer.css">
<script src="//locationOfViewerJS/akamai-viewer.js"></script>

  3. In either the <head>element, or at the start of the <body>element, add this .js script that calls the viewer function.

    <script type="text/javascript">
  var $ = window.jQuery;
    $(document).ready(function(){
      $("[data-akamai-viewer]").each(function(){
        var viewer = new Akamai.Viewer($(this), {
        items:
          uri: "product.imviewer?imcollection=" + $(this).attr("data-akamaiviewer")
          });
        });
      });
    });
  </script>

  4. In the <body>, add one or more <div>elements to indicate where in the HTML the viewer should appear. Your div tag should include the media collection ID of the media items to appear in the viewer.

Example

This example shows the HTML of a page that has three instances of the Image and Video Manager product viewer. Each media collection has an ID that matches a product catalog number. The media collection IDs are 1001, 1015, and 2500.

The script in the <body>locates each <div>element that contains the data-akamai-viewer attribute and generates an instance of the viewer, populating it with the images in the associated media collection.

<!doctype html>
<html lang="en">
  <head>
    <!-- Include the product viewer CSS -->
    <link rel="stylesheet" href="http://www.example.com/css/akamai-viewer.css">

    <!-- Include the product viewer JavaScript -->
    <script src="http://www.example.com/js/akamai-viewer.js"></script>
  </head>

  <body>

    <!-- Initialize all product viewers on the page -->
    <script>
      var $ = window.jQuery;
      $(function(){
        $("[data-akamai-viewer]").each(function(){
          var viewer = new Akamai.Viewer($(this), {
            items: {
              uri: "product.imviewer?imcollection=" + $(this).attr("data-akamaiviewer")
            }
          });
        });
      });
    </script>

    <!-- Render the viewer for Media Collection 1001 -->
    <div data-akamai-viewer="1001">
    </div>

    <!-- Render the viewer for Media Collection 1015 -->
    <div data-akamai-viewer="1015">
    </div>

    <!-- Render the viewer for Media Collection 2500 -->
    <div data-akamai-viewer="2500">
    </div>

  </body>
</html>

Use the product viewer with multiple policy sets

If you have multiple policy sets associated with your web performance configuration, you need to consider how the product viewer interacts with Image and Video Manager rules.

The Image and Video Manager Manager behavior requires a file extension match containing at least one supported image format. If you are using the product viewer, this match should also include the custom extension imviewer.

By default, the Image and Video Manager rule template includes this extension match.

The product viewer code generates a request for a resource named product.imviewerwith a query string that specifies the media collection ID. This iterates for each <div>element, defining an instance of the product viewer on the webpage.

The Image and Video Manager rule containing the imviewerextension match that selects the request determines which instance of the Image and Video Manager behavior applies. Image and Video Manager uses the policy set name configured in that behavior. The combination of a policy set name and a media collection ID specifies the set of images to populate the viewer.

To ensure that the correct media collection and Image and Video Manager policies apply, check the logic of your Image and Video Manager rules.

HTML for instance of viewer

Updated 2 months ago