像 Facebook 和 Instagram 这样的网站为开发者提供了一个 oEmbed 端点。Iframely 服务会从公共互联网上的网站创建嵌入内容。对于私有网络（例如企业 CMS）中的内容，本文档概述了如何丰富内容或构建一个 API，以便 Enhanced Media Embed 服务器利用它来创建丰富的超链接。我们还将提供有关 Enhanced Media Embed 服务器摘要卡片的一些信息。

Enhanced Media Embed 服务器为私有内容创建的嵌入有三种增强选项：

  • 使用 Open Graph 或其他元标签注释内容

  • 开发返回 oEmbed 格式 JSON 的自定义端点

  • 开发返回 TinyMCE Enhanced Media Embed 格式 JSON 的自定义端点

关于 Cookie 和认证的说明

如果内容或端点与 Enhanced Media Embed 服务器位于同一域名下，Cookie 将转发到该服务器。这应该复用 CMS 环境中用户的现有登录状态。

示例如下：

  • Enhanced Media Embed 服务器的可访问地址为 http://mydomain.example.com/media

  • 您的自定义 oEmbed 端点的可访问地址为 http://mydomain.example.com/endpoint

  • 您已在 http://mydomain.example.com/cms 处登录到您的 CMS

  • 您从 http://mydomain.example.com/cms/secretcontent 嵌入内容，该内容通常需要认证才能访问

  • 因为您的内容、oEmbed 端点和 Enhanced Media Embed 服务器都在同一域名下，所以可以使用 Cookie 透传嵌入 http://mydomain.example.com/cms/secretcontent

使用 Open Graph 或其他元标签注释内容

Open Graph

如果您的内容使用了 Open Graph 标签标记，并且可以通过 HTTP GET 请求从 Enhanced Media Embed 服务器访问，那么将根据您的内容创建名片样式的嵌入。

如果在配置中启用了 Iframely，则 Open Graph 查找将由 Iframely 执行。Iframely 要求内容必须在互联网上公开可访问。

至少，您需要定义以下 Open Graph 标签：

  • og:title

  • og:image

建议同时定义以下内容：

  • og:url

  • og:description

  • og:site_name

此外，您可以通过定义以下内容来指定要包含在嵌入中的视频或音频资源：

  • og:video 和 og:video:type（所有浏览器仅支持 MP4）

  • og:audio 和 og:audio:type（所有浏览器仅支持 MP3）

SEO 标签

作为 Open Graph 标签的替代方案，您可以使用搜索引擎（如 Google）推荐的旧式风格包含元标签。

  • <title>...</title>

  • <meta name="description">...</meta>

  • <link rel=image_src href="..." />

优点

  • 这是在没有现有嵌入 API 的情况下创建嵌入的最简单方法

  • 无需服务器配置

  • 存在现有的 CMS 插件可以将这些标签添加到内容中

  • Enhanced Media Embed 服务器将负责创建嵌入 HTML 和样式

缺点

  • 页面必须对 Enhanced Media Embed 服务器可访问（不能需要认证）

  • Enhanced Media Embed 服务器创建的嵌入 HTML 和样式不可配置

  • 仅适用于 HTML URL

  • Iframely 只能作为全局选项启用或禁用。如果启用了 Iframely，则所有内容必须对世界开放，且不会发生 Cookie 透传。

自定义 API

作为在内容中包含元标签的替代方案，您可以编写一个自定义 API，以 oEmbed 或 TinyMCE Enhanced Media Embed 格式返回 JSON。

有关如何让 Enhanced Media Embed 服务器利用您的自定义 API 的详细信息，请参阅配置自定义端点文档。

oEmbed 端点

这是一个流行的选择，许多 CMS 都有支持 oEmbed 的现有插件。虽然您可以通过这种方式创建自定义 HTML 嵌入，但它们不能包含脚本。如果 HTML 包含脚本，则 Enhanced Media Embed 服务器将嵌入一个 摘要卡片。

优点

  • 存在支持 oEmbed 的现有 CMS 插件

  • 您可以编写自己的自定义 HTML

缺点

  • 该规范中没有为同一 URL 的多个嵌入表示留出空间

  • 必须是单独的 API，而不是仅仅嵌入在内容中的元数据

  • 错误消息未作为规范的一部分定义

TinyMCE Enhanced Media Embed 端点

开发自定义 API 端点的另一种选项是返回 TinyMCE Enhanced Media Embed 格式的 JSON。

优点

  • 您可以编写自己的自定义 HTML

  • 该格式能够容纳同一 URL 的多个嵌入表示

  • 更好地定义了向媒体服务器传达错误的能力

缺点

  • 必须是单独的 API，而不是仅仅嵌入在内容中的元数据

  • 现有插件不支持

  • TinyMCE 编辑器尚未充分利用此格式

TinyMCE Enhanced Media Embed 格式

HTTP 响应状态码

  • HTTP 200 (OK): EphoxEmbedObj

  • HTTP 400 (用户错误): ErrorObj

  • HTTP 503 (上游错误): ErrorObj

  • HTTP 500 (意外错误): ErrorObj

JSON 响应对象

EphoxEmbedObj

rel、media 和 html 组合形成您服务器选择的可嵌入资源的默认表示。Enhanced Media Embed 服务器的客户端（例如 TinyMCE 编辑器）可以在 links 中查找替代表示。

  • title（可选）

    • 包含文档标题的字符串。

  • author_name（可选）

    • 包含作者姓名的字符串。

  • author_iri（可选）

    • 包含作者 IRI 的字符串。

  • provider_iri（可选）

    • 包含资源提供者 IRI 的字符串。

  • provider_name（可选）

    • 包含资源提供者名称的字符串。

  • short_iri（可选）

    • 包含资源缩短 IRI 的字符串。

  • canonical_iri（必需）

    • 包含资源 IRI 的字符串。

  • description（可选）

    • 包含文档描述的字符串。

  • cache_age（可选）

    • 包含该资源建议缓存寿命（秒）的整数。

  • date（可选）

    • 包含文档日期的字符串，格式为 YYYY-MM-DD。

  • links（必需）

    • LinksObj

  • rel（可选）

    • RelObj

  • media（可选）

    • MediaObj

  • html（可选）

    • 包含 TinyMCE 要嵌入的 HTML 片段的字符串。

RelObj

一个描述嵌入主要类型、来源以及您可能想知道的任何技术属性（自动播放、ssl、文件格式（flash、html5 等））的标签数组。

  • primary（必需）

    • PrimaryRels 数组

  • technical（必需）

    • TechnicalRels 数组

  • source（必需）

    • SourceRels 数组

PrimaryRel

一个描述嵌入主要类型的字符串，包含以下值之一：

  • player：视频或音频播放器

  • thumbnail：资源的缩略图表示

  • image：资源的完整尺寸图像

  • reader

  • file：未提供 HTML。应仅为可下载文件的超链接。

  • survey

  • app：如果在移动设备上播放，将切换到移动应用的嵌入（例如 soundcloud）

  • summary：摘要卡片（无脚本嵌入）

  • icon

  • logo

  • promo

TechnicalRel

描述嵌入技术属性的字符串，包含以下值之一：

  • flash

  • html5

  • gifv

  • inline

  • ssl

  • autoplay

SourceRel

描述嵌入来源的字符串，包含以下值之一：

  • iframely: 来自 Iframely

  • opengraph: 从资源中的 Open Graph 标签生成

  • twitter: 从 Twitter Card 检索

  • oembed: 从 oEmbed API 检索

  • sm4

  • fallback: Ephox 回退嵌入，检查 SEO 标签和 Open Graph 标签。

  • script_censor: 原始嵌入（来自 Iframely 或 oEmbed）包含脚本，已转换为摘要卡片。

  • smartframe_censor: 原始嵌入包含 Iframely 智能框架，已被审查转换为摘要卡片，以避免对 Iframely 的内容依赖。

LinksObj

表示此资源的所有可能表示形式。

  • players (必填)

    • LinkObjs 数组

  • thumbnails (必填)

    • LinkObjs 数组

  • apps (必填)

    • LinkObjs 数组

  • readers (必填)

    • LinkObjs 数组

  • surveys (必填)

    • LinkObjs 数组

  • summary_cards (必填)

    • LinkObjs 数组

  • icons (必填)

    • LinkObjs 数组

  • logos (必填)

    • LinkObjs 数组

  • promos (必填)

    • LinkObjs 数组

  • images (必填)

    • LinkObjs 数组

  • files (必填)

    • LinkObjs 数组

LinkObj

这表示您可以链接到 / 嵌入的表示形式。

  • media (可选)

    • MediaObj

  • rels (必填)

    • RelObj

  • href (可选)

    • 包含资源 URL 的字符串。

  • mime_type (必填)

    • 包含资源 mime-type 的字符串。

  • html (必填)

    • 包含可嵌入 HTML 片段的字符串。

MediaObj

媒体对象描述嵌入的边界。它可以是 响应式 或 固定 的。

  • type (必填)

    • 值为 `fixed` 或 responsive 的字符串

当 type 为 fixed 时的字段：

  • width (必填)

    • 包含以像素为单位的宽度的整数。

  • height (必填)

    • 包含以像素为单位的高度的整数。

  • paddingBottom (可选)

    • 整数

当 type 为 responsive 时的字段：

  • aspectRatio (可选)

    • 双精度数

  • paddingBottom (可选)

    • 整数

  • width (必填)

    • DimensionBoundObj

  • height (必填)

    • DimensionBoundObj

DimensionBoundObj

维度边界定义响应式嵌入的高度或宽度。

  • type (必填)

    • 值为 fixed、constrained 或 unbounded 的字符串

当 type 为 fixed 时的字段：

  • pixels (必填)

    • 整数

当 type 为 constrained 时的字段：

  • min_pixels (可选)

    • 整数

  • max_pixels (可选)

    • 整数

当 type 为 unbounded 时无其他字段。

ErrorObj

  • code (必填)

    • 值为 400 (用户输入错误) 或 502 (上游故障) 的整数

  • subcode (必填)

    • 具有下列值之一的整数：

      • 当 code 为 502 时：

        • 1 - 上游连接问题

        • 2 - 上游返回非 OK

        • 3 - 上游返回服务器无法理解的响应

      • 当 code 为 501 时：

        • 1 - 未实现 URI 支持

      • 当 code 为 400 时：

        • 1 - URI 解析失败

        • 2 - URI 是相对的

        • 3 - URI 为空

        • 4 - URI 不是 http 或 https

        • 5 - 最大宽度不是正整数

  • msg (必填)

    • 给开发人员 / 支持人员的字符串消息。

摘要卡片

当 Enhanced Media Embed 服务器生成 URL 的摘要卡片（使用标题、缩略图、描述和网站）时，它会返回如下所示的 HTML 片段。您应将样式应用于文档样式以符合您的偏好。

<div class="ephox-summary-card">
  <a class="ephox-summary-card-url-thumbnail" href="http://www.imdb.com/title/tt0117500/">
    <img class="ephox-summary-card-thumbnail" src="https://images-na.ssl-images-amazon.com/images/M/MV5BZDJjOTE0N2EtMmRlZS00NzU0LWE0ZWQtM2Q3MWMxNjcwZjBhXkEyXkFqcGdeQXVyNDk3NzU2MTQ@._V1_UY1200_CR90,0,630,1200_AL_.jpg">
  </a>
  <a class="ephox-summary-card-link" href="http://www.imdb.com/title/tt0117500/">
    <span class="ephox-summary-card-title">The Rock (1996)</span><br><br>
    <span class="ephox-summary-card-description">Directed by Michael Bay.  With Sean Connery, Nicolas Cage, Ed Harris, John Spencer. A mild-mannered chemist and an ex-con must lead the counterstrike when a rogue group of military men, led by a renegade general, threaten a nerve gas attack from Alcatraz against San Francisco.</span><br><br>
    <span class="ephox-summary-card-website">IMDb</span>
  </a>
</div>

推荐 CSS

.ephox-summary-card {
  border: 1px solid #AAA;
  box-shadow: 0 2px 2px 0 rgba(0,0,0,.14), 0 3px 1px -2px rgba(0,0,0,.2), 0 1px 5px 0 rgba(0,0,0,.12);
  padding: 10px;
  overflow: hidden;
  margin-bottom: 1em;
}

.ephox-summary-card a {
  text-decoration: none;
  color: inherit;
}

.ephox-summary-card a:visited {
  color: inherit;
}

.ephox-summary-card-title {
  font-size: 1.2em;
  display: block;
}

.ephox-summary-card-author {
  color: #999;
  display: block;
  margin-top: 0.5em;
}

.ephox-summary-card-website {
  color: #999;
  display: block;
  margin-top: 0.5em;
}

.ephox-summary-card-thumbnail {
  max-width: 180px;
  max-height: 180px;
  margin-left: 2em;
  float: right;
}

.ephox-summary-card-description {
  margin-top: 0.5em;
  display: block;
}