> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.keyplace.ai/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# How keyplace works in a store: technical overview

keyplace is an embedded Shopify app with two extensions: a theme app extension with app blocks for the product page, and a web pixel. It never edits theme code and has no write access to products, orders or customers.

## In short
- The chat is an app block on product templates. There is no app embed.
- The browser gets a short-lived chat token through the App Proxy at `/apps/keyplace`, then streams answers from the keyplace server.
- A web pixel in Shopify's strict sandbox counts storefront events, only with the shopper's analytics consent.
- Settings live in app-data metafields. Approved Q&A lives in an app-owned metaobject.

## The parts
| Part | What it is | Where it runs |
|---|---|---|
| keyplace app | Embedded app (App Bridge) | Shopify admin |
| `keyplace-widget` | Theme app extension with two app blocks: "Ask about product" (`zapytaj`) and "keyplace Q&A" (`faq`) | Product templates of an Online Store 2.0 theme |
| `keyplace-pixel` | Web pixel extension, `runtime_context = "strict"` | Shopify's pixel sandbox (a web worker) |
| App Proxy | Prefix `apps`, subpath `keyplace`, so the storefront path is `/apps/keyplace/*` | Shopify signs and forwards each request to keyplace |

## Access scopes
The public app asks for these scopes and nothing else:

| Scope | Why |
|---|---|
| `read_products` | Product data for answers, and the product webhooks |
| `write_app_proxy` | The App Proxy at `/apps/keyplace` |
| `read_legal_policies` | Store policies, such as shipping and returns |
| `read_content` | Published pages and blog articles |
| `write_pixels`, `read_customer_events` | Registering the web pixel. Without them the app works and the pixel stays off. |

There is no theme scope, so keyplace can't read or change theme files. No ScriptTag. No access to customers or orders.

## How a question travels
1. The block renders in Liquid. Only a small loader and one stylesheet load with the page.
2. Hovering the widget prefetches the chat code. The first focus, tap or click attaches it (`keyplace-chat.js`).
3. The widget asks `/apps/keyplace/token` for a chat token. Shopify signs the request and keyplace checks the signature. The token is bound to the shop and the product and expires after 15 minutes.
4. Questions go as `POST` requests with that token to the keyplace server. Answers stream back as server-sent events and are added to the page as text nodes, never as HTML.
5. Widget views go to `/apps/keyplace/events` as beacons without a token. Failed turns send an error code to `/apps/keyplace/health`.

## What keyplace keeps in the store
- **App-data metafields** on the app installation, namespace `keyplace`: `ustawienia` (the app settings as JSON, which the block reads through `app.metafields`) and `panel_jezyk` (the app language). Only keyplace can write them.
- **An app-owned metaobject**, type `$app:product_faq`, named "keyplace Q&A". One entry per product, handle `kp-<product id>`, text fields only: `product_id`, `qa_ids`, `questions`, `answers`. Admin access is `merchant_read` (you can see it, not edit it). Storefront access is `public_read`, so the Q&A block reads it in Liquid. It holds only answers our team approved and the merchant turned on.
- **The web pixel's settings:** a pixel token and the counter address, set by the app.

## The web pixel
- It declares analytics consent only: `analytics = true`, `marketing = false`, `preferences = false`, `sale_of_data = "disabled"`. Nothing leaves the browser without analytics consent.
- It listens to `product_viewed`, `product_added_to_cart`, `checkout_started`, `payment_info_submitted`, `checkout_completed`, `alert_displayed` and `ui_extension_errored`.
- Each request carries counters only: the event name, Shopify's event id, an A/B letter and whether this device had a keyplace conversation in the last 7 days. `checkout_completed` adds the order total, the currency and a SHA-256 hash of the order id. Never the client id, the customer, an e-mail, an address, cart lines or URLs.

## Webhooks
API version `2026-10`.

| Topic | What keyplace does |
|---|---|
| `app/uninstalled` | Deletes this app's sessions for the store |
| `app/scopes_update` | Stores the new scopes and turns the pixel on or off to match |
| `products/update` | Guard: notes changes to prices, stock and empty fields |
| `products/delete` | Removes the product from the recommendation catalog at once |
| `customers/data_request`, `customers/redact` | keyplace keeps no data linked to a customer, so it only confirms |
| `shop/redact` | Deletes all of the store's data. Shopify sends it 48 hours after the uninstall. |

## Limits
- App blocks need an Online Store 2.0 theme. Vintage themes can't show the chat, and there is no app embed to fall back on.
- The blocks work on product templates only.
- Headless storefronts and Hydrogen don't render theme app extensions.
- In a market whose currency differs from the store currency, the block renders nothing.

## Common questions
### Does keyplace change my theme code?
No. The merchant adds the block in the theme editor, and Shopify saves it in the template JSON like any other app block.

### Does keyplace know who the shopper is?
No. Conversations are stored without a customer id, e-mail or login, and e-mails, phone numbers, card and account numbers are removed first.

### What happens on uninstall?
Shopify removes the app blocks from every theme and deletes the "keyplace Q&A" metaobject definition, then cleans up its entries. When `shop/redact` arrives, keyplace deletes the store's data.

## See also
- [Theme app blocks and Online Store 2.0](/en/article/theme-app-blocks-wd7e2v/)
- [Performance: script size and Lighthouse](/en/article/performance-dkhh5d/)
- [Shopper privacy](/en/article/shopper-privacy-14u0utz/)

Still stuck? Chat with us in keyplace: **Help > Chat with us**. We reply on working days. Never send us passwords, 2FA codes or shopper data.