Embed Reference

How to show app data in an iframe, and the parameters it takes.

Overview

An embed is a page you put in an iframe. It renders the same screens the dashboard does (app info, search, top charts, categories, similar apps and news) and it needs no key: everything below is decided by the URL.

Modes that read one app (info, similar, news) identify it the same way the API does: pick a store and give at least one identifier for that store. Search takes a keyword; charts and categories need nothing at all.

Modes

The path decides what the frame draws. A bare /embed means app info, which existing embed URLs resolve to.

/embed/search — Keyword search, as lightweight cards.
/embed/chart — The store's top chart: free, paid or grossing, whole store or one category (id from the categories endpoint).
/embed/category — The category list; each tile opens that category's chart.
/embed/info — The full app listing, shaped by the sections parameter below.
/embed/similar — Apps the store recommends alongside the given one.
/embed/news — Recent articles about the app.

URL parameters

Everything except the store is optional, and even the store falls back to play-store when omitted. On the modes that read one app, the app's identifier is required too.

store — Which store to read.
<identifier> — The app, named the way its store does: play-store takes package_name; app-store track_id or bundle_id; microsoft-store product_id or package_family_name. Required on the screens that read one app.
immediately — Fetch on arrival. Matters for addresses that navigate; the links built from the API's embed field carry it already.
query — The search keyword. Search mode only.
count — How many results the list modes return.
content_type — Which listing chart and category read.
pricing_type — Which chart to show. grossing is chart mode only, and the Microsoft Store has no grossing chart.
id — Narrows the chart to one category. Omit for the whole store.
sections — What info mode draws, in what order, with what options.
<mode>_items — Which parts that mode's result cards draw, e.g. chart_items=icon,name. Scoped per mode, so one URL can style every screen it navigates to. Omit to draw everything.
<mode>_heading — The line above that mode's list ("Results for …"), e.g. similar_heading=0. 0 hides it; any other text replaces it. search · similar · chart · news.
lang / country — Which storefront to read, and in which language.
ui_lang — The interface language (headings, buttons, notices), apart from the storefront language above. Omitted, it follows the lookup's own lang. auto follows the reader's browser. Any other code pins the interface to that language; dozens are covered, and unsupported ones fall back to English.
color — Accent used for links, charts and buttons. rgb() and hsl() forms are percent-encoded.
appearance — Follows the viewer's theme unless pinned.
paging — How lists and the reviews section continue past the first window. scroll loads more as the reader reaches the end. button waits for a press, which suits a fixed-height frame. off stays at the first window. Omitted, an embed's lists stay fixed and reviews decide by position.
nav — Stops the embed navigating anywhere. No chevrons, and result cards do not open another app. The frame's own back chevron still appears once something pushed history, a host go for instance.
scrollbar — Whether a scrollbar is drawn and when it fades. Fade timing applies to the page bar only.
scrollbar_size — How wide the bar is.
scrollbar_color — theme follows the accent above, so changing color moves the bar with it. A hex pins it instead.
embed_token — Unlocks management inside the embed. See Management embeds below. The session opens on any screen and survives navigation: management features appear on the app screen, branding removal applies everywhere.

The sections parameter

A comma-separated list of section names, drawn in the order given. A name may carry its own configuration in parentheses.

Inside the parentheses, order carries no meaning: a bare word is an item, key=value is an option, and @ introduces a window. A section may appear more than once. Three analytics blocks, each with its own charts and its own window, is a normal thing to ask for.

A name the embed does not know, or a field the store does not carry, is skipped rather than raised.

head — Removes the section's heading.
title — Replaces the heading.
id — Names this block, for scroll-to.
count — How many entries to show. Similar and news only. The defaults are 10 and 5.
viewer — Preview only. Removes the expanded view altogether: no expand buttons, and screenshots stop opening the viewer.
fullscreen — Preview only. Keeps the expanded view an in-page overlay: no browser fullscreen, and the video controls and YouTube lose their fullscreen buttons. When allowed (the default), the iframe itself must carry allowfullscreen. The snippet above includes it.
autoplay — Preview only. Inline videos wait behind a play overlay instead of starting by themselves.
picker — Analytics only. Hides the period picker, pinning the charts to the block's window. While it shows (the default), a visitor may switch between day presets, a week, a month, a year or a custom range.
translate — Reviews only. Hides the AI translate buttons. Inside an embed they appear only with a key holding reply:translate. Translation spends the embed key owner's daily AI allowance, so the host decides whether visitors see it.
tabs — Reviews only. Hides the sort tabs, pinning the order.
sort — Reviews only. Which order the list opens on.

Worth knowing

Every embed carries a small app·atlas logo under the content, linking back here. Attaching an embed key whose owner is on a paid plan removes the branding, provided the page's origin is on the key's allowed origins (the same check management goes through). A key with no permissions at all opens a session for that alone, so removing it never forces you to expose data or actions to the page's readers.
History reaches as far back as the app has been watched. A window starting before that draws what exists.
A comma or parenthesis inside an option value must be percent-encoded twice (a comma becomes %252C): the browser decodes the query once before the sections grammar is read. = and @ inside a value are safe; @ starting a bare item opens a window instead. The embed builder in the dashboard does this for you.
Analytics only draws for an app that is being watched. An app with no snapshots shows a placeholder instead.
The official metrics (installs, sessions, proceeds, crashes …) draw inside analytics, flagged on the card, and need a management token (embed_token) for an app the key manages. Without one they take no space at all.
totalInstalls and installs are two different figures, and neither name draws the other. totalInstalls is the cumulative count: the figure the Play listing publishes, collected in the daily snapshots, and the store's own running total on the same card for a managing caller. installs is the day's new installs, and comes from the store's own analytics only. The App Store publishes no install count on its listing, so there totalInstalls draws nothing.

App Atlas · API Reference · SDK Reference · Terms of Service · Privacy Policy · Sign up

ko · zh