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 1280px.
Customizability: All |
|
| 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: All |
| 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’ }
|
| error | This event is emitted when there is:
|
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:
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.