嵌入文档

说明如何用 iframe 展示应用信息，以及可用的参数。

概述

嵌入是一个放进 iframe 的页面。它渲染与仪表板相同的界面（应用信息、搜索、排行榜、分类、相似应用和新闻），并且无需密钥：下面的一切都由 URL 决定。

读取单个应用的模式（info、similar、news）与 API 相同：选择商店并至少提供该商店的一个标识符。 search 只需关键词；chart 和 category 则什么都不需要。

模式

路径决定框架绘制什么。不带路径的 /embed 表示应用信息，现有嵌入 URL 即按此解析。

/embed/search — 关键词搜索，以精简卡片呈现。
/embed/chart — 商店排行榜：免费、付费或畅销，可为整个商店或单个分类（id 来自 categories 端点）。
/embed/category — 分类列表；点击图块即打开该分类的排行榜。
/embed/info — 完整应用信息，由下方 sections 参数决定内容。
/embed/similar — 商店为该应用推荐的相关应用。
/embed/news — 关于该应用的近期文章。

URL 参数

除商店（以及读取单个应用的模式中的标识符）外，其余均为可选。商店本身省略时回退为 play-store。

store — 从哪个商店读取。
<identifier> — 应用标识符，按其商店的方式命名：play-store 用 package_name；app-store 用 track_id 或 bundle_id；microsoft-store 用 product_id 或 package_family_name。在读取单个应用的屏幕中必填。
immediately — 到达即发起请求。对会跳转的地址有意义；由 API 的 embed 字段生成的链接已带有此参数。
query — 搜索关键词。仅 search 模式。
count — 列表模式返回的条数。
content_type — chart 与 category 读取的列表。
pricing_type — 榜单类型。 grossing 仅限 chart 模式，且 Microsoft Store 没有畅销榜。
id — 将排行榜限定到单个分类。省略则为整个商店。
sections — info 模式绘制什么、以什么顺序、用什么选项。
<mode>_items — 该模式结果卡片绘制的部分，如 chart_items=icon,name。按模式区分，一个 URL 即可分别定制它能到达的每个屏幕。省略则全部绘制。
<mode>_heading — 该模式列表上方的标题文字（“…的搜索结果”），如 similar_heading=0。 0 隐藏；其他文本则替换之。仅限 search · similar · chart · news。
lang / country — 读取哪个地区的商店，使用哪种语言。
ui_lang — 界面语言（标题、按钮、提示），独立于上方的商店语言。省略时跟随查询所用的 lang。 auto 跟随读者的浏览器语言。其他代码则固定为该语言；支持数十种语言，不支持的值回退为英文。
color — 用于链接、图表和按钮的强调色。 rgb() 与 hsl() 形式需百分号编码。
appearance — 未固定时跟随访问者的主题。
paging — 列表与评论区在第一页之后的继续方式。 scroll 在读者到达末尾时自动加载。 button 仅在按下时加载，适合固定高度的框架。 off 停留在第一页。省略时嵌入列表保持固定，评论按位置自动。
nav — 禁止嵌入跳转。不显示箭头，结果卡片也不会打开其他应用。不过一旦有历史被推入（例如宿主的 go），框架自身的返回箭头仍会出现。
scrollbar — 是否绘制滚动条以及何时淡出。淡出时机仅适用于页面滚动条。
scrollbar_size — 滚动条的宽度。
scrollbar_color — theme 跟随上面的强调色，改动 color 时滚动条一同变化；给定十六进制则固定为该值。
embed_token — 在嵌入中开启管理功能。见下文“管理嵌入”。会话可在任何屏幕开启并在导航后保持：管理功能出现在应用屏幕，品牌标识移除适用于所有屏幕。

sections 参数

以逗号分隔的板块名称列表，按给定顺序绘制。名称后可用括号携带该板块自身的配置。

括号内顺序无意义：单独的词是条目，key=value 是选项，@ 引出时间窗口。同一板块可出现多次。三个各有图表与时间范围的 analytics 区块是正常用法。

无法识别的名称或该商店没有的字段会被跳过而非报错。

head — 移除板块标题。
title — 替换标题。
id — 为该区块命名，供 scroll-to 使用。
count — 显示多少条。仅 similar 与 news，默认分别为 10 和 5。
viewer — 仅 preview。整体关闭放大查看：不再显示放大按钮，点按截图也不会打开查看器。
fullscreen — 仅 preview。放大查看仅以页面内浮层打开：不进入浏览器全屏，视频控件与 YouTube 的全屏按钮也会移除。允许（默认）时 iframe 本身须带有 allowfullscreen。上方代码已包含。
autoplay — 仅 preview。内嵌视频不会自动播放，而是等待点按播放按钮。
picker — 仅 analytics。隐藏时间范围控件，把图表固定在区块的时间窗口上。显示（默认）时，访客可在天数预设、周、月、年或自定义范围之间切换。
translate — 仅 reviews。隐藏 AI 翻译按钮。在嵌入中，翻译按钮只有在密钥持有 reply:translate 权限时才会出现。翻译会消耗嵌入密钥所有者的每日 AI 用量，是否向访客展示由宿主决定。
tabs — 仅 reviews。隐藏排序标签，从而固定顺序。
sort — 仅 reviews。列表打开时的排序。

值得注意

每个嵌入的内容下方都有一个小小的 app·atlas 标识并链接回这里。附加付费方案所有者的嵌入密钥即可移除品牌标识，前提是页面来源在密钥的允许来源之中（与管理功能相同的检查）。完全没有权限的密钥也能为此打开会话，因此移除品牌标识不需要向页面读者暴露任何数据或功能。
历史可回溯到开始观测该应用的时间。起点更早的窗口只绘制已有部分。
选项值内的逗号或括号必须进行两次百分号编码（逗号写作 %252C）：浏览器先解码一次查询，之后才解析 sections 语法。值内的 = 和 @ 无需编码；只有单独条目开头的 @ 会被解析为时间窗口。仪表板中的嵌入生成器会自动处理。
analytics 仅对处于观测中的应用绘制。没有快照的应用会显示占位提示。
官方指标（installs、sessions、proceeds、crashes 等）绘制在 analytics 内部，以卡片标记区分，且需要该密钥管理的应用附带管理令牌（embed_token）。没有令牌时不占任何空间。
totalInstalls 与 installs 是两个不同的数值，任一名称都不会绘制另一个。 totalInstalls 是累计安装量：Play 商店页面公开、由每日快照采集的数值；对有管理权限的调用者，商店自有的累计值也会绘制在同一张卡片上。 installs 是当日新增安装数，仅来自商店自有统计。 App Store 的商店页面不公开安装量，因此那里的 totalInstalls 不会绘制任何内容。

App Atlas · API 文档 · SDK 文档 · 服务条款 · 隐私政策 · Sign up

en · ko