What is a Shopify app embed and how do you turn it on?

You install a reviews app, a chat app or a structured data app, the app says it is ready and nothing shows up in the store. Often the reason has a name: the app is installed, but its app embed is switched off. An app embed is not the app and it is not your theme's code. It is the piece the app leaves ready to put its code on every page, and it only works once you turn it on. Its relative, the app block, is a different thing: a block you place inside a section, in a specific spot on the page.

How it works

App embeds are part of an app's theme app extensions, the mechanism Shopify gives merchants to add dynamic elements to their theme without touching the Liquid templates or the code.⁠^{[1]Shopify Dev Docs. About theme app extensions} There are two kinds of block:⁠^{[2]Shopify Dev Docs. Configure theme app extensions}

• App blocks. They are placed inside a section, so they need JSON templates and sections that accept blocks of type @app.
• App embeds. They are used by apps that have no visible part or that add floating or overlay elements. Shopify renders them and inserts them before the closing </head> and </body> tags, depending on the target the block declares: head, body or compliance_head.

Because they do not depend on sections or JSON templates, app embeds work on both vintage themes and Online Store 2.0.⁠^{[2]Shopify Dev Docs. Configure theme app extensions} Shopify's help describes them, for the merchant, as elements that float or overlay on the theme, or that add code to the store without the customer seeing it, such as a chat bubble or an analytics tool.⁠^{[3]Shopify Help Center. Extend your theme with apps}

The detail that generates the most support requests: after the app is installed, its app embeds are switched off. The merchant has to turn them on in the theme editor, in the theme settings, under "App embeds."⁠^{[2]Shopify Dev Docs. Configure theme app extensions} The app can help with a deep link to the editor that opens the block already activated, using the activateAppId parameter.⁠^{[2]Shopify Dev Docs. Configure theme app extensions} And Shopify recommends that developers explain how to turn each app embed on and off, with screenshots, video or text, and that they offer that deep link.⁠^{[4]Shopify Dev Docs. UX for theme app extensions}

Inside, each block is a Liquid file in the extension's blocks/ folder, alongside assets/ for the CSS and JavaScript, snippets/ and locales/. A block can be shown only if a condition is met (available_if), which reads a boolean metafield from the app. And there are limits: 30 blocks per extension, 10 MB in total and 100 KB of Liquid, adding up all the files.⁠^{[2]Shopify Dev Docs. Configure theme app extensions}

They exist to solve an old problem. Before, an app edited the theme's code or injected scripts into it, and when you uninstalled it those edits stayed behind: what Shopify calls ghost code, which can cause quality and performance problems.⁠^{[5]Shopify Dev Docs. Migrate to theme app extensions} With theme extensions, when an app is uninstalled its blocks are removed from the theme automatically and completely.⁠^{[4]Shopify Dev Docs. UX for theme app extensions}

In a store

A fictional example: an app that publishes structured data in the header of every product page. Its block, in the extension's blocks/ folder, declares that it goes in the head:

{% comment %} blocks/structured-data.liquid (fictional example) {% endcomment %}
<script type="application/ld+json">
  {% comment %} the app writes the product page's JSON-LD here {% endcomment %}
</script>

{% schema %}
{
  "name": "Structured data",
  "target": "head",
  "settings": []
}
{% endschema %}

Until the merchant turns it on, that <script> does not appear on any page. When they turn it on and save, Shopify places it before </head>, so the JSON-LD ends up in the header of the product page without anyone having edited theme.liquid.

It is the same split Clione uses on Shopify: it writes each product's signals to metafields and paints them with two app embeds, "Clione SEO," with the structured data graph in the head, and "Clione FAQ," with the question accordion in the body, which are turned on from the Clione panel with one click.

How to check it

1. Open the theme editor for the published theme and click the "App embeds" icon in the sidebar. Find the app and see whether the toggle is on. If you change it, save.⁠^{[3]Shopify Help Center. Extend your theme with apps}
2. If you sell in several markets, check which market was selected: with none chosen, the change goes to the store's default configuration.⁠^{[3]Shopify Help Center. Extend your theme with apps}
3. Open a product page and its source code (Ctrl+U in Chrome) and look for the app's code before </head> or </body>, depending on where the app says it works.⁠^{[2]Shopify Dev Docs. Configure theme app extensions}
4. If the block publishes structured data, run the URL through the Rich Results Test or a schema validator to see that it reads without errors.
5. Every time you change themes, repeat steps 1 and 3. The new theme does not inherit the apps activated on the previous one.⁠^{[3]Shopify Help Center. Extend your theme with apps}

Related concept: BigCommerce widget

On BigCommerce, the closest thing is the BigCommerce widget. A widget is a unit of content in HTML, CSS and JavaScript, on a Handlebars template, that is placed with the Widgets API in a specific region of a Stencil theme and is rendered as part of the store's HTML.⁠^{[6]BigCommerce Dev Center. Widgets API} The practical difference is the location. An app embed goes at the end of the page's head or body, and the merchant turns it on with a toggle. A widget goes to the region and the page its placement says, which is created through the API.⁠^{[6]BigCommerce Dev Center. Widgets API}

The guide from metafield to published page follows a piece of Shopify data all the way to the product page's HTML, and the publishing by platform reading path puts the rest of the terms in order.