A guide to optimizing your site for Iframely

This document describes how to optimize your web-hosted content that people share to apps that use Iframely.

In this document:

Target Iframely with your meta

When an end-user shares URL to your webpage in one of the Iframely user apps, our robot gathers meta information from your website or app to present that URL to other people and engage them.

We use Facebook’s Open Graph, Twitter Cards, oEmbed and Google’s Structured Data. If none are present, we’ll use your SEO tags for title and description.

Iframely uses metadata to create a summary card so your content gets better engagement. Our customers, however, may opt to get plain data via API and build their URL previews on their instead.

Here’s an example of how it may look.

Summary preview

Or in a compact form

If you optimized the website for social sharing, you don’t necessarily need to do anything else.

Meta markup

You may override any piece of meta we get for your URLs with Iframely-prefixed Open Graph tags:

<meta property="iframely:title" content="…" />
<meta property="iframely:description" content="…" />
<meta property="iframely:image" content="…" />
…

This data will have the highest priority over all other available sources. You may define any of the meta fields that Iframely supports, such as author and date.

Media card attachment

Iframely can create a media card if we find a rich media attachment on your page.

By default, we recognize the most popular video platforms in your Open Graph video, Twitter players and VideoObject structured data. The known publishers include YouTube, Vimeo, Dailymotion, SoundCloud, Brightcove, and tens of others.

We treat it as an “attachment” and generate the media card like these:

Attachment

Compact & click-to-play

You can also “attach” a video explicitly for Iframely from any of the supported media publishers via attach meta field this way:

<meta
  name="iframely:attach"
  content="https://players.brightcove.net/…/index.html?videoId=5847524533001"
/>

Publish your rich media to Iframely

In addition to media attachments from known sources, you can host and publish your own rich media for Iframely. In other words — become a publisher.

Please get your domain listed on Iframely; unrecognized embeds are not allowed.

Discovery via `<link>` meta tag

If your rich media embeds as an iFrame, let Iframely discover it via custom <link> in the <head> section of your page:

<link
  rel="iframely"
  href="https://video.vice.com/en_us/embed/5a5f86d2177dd408e5604453"
  media="(aspect-ratio: 1280/720)"
/>
<!--
  [rel]:   Target Iframely,
  [type]:  optional, "text/html" to publish embed as iFrame
  [href]:  with this href as src
  [media]: and with this size
-->

Iframely translates such link into the following responsive embed code:

<div style="width: 100%; height: 0px; position: relative; padding-bottom: 56.25%;">
  <iframe
    src="https://video.vice.com/en_us/embed/5a5f86d2177dd408e5604453"
    style="width: 100%; height: 100%; position: absolute;"
    frameborder="0">
  </iframe>
</div>

Discovery via link

Discovery via `link` HTTP header

If it is simpler for you to set Link Headers, publish your Iframely link this way:

Link: <https:// … >; rel="iframely"; type="text/html"; media="…"

Link’s `href` attribute

Link’s href is a source of a media element, primarily an src attribute of an iFrame. Because iFrame is our default case, type optional there. Or you can publish it as text/html for an explicit value.

href can also point to images with the corresponding image type.

Link’s `rel` attribute

Rel is a string representing an array of space-separated values:

rel list should start with iframely to recognize that you publish for us.
Add primary functional rel from the list of recognized rels, for example, rel="iframely player" for video players. If omitted, we use app as default. You can also publish thumbnail images.
Optionally add information rels such as audio and playlist (rel="iframely player audio");
Or required feature-policy directives. We’ll pass them into allow attribute of the embedded iFrame code (rel="iframely player encrypted-media").
Please add playerjs into rel if you publish a player that supports playback events.

Please do not include autoplay if you need it for feature-policy. It’s not supported and will be considered as functional rel instead. Your player will be handled as auto-starting and requiring a click-to-play cover.

Link’s `media` attribute

Media represents your iFrame’s sizing. It is an optional attribute, with the default fixed aspect-ratio of 16/9 for iFrames and sizing auto-detect for images.

Any sizing media query from the supported dictionary works. If you need another aspect-ratio, include it as this:

<link … media="aspect-ratio: 4/3;"/>

To add a max-width or small fixed padding on top or at the bottom, use max-width and padding-bottom, respectively, in pixels:

<link … media="aspect-ratio: …; max-width: 640; padding-bottom: 16"/>

“Horizontal” iFrame

“Horizontal” iFrame is the media case worth a separate paragraph. It is an iFrame that resizes to 100% width with a fixed height.

To achieve that, provide just height: … (in pixels) as your media attribute:

<link rel="iframely app" type="text/html" href="…" media="height: 420" />

If you want end-users to change the height of your iFrame, please add resizable into rel of your link. We will then add the height mechanism to user options.

MP4s, audio and images `type`

type attribute is optional, defaulting to text/html for an iFrame embed.

Similarly, you can publish MP4 and streaming video sources, audio and images simply by choosing a type from supported MIME types. For images, you may omit the media sizing altogether.

Embeds with dynamic sizes and oEmbed

If the height of your iFrame needs to change depending on the user device and available space, you’d likely need to include <script> in there and pass the entire html to Iframely.

Please make it available for oEmbed discovery and submit your site for review.

Target specific Iframely user apps

Like optimizing for the entire Iframely network, you may target specific Iframely user apps, provided they share with you their app name.

Ask the app’s support team about that information if needed. If you get click-throughs from the app with a correctly set up name in Iframely, you’ll get the name added as referring &utm_source=… parameter. The most common choice for an app name is the company/product/web domain name.

If you’re an Iframely app owner, your app name is a string you will be soon able to submit in your settings. For now, reach out to support to configure.

Override meta

Knowing app name, you can optimize your website for it via {AppName}: prefix of Open Graph. For example,

<meta property="drift:title" content="…" />

As an Iframely app owner, you can enter other app’s name to consume meta the way they do. For example, og to consume Open Graph meta as Facebook, or twitter to consume it as Twitter.

Target apps with rich media

Similarly, you can target apps with the specific rich media:

<link rel="atlassian" href="…" type="text/html" media="aspect-ratio: 16/9" />

If your rich media is targeted, skip iframely from the rel and leave on app name. Only that specific app will receive your media.

Target a user-agent

App owner can also submit their extension to Iframely’s default user-agent string. Our robot will add it at the end of the UA string. By default, the extension is the capitalized app name, if any:

Iframely/1.3.1 (+https://iframely.com/docs/about)
Iframely/1.3.1 (+https://iframely.com/docs/about) Atlassian
Iframely/1.3.1 (+https://iframely.com/docs/about) Bloomberg
…

Please see how to allow Iframely robot on your network based on user-agent and IPs.

Troubleshoot Iframely robot access

Basic robot requirements:

Your server must use gzip, deflate or brotli encodings.
Any meta properties and Iframely <link> needs to be listed in the <head> section of your website or app, or they will be cutoff.
Ensure that your server replies to our robot within 10 seconds. Iframely will otherwise raise a timeout error and will not be able to display your content.
If your website or app supports several language, you can return relevant variant following Iframely’s accept-language request header.
Add to your allow list either the user agent strings or the IP addresses used by Iframely robot.
If your website uses React, Angular, Redux or other similar SPA technologies, prerender your pages and meta for Iframely robot.
Make sure Iframely robot can access iFrame src of your embed code. We will verify that iFrame source are valid, and will make sure that no x-frame-options or frame-ancestors are accidentaly set up.
Your rich media needs to be listed to be allowed. Submit here.

To check how Iframely sees your webpage, please use content sharing debugger.