Iframely

https://iframely.com/docs
Admin
Iframely is a URL unfurling API that fetches semantic data, rich media embeds, and meta information...
Tokens:30,887
Snippets:383
Trust Score:10
Update:4 months ago
Show doc for...
Tokens:
Raw
### Start Iframely with PM2 Process Manager

Source: https://iframely.com/docs/host

Install PM2 globally and use its configuration file to start the Iframely application.

```bash
npm install pm2 -g
pm2 start pm2.json
```

--------------------------------

### Start Iframely with Forever Process Manager

Source: https://iframely.com/docs/host

Install Forever globally and use it to start the Iframely cluster in the background, logging output.

```bash
npm install forever -g
forever start -a -l iframely.log --killSignal=SIGTERM cluster.js
```

--------------------------------

### Start Development Environment with Vagrant

Source: https://iframely.com/docs/host

Use this command to bring up the development environment managed by Vagrant.

```bash
vagrant up
```

--------------------------------

### Full Options Object Example (CodePen)

Source: https://iframely.com/docs/options

An example of a comprehensive options object including theme color (radio group), click-to-load (checkbox), and height adjustment (text input), along with query parameters.

```json
options: {
	_theme: {
		value: "dark",
		values: {
			auto: "Default",
			dark: "Dark",
			light: "Light"
		},
		label: "Theme color"
	},
	_click_to_load: {
		value: true,
		label: "Use click-to-load"
	},
	_height: {
		value: "600",
		label: "Adjust height",
		placeholder: "ex.: 600, in px",
	},
	query: ["_height", "_theme"]
}
```

--------------------------------

### YouTube Start Time Option

Source: https://iframely.com/docs/options

Illustrates a text input type for a YouTube-specific option, enabling users to set a specific start time for a video.

```json
_start: {
	value: "7",
	label: "Start from",
	placeholder: "ex.: 11, 1m10s"
}
```

--------------------------------

### Install libkrb5-dev for GSSAPI

Source: https://iframely.com/docs/host

Install the libkrb5-dev package if you encounter GSSAPI-related errors during npm install.

```bash
sudo apt-get install libkrb5-dev
```

--------------------------------

### Clone Iframely and Install Dependencies

Source: https://iframely.com/docs/host

Clone the Iframely repository from GitHub and install its Node.js dependencies.

```bash
cd <your servers dir>
git clone https://github.com/itteco/iframely.git
cd iframely
npm install
```

--------------------------------

### Run Iframely Server

Source: https://iframely.com/docs/host

Start the Iframely server from its home directory using Node.js.

```bash
node server
```

--------------------------------

### Example HTML with Feature Class Names

Source: https://iframely.com/docs/omit-css

This example shows an Iframely embed for YouTube, including feature-specific class names like 'iframely-youtube' and 'iframely-player'. These allow for fine-grained CSS control.

```html
<div class="iframely-youtube iframely-player iframely-embed">
	<div class="iframely-responsive">
		<iframe src="…"></iframe>
	</div>
</div>
```

--------------------------------

### Example Whitelist Filename

Source: https://iframely.com/docs/whitelist-format

A whitelist file should be named with a timestamp to indicate when it was last updated. This allows for easy updates without server restarts.

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

--------------------------------

### Example Meta Object

Source: https://iframely.com/docs/meta

This is an example of the meta object structure returned by the Iframely API, showcasing various metadata fields.

```json
"meta": {
  "title": "Input/Output",
  "description": "A new short from Terri Timely and Park Pictures",
  "author_url": "https://vimeo.com/user1946955",
  "author": "Terri Timely",
  "site": "Vimeo",
  "canonical": "https://vimeo.com/141567420",
  "duration": 249,
  "date": "2015-10-06",
  "medium": "video"
}
```

--------------------------------

### Domains Widget with Dark Theme and Small Icons

Source: https://iframely.com/docs/domains-widget

Customize the widget's appearance by setting attributes like 'theme' and 'icon-size'. This example demonstrates a dark theme with small icons.

```html
<iframely-domains theme="dark" icon-size="small"></iframely-domains>
<script type="module" src="https://iframely.net/domains.js"></script>
```

--------------------------------

### Run Iframely Server in Cluster Mode

Source: https://iframely.com/docs/host

Start the Iframely server in cluster mode for better CPU utilization on multi-core systems.

```bash
node cluster
```

--------------------------------

### Iframely User-Agent Strings

Source: https://iframely.com/docs/webmasters

Examples of user-agent strings used by the Iframely robot. You can append your app name to these strings.

```text
Iframely/1.3.1 (+https://iframely.com/docs/about)
```

```text
Iframely/1.3.1 (+https://iframely.com/docs/about) Atlassian
```

```text
Iframely/1.3.1 (+https://iframely.com/docs/about) Bloomberg
```

--------------------------------

### Example Link Object Structure

Source: https://iframely.com/docs/links

This object represents a media link with its source, functional rels, MIME type, media attributes, and optional HTML embed code.

```json
{
	// SRC of embed. The main attribute
	// can be omitted for apps, for example Twitter and Facebook.
	"href": "https://player.vimeo.com/video/141567420",

	// functional and technical use cases.
	"rel": ["player", "autoplay", "html5"],

	// MIME type. Tells: "embed as iFrame"
	"type": "text/html",

	"media": {
		// Media query. Mostly responsive
		"aspect-ratio": 1.777778
	},

	// plus generated or native HTML code:
	"html": "<div …></div>"
}
```

--------------------------------

### Example of Click-to-play for General Videos

Source: https://iframely.com/docs/click-to-play

This snippet demonstrates how a YouTube video is wrapped in Iframely's 'click-to-play' iFrame helper. It's used for general video embedding to prevent autoplay.

```html
<iframe src="//iframe.ly/api/iframe?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3D_Oat-5a5_10&key=YOUR_API_KEY" width="640" height="360" scrolling="no" frameborder="0" allowfullscreen sandbox="allow-scripts allow-same-origin allow-popups"></iframe>
```

--------------------------------

### Example of Single Value Option Mapping

Source: https://iframely.com/docs/options

Treat single 'values' as a checkbox. If checked, send the actual value; if unchecked, skip the parameter.

```javascript
media: {
	value: "",
	values: {
		"1": "Just the image"
	}
}
```

--------------------------------

### Installing Iframely embed.js via npm

Source: https://iframely.com/docs/angular

Add Iframely's embed.js as a project dependency using npm. This ensures the script is managed by your project's package manager.

```json
"name": "iframely.angular",
"dependencies": {
  "@iframely/embed.js": "^1.3.1",
  …
}
```

--------------------------------

### oEmbed API Request

Source: https://iframely.com/docs/oembed-api

Make an HTTP GET request to the oEmbed API endpoint with the URL to be embedded. Required parameters include the URL and an API key. The URL must be URL-encoded. The API key can be substituted with its MD5 hash for added security.

```APIDOC
## GET /oembed

### Description
Fetches embeddable HTML code for a given URL using the oEmbed protocol.

### Method
GET

### Endpoint
`/oembed`

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL to be embedded. Must be URL-encoded.
- **api_key** (string) - Required - Your Iframely API key.
- **key** (string) - Optional - The MD5 hash of your API key for additional security.

### Request Example
`GET /oembed?url=https%3A%2F%2Fvimeo.com%2F141567420&api_key=YOUR_API_KEY`

### Response
#### Success Response (200)
- **html** (string) - The HTML embed code for the content.
- **type** (string) - The type of content (e.g., "video", "photo", "rich").
- **version** (string) - The oEmbed version.
- **title** (string) - The title of the content.
- **description** (string) - A description of the content.
- **author_url** (string) - The URL of the content author.
- **provider_name** (string) - The name of the content provider.
- **thumbnail_url** (string) - The URL of the content thumbnail.
- **thumbnail_width** (integer) - The width of the thumbnail.
- **thumbnail_height** (integer) - The height of the thumbnail.

#### Response Example
```json
{
	"url": "https://vimeo.com/141567420",
	"type": "video",
	"version": "1.0",
	"title": "Input/Output",
	"description": "A new short from Terri Timely and Park Pictures",
	"author": "Terri Timely",
	"author_url": "https://vimeo.com/user1946955",
	"provider_name": "Vimeo",
	"thumbnail_url": "https://i.vimeocdn.com/…5aebf015a6472-d_295x166",
	"thumbnail_width": 295,
	"thumbnail_height": 166,
	"html": "<div style=\"left: 0px; width: 100%; height: 0px; position: relative; padding-bottom: 56.25%;\"><iframe src=\"https://player.vimeo.com/video/141567420\" style=\"top: 0px; left: 0px; width: 100%; height: 100%; position: absolute;\"></iframe></div>"
}
```
```

--------------------------------

### Example oEmbed API Response for Vimeo

Source: https://iframely.com/docs/oembed-api

This JSON object represents a typical response from the Iframely oEmbed API when requesting embed code for a Vimeo video. It includes metadata such as title, description, author, provider, thumbnail, and the generated HTML embed code.

```json
{
	"url": "https://vimeo.com/141567420",
	"type": "video",
	"version": "1.0",
	"title": "Input/Output",
	"description": "A new short from Terri Timely and Park Pictures",
	"author": "Terri Timely",
	"author_url": "https://vimeo.com/user1946955",
	"provider_name": "Vimeo",
	"thumbnail_url": "https://i.vimeocdn.com/…5aebf015a6472-d_295x166",
	"thumbnail_width": 295,
	"thumbnail_height": 166,
	"html": "<div style=\"left: 0px; width: 100%; height: 0px; position: relative; padding-bottom: 56.25%;\"><iframe src=\"https://player.vimeo.com/video/141567420\" style=\"top: 0px; left: 0px; width: 100%; height: 100%; position: absolute;\"></iframe></div>"
}
```

--------------------------------

### Example Iframely API Response for Vimeo

Source: https://iframely.com/docs/iframely-api

This JSON response illustrates the data structure returned by the Iframely API for a Vimeo URL, including 'id', 'url', 'rel', 'html', 'meta', and 'links'.

```json
{
  "id": "qH98az",

  // URL Content ID (if available) plus canonical URL
  "url": "https://vimeo.com/141567420",

  // Rel use cases and html code for primary variant of embed
  // Check for `autoplay` if you requested it
  "rel": ["player", "ssl"],

  // That's the embed code we recommend
  "html": "<div …>…</div>",

  // Meta object with attribution & semantics
  "meta": {
    "title": "Input/Output",
    "description": "A new short from Terri Timely and Park Pictures",
    "author_url": "https://vimeo.com/user1946955",
    "author": "Terri Timely",
    "site": "Vimeo",
    "canonical": "https://vimeo.com/141567420",
    "duration": 249,
    "date": "2015-10-06",
    "medium": "video"
  },

  // Plus list of all media that we have for this URL
  // Embed src links with functional rels, for example:
  "links": {

    // List of player embed widgets
    "player": [{

      // SRC of embed
      "href": "https://player.vimeo.com/video/141567420",

      // Functional and technical use cases
      "rel": ["player", "ssl", "html5"],

      // Link's MIME type, says "embed as iFrame"
      "type": "text/html",

      // Media query, e.g. aspects
      "media": {
        "aspect-ratio": 1.777778
      },

      // Plus generated HTML code for simplicity of use
      "html": "<div … ></div>"
    }, {
      …
      // Might have multiple variations of the same player.
      // Say, one that 'autoplay's, one as MP4 video, one as https.
    }],
    "thumbnail": [{
      "media": {
        // Exact sizes here
        "height": 360,
        "width": 640
      },

      // We repeat the same rel for consistency
      "rel": ["thumbnail"],
      "type": "image",

      // "Use href as src of an image"
      "href": "http://cdn1.aka … med_1381670134_00040.jpg"
    }, {
      …
    }],

    // Also possible: header-menu, image (as rel), reader, survey, file, logo, icon

    "icon": [{
      …
    }]
  }}

```

--------------------------------

### Create and Edit Local Configuration

Source: https://iframely.com/docs/host

Copy the sample configuration file to create a local configuration and then edit it to adjust settings.

```bash
cp config.local.js.SAMPLE config.local.js
vi config.local.js
```

--------------------------------

### Fetch Single Content by ID (oEmbed Format)

Source: https://iframely.com/docs/ids

Use this endpoint to retrieve data in oEmbed format for a specific content ID. This call does not require an API key and is publicly accessible.

```bash
iframe.ly/{ID}.oembed
```

--------------------------------

### Build and Run Iframely Docker Container

Source: https://iframely.com/docs/host

Commands to build the Iframely Docker image and run it locally, mapping the configuration file and exposing the necessary port.

```bash
docker build -t iframely:latest .
docker run -it -p 8061:8061 -v $PWD/config.local.js:/iframely/config.local.js --name iframely iframely:latest
```

--------------------------------

### API Call with Caption Option

Source: https://iframely.com/docs/options

Example of an Iframely API call that includes the `_showcaption` option as a query-string parameter to disable showing the author's text caption.

```http
iframe.ly/api/oembed?url={URL}&_showcaption=false
```

--------------------------------

### Click-to-play in a Compact Card Layout

Source: https://iframely.com/docs/click-to-play

This snippet shows a TED video from YouTube embedded in a compact card layout with 'click-to-play' enabled, even if an autoplay variant isn't natively available.

```html
<iframe src="//iframe.ly/api/iframe?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3D_Oat-5a5_10&key=YOUR_API_KEY&card.template=compact" width="640" height="360" scrolling="no" frameborder="0" allowfullscreen sandbox="allow-scripts allow-same-origin allow-popups"></iframe>
```

--------------------------------

### Restore failed unfurls as links

Source: https://iframely.com/docs/embedjs

Source embed.js with the '&cancel=0' parameter to automatically convert cancelled widgets back into standard anchor (<a>) links.

```html
<script async src="https://iframely.net/embed.js?api_key=…&cancel=0"></script>
```

--------------------------------

### Batch Request for Multiple Content IDs (oEmbed Format)

Source: https://iframely.com/docs/ids

Combine up to 100 content ID requests into a single API call for efficiency. IDs are delimited by hyphens. The response contains data in oEmbed format keyed by their respective IDs.

```bash
iframe.ly/{ID1}-{ID2}-…-{IDn}.oembed
```

--------------------------------

### Iframely API Request and Response

Source: https://iframely.com/docs/iframely-api

This snippet outlines the structure of an API request to Iframely and provides an example of a successful JSON response. The API allows fetching comprehensive data about a URL, including embeddable HTML, meta information, and various media links.

```APIDOC
## GET /api/iframely

### Description
Retrieves complete JSON data about a given URL, including embeddable HTML, meta information, and links to publisher media.

### Method
GET

### Endpoint
`/api/iframely`

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL to fetch data for. Must be URL-encoded.
- **api_key** (string) - Required - Your Iframely API key. Alternatively, use the `key` parameter which should be the md5 hash of your API key.
- **key** (string) - Optional - The md5 hash of your API key for additional security.

### Request Example
```
GET /api/iframely?url=https://vimeo.com/141567420&api_key=YOUR_API_KEY
```

### Response
#### Success Response (200)
Returns a JSON object containing:
- **html** (string) - The recommended embed code.
- **url** (string) - The canonical URL or Content ID.
- **rel** (array) - Use cases for embeds (e.g., "player", "thumbnail").
- **meta** (object) - Attribution and semantic metadata about the URL.
- **links** (object) - A collection of all available media variants for the URL, categorized by `rel` (e.g., "player", "thumbnail", "icon").

#### Response Example
```json
{
  "id": "qH98az",
  "url": "https://vimeo.com/141567420",
  "rel": ["player", "ssl"],
  "html": "<div …>…</div>",
  "meta": {
    "title": "Input/Output",
    "description": "A new short from Terri Timely and Park Pictures",
    "author_url": "https://vimeo.com/user1946955",
    "author": "Terri Timely",
    "site": "Vimeo",
    "canonical": "https://vimeo.com/141567420",
    "duration": 249,
    "date": "2015-10-06",
    "medium": "video"
  },
  "links": {
    "player": [
      {
        "href": "https://player.vimeo.com/video/141567420",
        "rel": ["player", "ssl", "html5"],
        "type": "text/html",
        "media": {
          "aspect-ratio": 1.777778
        },
        "html": "<div … ></div>"
      }
    ],
    "thumbnail": [
      {
        "media": {
          "height": 360,
          "width": 640
        },
        "rel": ["thumbnail"],
        "type": "image",
        "href": "http://cdn1.aka … med_1381670134_00040.jpg"
      }
    ],
    "icon": [
      {
        ...
      }
    ]
  }
}
```
```

--------------------------------

### Configure Iframely API Endpoint for Medium Insert Plugin

Source: https://iframely.com/docs/medium

Set the oembedProxy to your Iframely API endpoint. Replace '{your key here}' with your actual API key. This configuration is used when initializing the Medium Insert Plugin.

```javascript
<script>
  $(function () {
    $('.editable').mediumInsert({
      editor: editor,
      addons: {
        embeds: {
          oembedProxy: 'https://iframe.ly/api/oembed?api_key={your key here}'
        }
      }
    });
  });
</script>
```

--------------------------------

### Registering Options via iFrame Message

Source: https://iframely.com/docs/options

Listen for 'options' messages from hosted iFrames to register options and set a context ID for future use.

```javascript
iframely.on('options', function (widget, options) {
	// register options to the context, perhaps invisible
	// set any context ID - you'll need it next
	// when user clicks for the context edit menu
	// show form, using the next method
});
```

--------------------------------

### Graceful Server Reload with PM2

Source: https://iframely.com/docs/host

Perform a graceful reload of the Iframely application managed by PM2.

```bash
pm2 reload iframely
```

--------------------------------

### Handle Domains Widget Click Event

Source: https://iframely.com/docs/domains-widget

Add an event listener to capture when a user clicks on a provider within the domains widget. The event detail contains information about the clicked provider.

```javascript
document.querySelector('iframely-domains').addEventListener('iframely-domains-click', (event) => {
	event.preventDefault();
	// Handle `event.detail` in your code here...
});
```

--------------------------------

### Handle URL Options with Iframely

Source: https://iframely.com/docs/embedjs

Listen for the 'options' event to receive widget and option data. This is useful for building custom forms in text editors for specific URLs, potentially using the `options.js` utility.

```javascript
iframely.on('options', function (widget, options) {
	// Use our options.js to build the options form for your text editor
});
```

--------------------------------

### Graceful Server Restart (Non-PM2)

Source: https://iframely.com/docs/host

Send a SIGUSR2 signal to the cluster.js process to perform a graceful server restart without dropping active connections.

```bash
pkill -USR2 iframely-c
```

--------------------------------

### Update Iframely Package

Source: https://iframely.com/docs/host

Run this command from the Iframely home directory to update the package to the latest version.

```bash
git pull
```

--------------------------------

### Run Iframely iFrame Loader

Source: https://iframely.com/docs/react

Explicitly run Iframely's loader for lazy-loaded content. This is necessary if `window.iframely` is available after your iFrames are loaded. Execute it every time an element is added to ensure safety.

```javascript
window.iframely && window.iframely.load();
```

--------------------------------

### Configure Cache Storage

Source: https://iframely.com/docs/host

Define caching parameters in your local configuration file, specifying the cache engine and its Time To Live (TTL).

```javascript
CACHE_ENGINE: 'memcached',
CACHE_TTL: 0, // In milliseconds. 0 for 'never expire' to let cache engine decide itself when to evict the record
```

--------------------------------

### Targeting Specific Iframely Apps with Meta

Source: https://iframely.com/docs/webmasters

Optimize content for specific Iframely user apps by using an app-specific prefix for Open Graph tags. This allows for tailored meta information delivery.

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

--------------------------------

### Basic Whitelist JSON Structure

Source: https://iframely.com/docs/whitelist-format

This JSON structure defines whitelisted domains, their supported protocols, and specific tags for each protocol-type pair. It includes domains like youtube.com, mashable.com, *.nbcsports.com, and iframe.ly with their respective configurations.

```json
{
	"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"
		}
	}
}
```

--------------------------------

### View Forever Logs

Source: https://iframely.com/docs/host

Access the logs generated by the Forever process manager for the Iframely instance.

```bash
forever logs 0 -fifo
```

--------------------------------

### Fetch Single Content by ID (Iframely Format)

Source: https://iframely.com/docs/ids

Use this endpoint to retrieve Iframely API format data for a specific content ID. This call does not require an API key and is publicly accessible.

```bash
iframe.ly/{ID}.json
```

--------------------------------

### Interactive Feature Parameters

Source: https://iframely.com/docs/parameters

Control interactive elements and formatting for rich media embeds.

```APIDOC
## Interactive Features

### `card=1`
**Description**: Wraps rich media (players, images, apps) in a media card. Use `&card=small` for a compact card layout.

### `amp=1`, `amp=iframely`, `amp=iframe`
**Description**: Formats HTML code output for the Accelerated Mobile Pages (AMP) framework.

### `playerjs=1`
**Description**: Activates Player.js events for playback control where possible. Requires and is delivered via a hosted iFrame.

### `click_to_play=1`
**Description**: Enables click-to-play mode for players, deferring player loading until user interaction.

### `consent=1`
**Description**: Places rich media into a hosted iFrame and activates a consent mechanism before exposing users to third-party content, enhancing privacy.
```

--------------------------------

### View PM2 Logs

Source: https://iframely.com/docs/host

Access the logs generated by the PM2 process manager for the Iframely application.

```bash
pm2 logs
```

--------------------------------

### Domains Widget Click Event Detail Structure

Source: https://iframely.com/docs/domains-widget

The `event.detail` property of the `iframely-domains-click` event provides structured information about the selected provider, including its sitename, domain, slug, and URL.

```javascript
// event.detail
{
  sitename: 'Iframely',
  domain: 'iframely.com',
  slug: 'iframely',
  url: 'https://iframely.com'
}
```

--------------------------------

### Restart Iframely with Forever

Source: https://iframely.com/docs/host

If you are using Forever to manage your Iframely process, use this command to restart it after an update.

```bash
forever restartall
```

--------------------------------

### Optional Data Attributes for Embed Dialog

Source: https://iframely.com/docs/embed-dialog

Specify the exact URL for the embed dialog or a media attachment using these optional data attributes. If 'data-url' is omitted, the current URL is used. 'data-promo' enables promo card generation.

```html
data-url="http://mashable.com/2015/02/13/friday-the-13th/"
data-promo="http://imgur.com/gallery/GlPlsDi"
```

--------------------------------

### Include embed.js with Theme Parameter

Source: https://iframely.com/docs/cards

When manually adding the embed.js script, append the `theme` query-string parameter to the `src` attribute to set the card theme.

```html
<script src="https://iframely.net/embed.js?theme=dark">

```

--------------------------------

### Required Parameters

Source: https://iframely.com/docs/parameters

These parameters are essential for making a valid API request to Iframely.

```APIDOC
## Required Parameters

### `api_key`
**Description**: The API key obtained from your profile. For user-facing applications, you can use the `key` parameter, which is the MD5 hash of your API key, to restrict access.

### `url`
**Description**: The URL-encoded value of the target URL. This must be an HTTP or HTTPS link. Ensure the URL is properly encoded before sending.

**Note**: URLs sent to Iframely should be URL-encoded.
```

--------------------------------

### Batch Request for Multiple Content IDs (Iframely Format)

Source: https://iframely.com/docs/ids

Combine up to 100 content ID requests into a single API call for efficiency. IDs are delimited by hyphens. The response contains JSON objects keyed by their respective IDs.

```bash
iframe.ly/{ID1}-{ID2}-…-{IDn}.json
```
Tokens:
Raw