# Page Evidence: What AI Actually Sees When It Reads Your Store


# Page Evidence: What AI Actually Sees When It Reads Your Store

## What this helps you with

Have you ever seen "optimized" in your dashboard, yet ChatGPT or Gemini still does not mention your product?
Usually it is because **the page AI sees is not the page you think it sees**.

Page Evidence makes our system **actually open your page**, collect what AI would read (JSON-LD, FAQ anchors, raw-md), re-validate it on the server, and then tell you:

- what AI actually received;
- what is missing or wrong;
- which fix matters most.

## Three steps to your first evidence

1. **Enable the theme extension** in Shopify admin (one-time).
2. **Open AI Readiness** and pick a product page, then click **Collect evidence**.
3. **Read the result**: after 10–30 seconds you get the Evidence card with status, JSON-LD, FAQ anchors and raw-md length.

> If it says "unmeasured", that is not a failure: we **do not guess**. If we did not capture it, we say so.

## Three terms to know

- **JSON-LD**: the "business card" of your product for AI.
- **FAQ anchor**: the question/answer mapping AI needs when citing you.
- **raw-md**: a clean text version of the page that is cheaper for AI to read.

## FAQ

**Q: Why does it say "unmeasured"?**
A: Password protection, a missing raw-md template, or a fetch timeout. Check the reason in Evidence details first.

**Q: Will it slow down my store?**
A: The extension only collects evidence; it does not block your storefront.

**Want the details?** Read the expert version: [[page-evidence.expert]]


---


# Page Evidence (Expert): Principles, Boundaries and Troubleshooting

## Chapter 1: Principles and boundaries

### 1.1 Why first-party evidence

AI crawlers do not execute JavaScript, and third-party probes are often blocked by WAF/CDN. So we do not guess or screenshot. Instead:

1. The theme App Embed runs in a **real browser**, reading rendered JSON-LD / FAQ anchors / raw-md;
2. It posts back through **Shopify App Proxy** with an HMAC signature (`shop + path_prefix + timestamp + signature`);
3. The Worker verifies the signature and **re-validates on the server** (browser-provided `passed/verdict` is never trusted);
4. Evidence is stored in `page_evidence` with `trust_level=APP_PROXY_HMAC`, hash and timestamp.

### 1.2 Template awareness

| Template | Required Schema types |
|---|---|
| product | `Product` + `Offer` |
| page/collection/article | page-type Schema (`FAQPage`, `CollectionPage`, `Article`, `Organization`) |

Non-product pages no longer fail with `JSONLD_PRODUCT_REQUIRED`; missing raw-md is reported as `RAWMD_FETCH_UNAVAILABLE` (unmeasured, never fake PASS).

### 1.3 Boundaries

- Evidence reflects the page **at collection time**, not history;
- WAF/password pages produce "unmeasured", not "passed";
- raw-md depends on the theme template; a theme change can break it;
- First-party evidence does not replace platform data (GSC/Shopify Analytics).

## Chapter 2: Troubleshooting and advanced usage

### 2.1 Common failure codes

| Code | Meaning | Fix |
|---|---|---|
| `APP_PROXY_SIGNATURE_INVALID` | HMAC mismatch | Check App Proxy secret / clock skew (±5 min) |
| `RAWMD_FETCH_UNAVAILABLE` | raw-md template missing or HTML fallback | Upload `templates/*.raw-md.liquid`, ensure `Accept: text/html` |
| `JSONLD_PRODUCT_REQUIRED` | Product/Offer missing | Add JSON-LD or check theme |
| `TENANT_UNRESOLVED` | Domain not bound to a tenant | Set `primary_domain` in tenant |

### 2.2 API and automation

- Ingest: `POST /api/v1/app-proxy/page-evidence` (HMAC)
- Read: Evidence page in console (tenant-scoped)
- Fields: `verdict / reasons / jsonld / faq_anchors / raw_md_json / hash / collected_at`

### 2.3 Best practices

- Re-collect after theme or product changes;
- Put evidence timestamps in client reports;
- Run 2–3 collections per URL for stability.

**Back to beginner version:** [[page-evidence.novice]]