---
title: "International SEO and Structured Data"
canonical_url: "https://ainode.run/docs/seo"
type: "doc"
locale: "en"
description: "Configure canonical URLs, hreflang, JSON-LD, robots policy, and the active-theme sitemap."
---

# International SEO and Structured Data
> Configure canonical URLs, hreflang, JSON-LD, robots policy, and the active-theme sitemap.

APay renders SEO metadata on the server for the built storefront languages: English (`en`), Simplified Chinese (`zh`), Hong Kong Traditional Chinese (`zh-HK`), and Russian (`ru`). The active deployment can build a subset with `APAY_LOCALES`.

## Trusted site URL

Single-domain deployments must set **Settings → Site URL** (`site_url`) to an absolute HTTP or HTTPS origin such as `https://store.example.com`. Paths, query strings, fragments, credentials, and non-HTTP schemes are invalid. APay never guesses a public origin from an arbitrary request Host.

When `APAY_DOMAIN_LOCALES` is enabled, the current Host must match that build-time allowlist. `APAY_PUBLIC_PROTOCOL=https` is recommended behind a reverse proxy. See [Domain Locale Binding](/docs/domain-locales) for the proxy and cache requirements.

If no trusted origin is available, storefront HTML degrades to `noindex,follow`, omits canonical and JSON-LD, and `/sitemap.xml` returns HTTP 503. `robots.txt` remains available but omits its Sitemap line.

## Language URLs

The default language uses an unprefixed path; other built languages use a locale prefix. For an English-default site, one product is represented as:

- English: `/products/example`
- Simplified Chinese: `/zh/products/example`
- Hong Kong Traditional Chinese: `/zh-HK/products/example`
- Russian: `/ru/products/example`

Each indexable page emits one canonical URL, `hreflang` links for reachable built languages, an `x-default` link to the unprefixed default-language URL, `og:url`, and the correct HTML language. Query strings and fragments do not create alternate canonical pages.

When `APAY_LOCALE_DOMAINS` is enabled, language ownership defines the canonical URLs: Simplified Chinese can use `https://myshopark.com/products/example`, English `https://myshopark.com/products/example`, and Russian `https://myshopark.com/ru/products/example`. Canonical, `og:url`, JSON-LD page addresses, and reciprocal `hreflang` use those owner URLs. Both domains use the build default for `x-default`. Each domain's sitemap contains only its own `` URLs with cross-domain alternates. See [Domain Locale Binding](/docs/domain-locales) for configuration, redirect exclusions, and rollback.

## Structured data

All structured data is emitted as one SSR `` with a Schema.org `@graph`:

| Page | Nodes |
| --- | --- |
| Public storefront | `Organization`, `WebSite` |
| Active product detail | `Product`, `Offer`, `BreadcrumbList` |
| Active blog detail | `BlogPosting`, `BreadcrumbList` |
| Qingpu downloads | `SoftwareApplication`, `BreadcrumbList` |
| Shoply app detail | `SoftwareApplication`, `BreadcrumbList` |
| Shoply theme detail | `Product`, `Offer` when backed by a product, `BreadcrumbList` |

Entity pages submit the localized data they already fetched during SSR. Product offers use the same `useLocaleCurrency()` amount and ISO currency as the visible page and checkout. APay does not fabricate ratings, reviews, inventory, authors, SKU/GTIN values, search actions, or social profiles. Missing optional facts are omitted.

Inactive products and posts return or remain 404 and are excluded. NFT mock product, creator, drop, stock, and live-status facts are intentionally `noindex` and never emitted as Product schema.

## Route policy and sitemap

`app/core/seo.routes.json` and each theme's `seo.routes.json` are the index policy source. Every real page entry must be classified as public, private, or redirect. The SEO guard fails when a page is unclassified, classified twice, or a manifest path does not exist.

Shoply's `/about` is a redirect to the public `/page/about` page. Legacy solution URLs are also redirects; they must not appear as sitemap destinations. Deleted `/page/case` is excluded, while `/cases/:slug` is classified as a public detail route.

Theme-specific dynamic sources are declared in `theme.host.json` as
`seoSources: { "source-name": "server/seo.ts" }`. The module exports
`getSitemapEntries(source)` and returns `{ path, lastmod? }` entries. The build
registry includes only selected storefront providers; core Sitemap code does
not import individual themes. A missing or failing provider produces HTTP 503
instead of silently omitting its routes.

The sitemap contains only:

- the current active theme plus non-suppressed core public routes;
- the current trusted origin;
- built languages and their alternates;
- active products and active blog posts;
- real Shoply marketplace seed routes.

Documentation landing pages are included. Individual Nuxt Content document paths remain discoverable through SSR links and canonical metadata but are not proactively enumerated by the current sitemap generator.

It never unions routes from every bundled theme. Generation fails instead of returning partial XML when the database query fails or the result exceeds 50,000 URLs. Responses cache for five minutes with stale revalidation; CDN keys must include Host.

Private `/admin`, `/api`, `/auth`, `/user`, `/payment`, `/callback`, and `/app` paths receive `X-Robots-Tag: noindex, nofollow`. Unknown or unclassified storefront paths use `noindex,follow` so crawlers can observe the directive. `robots.txt` blocks API routes but deliberately allows private HTML to be fetched so crawlers can read its noindex response header.

## Generative Engine Optimization (GEO)

APay includes a host-level GEO layer alongside traditional SEO so AI search engines and retrieval agents (`OAI-SearchBot`, `ChatGPT-User`, `PerplexityBot`, `Claude-SearchBot`, `ClaudeBot`, `Google-Extended`, `Applebot-Extended`, etc.) can index and cite public facts without scraping hydration payloads:

1. **`/llms.txt`, `/llms-full.txt`, and `/rss.xml`**: `/llms.txt` renders a structured Markdown directory for the active theme and trusted origin: site overview, public core pages, active products with base currency pricing, active blog posts matching domain locale ownership, documentation pages, and theme-provided dynamic entries (`ThemeSitemapEntry` optionally supplies `title`, `description`, `section`, and `markdown`).`/llms-full.txt` appends the cleaned full-text Markdown corpus for active products, documentation (converted from Nuxt Content Minimark AST via `minimarkToMarkdown` with Shiki styles stripped), blog articles, and theme catalog entries.`/rss.xml` outputs an RSS 2.0 XML feed for active blog articles. On single-domain multi-locale sites, `/llms.txt`, `/llms-full.txt`, and `/rss.xml` accept `?locale=` (e.g. `?locale=zh`) to return the localized corpus.All endpoints enforce `classifySeoRoute(...) === 'public'` and return HTTP 503 if no trusted origin is configured.
2. **Markdown Mirrors and Content Negotiation**: Public blog, product, documentation, and theme-declared dynamic detail routes support explicit `.md` suffixes (`/blog/:slug.md`, `/products/:slug.md`, `/docs/**.md`, and any `/:group/:slug.md` backed by a theme `seoSources` declaration, plus localized prefixes) as well as `Accept: text/markdown` content negotiation.Responses emit `Content-Type: text/markdown; charset=utf-8`, `Vary: Accept`, canonical and `llms-txt` `Link` headers, and YAML frontmatter (`title`, `canonical_url`, `type`, `locale`, `price`/`currency`, `published_at`, `updated_at`) followed by sanitized Markdown.Indexable SSR pages emit ``, `` (when blog routes are public), and `` on Markdown-mirror-capable detail pages.If a theme suppresses or marks a route as `private` (for example, `nft` suppressing `/products/**`), the Markdown mirror is refused and returns 404.
3. **AI Crawler Directives, Admin Controls & JSON-LD**: `/robots.txt` declares explicit rules for `AI_SEARCH_BOTS` (controlled by `geo_ai_bots_policy` under **Admin → Settings → SEO**: `allow` by default, or `disallow`) and advertises `LLMs-Txt: /llms.txt`.**Admin → Settings → SEO** also manages search engine webmaster verification tokens (`google_site_verification`, `bing_site_verification`, `baidu_site_verification`, `yandex_site_verification`) which are automatically injected into public indexable `` tags.`useJsonLd.ts` provides `useFaqPageJsonLd` (`FAQPage`) and `useSoftwareApplicationJsonLd` (`SoftwareApplication`) in addition to `useProductJsonLd` and `useBlogPostingJsonLd`, strictly omitting any fabricated ratings or review counts.**GEO & SEO Growth Cockpit & IndexNow**: **AI Bot Telemetry (`GET /api/admin/settings/seo-telemetry`)**: Filters `access_logs` at the SQL query layer for `AI_SEARCH_BOTS` (`OAI-SearchBot`, `GPTBot`, `PerplexityBot`, `ClaudeBot`, `Google-Extended`, etc.) and requests to `/llms.txt`, `/llms-full.txt`, and `*.md` mirrors without pre-truncating general traffic, displaying 30-day crawl leaderboards and top AI-crawled pages in **Admin → Settings → SEO**.**IndexNow Real-Time Push (`POST /api/admin/settings/seo-indexnow`)**: Configure `indexnow_key` and `indexnow_auto_push` in **Admin → Settings → SEO**. APay automatically hosts `/.txt` at the root and asynchronously pushes updated canonical HTML and `.md` mirror URLs when products or blog posts are published or updated.**Single-Page GEO/SEO Inspector**: Product (`/admin/products/[id]`) and Post (`/admin/posts/[id]`) editors include a sidebar readiness score (0–100, Grade `A`–`D`), `.md` mirror & JSON-LD live preview modal, and one-click IndexNow push.**Proactive Audit Radar & One-Click Auto-Optimizer (`GET /api/admin/settings/seo-audit`, `POST /api/admin/settings/seo-autofill`)**: Automatically scans all active products and blog posts, surfaces actionable diagnostics (missing citations, AI-crawled posts without product links, uncrawled orphan pages), and supports one-click smart extraction of `tldr`, `keySpecs`, `faqs`, and bidirectional product ↔ blog `relatedLinks` (both inside individual editors and in full-site batch mode).**Citation-Ready Structured Content (`metaData`)**: Products and posts support `tldr` (concise takeaway), `keySpecs` (label-value pairs rendered as Markdown tables in `.md` mirrors / `/llms-full.txt` and `additionalProperty` `PropertyValue` nodes in `Product` JSON-LD), `faqs` (question-answer pairs automatically injected as `FAQPage` JSON-LD and appended to `.md` mirrors), and `relatedLinks` (bidirectional internal links between products, tutorials, and docs), with per-locale overrides under `metaData.translations[locale]`.**GeoIP Smart Checkout Routing & Cross-Conversion**: `/api/payments/info` uses offline GeoIP (`resolveRequestGeo`) to prioritize regionally preferred payment gateways (`sortPaymentMethodsByGeo`) and surfaces a `recommendedByGeo` indicator in `PaymentWorkspace.vue` without altering canonical URLs or `currencySnapshot` accounting.The Growth Cockpit reuses the shared visitor report service (`loadVisitorReport` + `buildVisitorGeoConversions`) to cross-analyze visitor GeoIP country with `ai` and `search` acquisition channels (`geoConversions`), computing deduplicated visitor conversion rates (`paidVisitors / totalVisitors`, `aiPaidVisitors / aiVisitors`, `searchPaidVisitors / searchVisitors`) and per-currency revenue/AOV buckets (`revenueByCurrency`, `aovByCurrency`) without summing across different accounting currencies.**MCP Server Discovery in `/llms.txt`**: `/llms.txt` includes an `## AI Agent & MCP Protocol` section advertising `/api/mcp` (JSON-RPC 2.0 Streamable HTTP), `/.well-known/oauth-protected-resource`, and `/.well-known/oauth-authorization-server`.

## Site icon

Upload the site icon under **Admin → Settings → General**, then click **Save changes**. Uploading only fills in the favicon URL; it does not save the setting. The shared head plugin reads `site_favicon` for all themes and admin pages, including SSR, and updates the current browser tab after settings are saved. Refresh other open tabs to load the new setting. An empty value uses `/favicon.svg`.

Uploaded files receive a unique URL on each upload. Local `/uploads/*.ico` responses use `Content-Type: image/vnd.microsoft.icon` and retain `X-Content-Type-Options: nosniff`.

## Verification

Run the focused guards before building:

```bash
npm run check:seo
node --experimental-strip-types scripts/check-domain-locales.mjs
node --experimental-strip-types scripts/check-locale-domains.mjs
```

After deployment, inspect SSR source—not only the hydrated DOM—for the canonical, alternates, robots meta, and single JSON-LD graph. Probe `/robots.txt`, `/sitemap.xml`, every configured Host, one URL per language, an active and inactive product, an active blog post, a 404, and a private page. Validate sample entity pages with a structured-data validator without treating rich-result eligibility as a ranking guarantee.

Rollback requires deploying the previous artifact or reverting the SEO route manifests and code. No database migration, payment rollback, or production data rewrite is involved.
