Overview

You will need to install a SmartFrame Web Component in your webpage code in order to display images from the SmartFrame Cloud on your webpages.

The SmartFrame Web Component <smartframe-embed> can be used and styled like any other HTML tag.

Installation

In order to install SmartFrame Web Component into your website, add the viewer code snippet into the <head> section of your website.

<script async src="https://static.smartframe.io/embed.js"></script>

This script registers the new custom <smartframe-embed> Web Component. At this point, <smartframe-embed> is ready to be used on the web page.

Compatibility for legacy <smart-frame> and <smart-frame-embed> is preserved, which means that they continue to work but are deprecated. It’s recommended to switch over to using the <smartframe-embed>.
The SmartFrame Web Component is compatible with all evergreen browsers. If any of the browser features are missing, an appropriate polyfill will be automatically loaded. For further details, please refer to the browser compatibility page.

Usage

Insert the <smartframe-embed> tag wherever you would like your images to appear. The value [image_id] needs to be replaced with your image ID (case-sensitive) and the value [customer_id] needs to be replaced with your customer ID which can be found in the Admin Panel under Account settings > Integration.

<smartframe-embed image-id="[image_id]" customer-id="[customer_id]"></smartframe-embed>

The appearance of SmartFrames can be controlled through the use of a number of attributes, for example:

<smartframe-embed image-id="[image_id]" customer-id="[customer_id] theme="myzoom" disable-hidpi></smartframe-embed>

SmartFrame emits standard Javascript DOM events:

<smartframe-embed image-id="[image_id]" customer-id="[customer_id]"></smartframe-embed>
<script>
  let sf = document.queryElement('smartframe-embed');
  sf.addEventListener('load', (e) => { console.log('SmartFrame loaded') });
</script>

SmartFrames can be styled using standard CSS:

<style>
  smartframe-embed.my-image { 
    max-width: 300px;
  }
</style>
 
<smartframe-embed class="my-image" image-id="[image_id]" customer-id="[customer_id]"></smartframe-embed>

SmartFrames can also be dynamically added into the DOM:

<script>
  let sf = document.createElement('smartframe-embed');
  sf.setAttribute('image-id', '[image_id]');
  sf.setAttribute('customer-id', '[customer_id]');
  document.body.appendChild(sf);
</script>
Unlike the img tag, smartframe-embed requires a closing tag

Attribute reference

You can control the appearance and behavior of your SmartFrames by inserting attributes into the shortcode, using the following syntax:

<smartframe-embed image-id="[image_id]" customer-id="[customer_id]" [attribute1] [attribute2]="[optionalvalue]"></smartframe-embed>

 

Key Value Description
customer-id
(required)
string Unique case-sensitive ID of the client.

Customizability: All

image-id
(required)
string Unique case-sensitive ID of the image.

If you added the image using SmartFrame API, it’s the same ID as provided in the API request.

If you use the Image Source Connector, it’s the ID we agreed to use.

If you uploaded the image using the SmartFrame Admin Panel, you can find the ID in the Admin Panel. Click on the image in the Images panel before selecting Image Details.

Customizability: All

thumbnail-mode (optional) If this option is present, SmartFrame operates in a thumbnail mode. In this mode, all of SmartFrame’s UI, together with watermarks and tracking, are hidden and disabled. The maximum size of the image is limited to 800px.

Customizability: Home domain only (on-site)

theme (optional) string Identifier of the Theme to use. You can find it on the Overview page within each Theme in the Admin Panel.

Customizability: Home domain only (on-site)

disable-hidpi (optional) When used, SmartFrame will ignore the physical resolution of the display used to view the SmartFrame when choosing the image size file to download, and will instead rely only on logical resolution.

Customizability: Home domain only (on-site)

wait (optional) When the ‘wait’ attribute is present in the code, rendering of the SmartFrame will not be initiated. Use this if you want to load your page with SmartFrame disabled. When the attribute is removed, SmartFrame will be displayed.

Customizability: Home domain only (on-site)

retina-zoom (optional) Turns on window.devicePixelRatio for Hyper Zoom tiles size calculations.

Customizability: Home domain only (on-site)

gallery-caption (optional) Text value that overrides all the image captions with a single caption.

Customizability: Home domain only (on-site)

disable-captions (optional) false Boolean to hide all the image captions, including the custom generated via gallery-caption option.

Customizability: Home domain only (on-site)

gallery-attribution (optional) Text value that overrides the theme attribution for off-site embeds with a custom attribution.

Customizability: Home domain only (on-site)

autoplay (optional) false Boolean to start autoplay the gallery slides. On mouseover, tap or if any overlay is active (e.g. deterrent, share, embed) or if the image is zoomed then the autoplay feature is stopped.

Customizability: Home domain only (on-site)

interval (optional) Number value (milliseconds) that sets the delay between each image. Default value is 5000 (milliseconds).

Customizability: Home domain only (on-site)

social-media-first-line (optional) Text value that provides a custom description for the first line of the social media preview (Facebook, Twitter, LinkedIn). If no social-media-first-line, default Control settings from the first image of the gallery are applied.

Customizability: Home domain only (on-site)

social-media-second-line (optional) Text value that provides a custom description for the second line of the social media preview (Facebook, Twitter, LinkedIn). If no social-media-second-line, default Control settings from the first image of the gallery are applied.

Customizability: Home domain only (on-site)

SmartFrame emits custom Javascript events that can be listened to using a standard addEventListener method.

Event name Description
preload Low-resolution placeholder finished loading, SmartFrame present in DOM
load Image file finished loading
resize Viewport size has changed
danger An image-theft attempt has been detected. A detail object is provided, with the type of image theft attempt detected:

{ ‘origin’: ‘type’ }

  • right-click – right-click was detected
  • screenshot – screenshot attempt was made
  • programmatic – an attempt to programmatically obtain access to the image was made
error This event is emitted when there is:

  • any problem with image itself and other sources (missing sfm, sfi, theme, etc.)
  • a malformed response (invalid data)
  • a blocked embed
  • a sandbox detection
  • a deleted image

Test mode

This is activated when ‘__sfDisableTracking’ global window variable is set to true.

The snippet that sets it (below) needs to be added in <head> section of the page

<script>window.__sfDisableTracking = true;</script>

How SmartFrame renders on the page

As soon as SmartFrame is initiated, a very low-resolution JPEG placeholder is displayed at the same size as the target image. This reduces the perceived loading time and creates a smooth user experience. In addition, the image height is immediately reserved on the page, which minimizes shifting of content layers while images load.

If the SmartFrame lies outside the viewport, it will be prepared for display. Further loading is paused to save bandwidth until the SmartFrame comes into view (lazy loading). The SmartFrame is initiated and the content is displayed as soon as the user expects to see it. At that point, the image is rendered on a <canvas> object placed inside the <smartframe-embed> tag, which eliminates the need for an image file and prevents unwanted image downloads.

SmartFrame detects the screen size and pixel density of the user’s display, and requests the most appropriate resolution from the server. This optimizes bandwidth and ensures that the image is always clear, even on more demanding HiDPI or Apple Retina displays. When the image size is changed – due to resizing the browser window, resizing the container layer, or changing the screen’s orientation – the image on the page is resized to fit the new size. If SmartFrame determines that it may not look sharp, a higher-resolution image is requested from the server and automatically inserted into the frame. This method is also activated when a user pinches a mobile or tablet screen to zoom into the image.

You can adjust the SmartFrame size on the demo below and observe the loading behavior:

Full width
Custom width
Browser width

Styling SmartFrame with CSS

<smartframe-embed> replicates <img> tag behavior as closely as possible. It’s a Web Component and can be styled with plain CSS. SmartFrame is an inline-block element by default and maintains aspect ratio.

If you are converting your existing website to use SmartFrame, your CSS styles might be mapped to <img> selector. In this case, you will need to map those styles to the <smartframe-embed> selector.

Differences between <img> and <smartframe-embed> styling

SmartFrame emits custom Javascript events that can be listened to using a standard addEventListener method.

Image file SmartFrame
When the aspect ratio is changed stretch crop
When the image container is enlarged upscale the existing image load a higher-resolution image to match the new size
When the image is outside the viewport always displayed only displayed if in the viewport
To limit the maximum height of the image use max-height CSS property use sf-max-height CSS property
To limit the maximum width of the image use max-width CSS property use sf-max-width CSS property

Notes:

  • Scaled SmartFrames will retain the original aspect ratio unless width and height properties are set to a fixed value, just like an <img> tag.
  • By default, SmartFrame will not exceed the parent container width.

You can use the demo below to test a SmartFrame’s behavior when resizing.