1. Docs

Iframely Whitelist File Format

Iframely parsers relies on the whitelist file to allow rich media embeds via Iframely Protocol, oEmbed, Twitter Cards and Open Graph.

The central whitelist is already included with default config of the self-hosted open-source Iframely. Your Iframely instance will fetch the file updates periodically from our servers.

Here’s the up-to-date version of the file http://iframely.com/qa/whitelist.json.

If you like, you can download it, change and upload into /whitelist folder of your Iframely server to replace the default behaviour. Or generate your own file altogether based on the structure defined below.

Basic file structure

For your own file, its name should contain the timestamp when the whitelist was last updated:

iframely-2022-06-21-18-00-UTC.json

This way you may upload the new files to your server’s directory and update them without restart of the server.

The file itself contains the list of domains, with the protocols the domains support and extra information to craft best user experience:

{
  "youtube.com": {
    "date": "1485789423106",
    "og": {
      "video": ["allow", "ssl", "responsive"]
    },
    "oembed": {
      "video": ["allow", "responsive"]
    },
    "twitter": {
      "player": ["allow", "ssl", "responsive"]
    }
  },
  "mashable.com": {
    "date": "1485789423106",
    "twitter": {
      "photo": "deny",
      "player": ["allow", "ssl", "responsive", "autoplay"]
    }
  },
  "*.nbcsports.com": {
    "date": "1485789423106",
    "oembed": {
      "link": ["allow", "reader"]
    }
  },
  "iframe.ly": {
    "date": "1485789423106",
    "iframely": {
      "reader": "allow",
      "player": "allow",
      "survey": "allow",
      "image": "allow",
      "thumbnail": "allow",
      "logo": "allow"
    },
    "twitter": {
      "player": "allow",
      "photo": "allow"
    },
    "og": {
      "video": "allow"
    },
    "oembed": {
      "video": "allow",
      "photo": "allow"
    }
  }
}

The domain name is given as the top-level key.

Its value contains an object with keys equal to protocol names and values listing the tags associated with the domain-protocol pair. Type within a protocol is at the bottom of hierarchy, followed by the list of QA results as a list of tags.

If the protocol is not supported by the domain, the value of domain.protocol will be null. If we did not test the domain yet, domain will be null. If domain does not support specific type on the protocol, then domain.protocol.type will be null.

The basic and most important values in tags list are:

  • "allow" — means the domain-protocol is whitelisted
  • "deny" — indicates that domain-protocol does not provide reliable or expected user experience

date value for the domain gives the date when this domain was last updated with the test results. The format is the number of milliseconds since 1970/01/01. You may opt to ignore test results that are not recent enough for your needs.

Choosing proper domain object

The domain names are given as the top-level keys for the convenience of querying the values.

However, whitelist supports wildcard entries, such as "*.sub.domain.com" and you would need to choose a proper key.

We suggest the following algorithm. Let’s say you have the URL http://name.sub.domain.com/slug:

  1. Check if name.sub.domain.com exists. If it does, use as value.
  2. Check if *.sub.domain.com exists. If it does, use as value.
  3. Check if *.domain.com exists. If it does, use the value (otherwise — we don’t have info about the domain).

The domains use variety of URL structures, and sometimes we need to allow the top domain, but block some of the sub-domains, or whitelist all subdomains except only one. The algorithm above covers the logic of how we do it.

Please, note that www.domain.com and domain.com are the same in most cases. If you meet URLs with www and we do not list it explicitly as www.domain.com, check domain.com rather than *.domain.com. We try to be as careful about www as we can, but since it is a manual QA process, human error is always a factor.

Protocols

Iframely QA team tests the following protocols and types:

  • iframely is for Iframely protocol (see spec types:
  • player
  • reader
  • image
  • survey
  • oembed is for oEmbed types:
  • video
  • photo
  • rich
  • og is for Facebook Open Graph types. However, we only test video type.
  • twitter is for Twitter Cards:
  • player
  • photo
  • html-meta protocol with video type is for QA results on video_src meta tag.

Please, note, that Twitter’s photo card allows the fallback onto og:image if twitter:image is not provided. Such cards may be approved by Iframely as well.

QA result tags: allow or deny

The basic and most important values in tags list are:

  • "allow" — means the domain-protocol is whitelisted
  • "deny" — indicates that domain-protocol does not provide reliable or expected user experience

The naming of those tags is analogous to X-FRAME-OPTIONS header. Except you, the consumer, are now the one that needs to allow or deny the widget.

We also give the extra tags that you can program the user experience upon:

Additional responsive tag

The responsive tag is used for videos and players, if fixed width and size are given (or are omitted all together). You can program to resize the videos and players to bigger sizes, maintaining the aspect-ratio.

You can see it in following protocol-type combinations: oembed video, og video, twitter player, html-meta video.

For oembed video, this tag also means that you need to extract the value of attribute src of an <iframe> within html code (and we only assign this tag for oembed html with iframes in it).

Additional html5 tag

If the media works on mobile, there should be html5 flag, which will be proxied in API responses.

Additional ssl tag

If https is the transport protocol of frames in embed code, we verify that the SSL certificate is valid and does not generate browser errors on load and does not break the lock of the browser. Passive mixed content browser warnings when the video or audio starts to play may still occur.

For og video it also verifies the value of og:video:secure_url attribute.

Additional autoplay tag

This tag is present if the media starts to play automatically without the user interaction. You may opt to isolate such widgets from a user until she confirms the action. For example, putting a thumbnail with a play button above it, and replacing it with the player once user initiates the playback.

Most of og video implementations come with autoplay.

Additional reader tag

For oembed link and oembed rich we add tag reader, in case the html actually contains the complete article. oEmbed spec does not include article types, and so many publishers (WordPress in particular) provider link and rich types instead.

Docs