Install the Runtime script

Add the Proa Runtime to a Shopify store: through the Proa app or as a manual tag, how to verify it, and what happens next.

Before you start

You need a Proa account with the website created in the dashboard, and access to the store's Shopify admin. If the Runtime section shows not initialized, click Initialize Runtime first: that creates the site key and the embed snippet. Initializing publishes nothing and changes nothing on the store.

There are two ways to install, and both are fully supported:

  • With the Proa Shopify app — no code touches the theme. The easiest path on Shopify.
  • With the manual tag — you paste one script tag into the theme yourself. The only path on other platforms, and a deliberate choice on Shopify when you want the tag under your own control.

Installing with the Shopify app

In Site settings → Install with the Shopify app, enter the store domain and click Connect Shopify store. Then turn the Proa Runtime embed on in the theme editor with Activate in theme (Shopify admin → Online Store → Themes → Customize → App embeds) and save.

Connecting the store also does two things that used to be manual steps:

  • The store's myshopify.com domain is added to the site's Authorized hosts by itself. On a site that has never been published it takes effect right away; on a published site, on the next publish, like any host change.
  • The checkout pixel is provisioned on the store. It is what lets an experiment see the checkout steps in the funnel and measure coverage among paid orders; Site settings shows whether it is in place, with a Provision pixel button when it is not.

The section then reports what it actually sees on your storefront over the last seven days: the embed working, the store still waiting for its first visit, or two Proa tags on the same page — a leftover manual snippet next to the embed. Keep one; until you do, only one copy runs.

Installing with the manual tag

1. Authorize your hostnames

In the Proa dashboard, open Site settings → Authorized hosts and add every hostname the storefront answers on.

This list is a containment boundary, not a filter: the Runtime refuses to run on any hostname you have not authorized. Two details matter:

  • *.example.com matches subdomains but not the apex. If the store answers on example.com, add it explicitly.
  • Host changes only reach the storefront on the next publish. Until you publish, the storefront runs the previous list.

2. Place the snippet

Copy the snippet from Site settings → Installation. It looks like this:

<script src="https://runtime.tryproa.com/v1/s/<siteKey>.js"
  data-template-resource="{{ template.name | escape }}"
  data-assigned-template-suffix="{% if template.name == 'product' %}{{ product.template_suffix | escape }}{% elsif template.name == 'collection' %}{{ collection.template_suffix | escape }}{% elsif template.name == 'page' %}{{ page.template_suffix | escape }}{% elsif template.name == 'blog' %}{{ blog.template_suffix | escape }}{% elsif template.name == 'article' %}{{ article.template_suffix | escape }}{% endif %}"
  data-rendered-template-suffix="{{ template.suffix | escape }}"></script>

Paste it into the theme's head, as high as possible: Shopify admin → Online Store → Themes → Edit code → layout/theme.liquid, immediately after the opening <head> tag, before other app tags that manipulate the page.

The three data-* attributes are Shopify Liquid — they tell Proa which theme template the page uses, which template tests need. On a non-Shopify storefront, copy from the Other platforms tab of the Installation card instead: it gives the bare <script src="…"></script>, and everything except template tests works identically.

The site key is delivery routing, not a secret; it appears in every visitor's HTML by design. Whether the tag carries async is a real decision with a real tradeoff: read Blocking or async before choosing. On a store new to Proa, starting async is the safe default.

Turn on measurement, then publish

Event collection is off by default and is an explicit choice, in Site settings → Telemetry. Without it the Runtime still delivers content; it just reports nothing. The setting is baked into the published snapshot, so it takes effect on the next publish.

Then publish: Runtime → the pending banner → Publish. New publishes reach visitors globally in under a minute.

Verify the install

Run all of these; any one failing means "not installed yet", not "probably fine".

  1. The script is served. curl https://runtime.tryproa.com/v1/s/<siteKey>.js returns JavaScript. This checks Proa's side only; it says nothing about whether the tag reached the theme.
  2. A snapshot is live. Runtime → Activity shows a published snapshot and no pending banner.
  3. The tag is on the storefront. On the app path, the Install with the Shopify app section reports the embed as seen on real traffic. On the manual path, load the store in a browser and confirm the script tag is present in the page source and loads without errors in the network tab.
  4. Measurement is flowing. If you enabled telemetry, numbers appear in the dashboard after real traffic. They are aggregated periodically, not live: no rows minutes after installing is normal. See Troubleshooting before assuming something is wrong.

What visitors see

Nothing that identifies Proa: no badge, no banner, no visible artifact. Preview sessions are the only state that shows a QA badge, and they exist only in your own browser tab. To measure revenue per variant, continue to Revenue attribution.