Use this guide if you want server-side rendering (SSR) of Schema App’s structured data (JSON-LD) for crawlers and bots, you use Akamai as your CDN provider, and your account has Edge Workers available. The instructions below explain how to install the Schema App CDN injection Edge Worker into your existing Akamai property. The worker injects JSON-LD markup from Schema App’s CDN into the <head> of HTML pages when the request is from a bot or crawler. Normal user traffic is unchanged.
Note: Currently, Akamai Server Side Rendering is only available to Enterprise (Highlighter) clients.
Prerequisites
- An Akamai account with Property Manager and Edge Workers enabled.
- Your existing property (the one that serves your website).
- Your Schema App account ID (e.g.
ExampleAccount,ExampleAccount/Test). Get this from the Schema App home page if you don’t have it.
Note: Be sure to not include the http://schemaapp.com/db/- The Edge Worker bundle (download from Schema App’s CDN; see Deploy the Edge Worker below).
Overview
You will:
- Deploy the Edge Worker bundle and note its ID.
- Add the user-defined variables to your property.
- Add a Schema App CDN rule that sends the Edge Worker's markup requests to Schema App's CDN.
- Add a Schema App Inject rule that runs the Edge Worker on page requests from bots.
- Activate to staging, test, then activate to production.
Rule order matters: The Schema App CDN rule must be evaluated before the Schema App Inject rule (e.g. place it higher in the default rule tree).
Step-by-step setup
1. Deploy the Edge Worker
Download the bundle from Schema App’s CDN:
- URL:https://cdn.schemaapp.com/javascript/schemaapp-edgeworker.tgz
Download this file (e.g. with your browser orcurl -O https://cdn.schemaapp.com/javascript/schemaapp-edgeworker.tgz). The bundle containsbundle.jsonandmain.jsat the root, as required by Akamai.
- URL:https://cdn.schemaapp.com/javascript/schemaapp-edgeworker.tgz
Upload the bundle in Akamai:
- Control Center: Edge Workers → Create / Manage → upload the downloaded
.tgzand create a new Edge Worker (or new version of an existing one). - CLI: Use the Akamai Edge Workers CLI to upload the bundle.
- Control Center: Edge Workers → Create / Manage → upload the downloaded
Note the Edge Worker ID (e.g.
105498). You will use it when adding the Edge Worker behavior.
2. Add user-defined variables
In Property Manager, open your property and add user-defined variables (e.g. under the Variables section or in the default rule’s configuration). Use one of the two options below.
Option A: Single hostname / single Schema App account
Add these two variables:
| Variable name | Value | Notes |
|---|---|---|
PMUSER_SCHEMAAPP_ACCOUNT_ID | Your Schema App account ID (e.g. ExampleAccount) | Exact name — no leading or trailing spaces. |
PMUSER_SCHEMAAPP_CDN_BASE_URL | https://<your-property-hostname> | Same scheme + host as the request (e.g. https://www.yourdomain.com). No path, no trailing slash.Do not set this to https://data.schemaapp.com — the worker will ignore it and skip CDN subrequests. |
Option B: Multiple hostnames or Schema App accounts
Use this when one Akamai property serves more than one hostname, or more than one Schema App project on the same hostname (split by URL path). Requires Edge Worker bundle version 1.5 or later; re-download the bundle (step 1) if yours is older.
Add this one variable:
| Variable name | Value | Notes |
|---|---|---|
PMUSER_SCHEMAAPP_PROJECTS | A JSON array of projects (see example below) | Exact name — no leading or trailing spaces. |
Example:
[
{"baseUrl":"https://en.example.com","accountId":"ExampleEN"},
{"baseUrl":"https://fr.example.com","accountId":"ExampleFR"},
{"baseUrl":"https://www.example.com","pathPrefix":"/en","accountId":"ExampleWebEN"},
{"baseUrl":"https://www.example.com","pathPrefix":"/fr","accountId":"ExampleWebFR"}
]Each entry has these fields:
| Field | Required | Meaning |
|---|---|---|
baseUrl | Yes | Scheme + host (e.g. https://www.yourdomain.com). Must be a hostname on this property, not data.schemaapp.com. |
accountId | Yes | Schema App account ID for that entry (same format as PMUSER_SCHEMAAPP_ACCOUNT_ID). |
pathPrefix | No | Match this path and anything under it (/en matches /en and /en/about). Omit to match any path on that host. |
Matching: hostname first (case-insensitive and exact, so list both www and the bare domain if both are used), then the longest matching pathPrefix. A request that matches no entry is served unchanged, with no markup.
If PMUSER_SCHEMAAPP_PROJECTS is set, the Option A variables are ignored. A one-entry list is the same as Option A.
To confirm each hostname and path maps to the right account, see How-To: Troubleshoot Akamai Integration.
Optional: Debug mode
Works with either option. Add this variable only while troubleshooting:
| Variable name | Value | Notes |
|---|---|---|
PMUSER_SCHEMAAPP_DEBUG | true | Turns on diagnostic output. Remove when done. See How-To: Troubleshoot Akamai Integration. |
Important:
- Variable names must match exactly (no extra spaces before or after).
- Each CDN base (
PMUSER_SCHEMAAPP_CDN_BASE_URL, or eachbaseUrlinPMUSER_SCHEMAAPP_PROJECTS) must be a hostname on this property. The Edge Worker sends its markup requests to that hostname, and your Schema App CDN rule forwards them to Schema App's CDN.
Note: Be sure to not include the http://schemaapp.com/db/ part of the Account ID. For example, http://schemaapp.com/db/SchemaApp must be shortened to just SchemaApp.3. Add the Schema App CDN rule (CDN Proxy)
This rule sends the worker’s CDN subrequests to Schema App’s CDN. It matches matches a header X-SchemaApp-CDN-Request and sends those requests to Schema App's CDN (data.schemaapp.com) instead of your website's server.
Add a Rule using the Blank Rule Template, and name it Schema App CDN. Make sure it is a direct child of the Default Rule, not nested under another rule.
Criteria: Request Header, header name
X-SchemaApp-CDN-Request, exists (or is one oftrue).Behavior: Origin Server. Add an Origin Server behavior with these settings:
- Origin Type:
Your Origin - Origin Server Hostname:
data.schemaapp.com - Forward Host Header: Origin Hostname. Required. If your website's hostname is forwarded instead, the CDN request can fail with a 503 error.
- Origin Type:
Behavior: Caching. Add a Caching behavior and set Caching Option to No Store. Schema App's CDN already manages caching of your markup. If Akamai also cached these responses, bots could keep receiving old markup after you publish changes in Schema App.
Do not change the path. Do not add path rewrites or an origin base path to this rule. Schema App's CDN expects the path exactly as the Edge Worker sends it.
(Optional) Add a Content Provider Code behavior if you want this traffic reported separately.
Note: This section is the most likely to require troubleshooting. Your CSM may request a copy of the integration code to share with our Engineering team to review.
4. Add the Schema App Inject rule (Edge Worker)
Create a new rule (e.g. name: Schema App Inject).
Select 'Match All'. Only requests that match all the criteria will invoke the worker.
Criteria: Match → User-Agent → is one of (or Matches regex), with a list of bot identifiers.
- For example:
*SchemaBot*,*Googlebot*,*Bingbot*,*Slurp*. Make sure to add wildcards around each botname so it will match against the useragent string. Schema App maintains a recommend list of Bots here. Add or remove bots per your requirements, but ensure that
*SchemaBot*is included in this list to allow Schema App's crawler to evaluate the markup.
- For example:
Criteria: Match → Request Method → is → GET. Only requests to pages that should display Schema Markup will invoke the worker.
Criteria: Request Header →
X-Subrequest→ does not exist. This bypasses the worker on subrequests, so that the Edge Worker is not invoked. The worker itself adds this header only to its own origin fetch. This prevents the origin subrequest from re-triggering the worker.Behaviors:
- Edge Worker: Enable, and select the Edge Worker you uploaded (by the ID you noted earlier).
- Set Continue on error as desired (typically false).
5. Save, activate, and test
Save the property version.
Activate to Staging. In Property Manager, use Activate → Activate to Staging (or equivalent) for this version.
Test on staging:
- Send a request with a bot User-Agent to a page that returns HTML, e.g.:
curl -s -A "Mozilla/5.0 (compatible; SchemaBot/1.2; +https://www.schemaapp.com/bot/)" \ "https://<your-staging-hostname>/<path>" -o response.html - Open
response.htmland confirm you see<script type="application/ld+json" data-source="SchemaApp-Akamai:...">in the<head>(if the Schema App CDN has data for that URL). - In Akamai logs or Test Center, confirm the worker runs and that subrequests to the CDN return 200 (not 503).
- If markup is missing or subrequests fail, see How-To: Troubleshoot Akamai Integration.
- Send a request with a bot User-Agent to a page that returns HTML, e.g.:
Activate to Production when staging looks correct.
Common setup mistakes
Check these before contacting support:
- Rule is incorrectly nested. Schema App CDN and Schema App Inject must both be direct children of the Default Rule. Drag-and-drop in the editor can accidentally place a rule as a childen under the rule above it or below it.
- Testing with the wrong User-Agent. When testing, use a bot user-agent header that matches a user-agent added in the Schema App Inject rule.
- Security rules block the test. Firewall, WAF, or bot-management rules can block SchemaBot or your test IP before the Edge Worker runs.
- Conflicting rules. Rules that rewrite paths or remove headers may conflict with the rules added for Schema App. Ensure that the order or nesting of other rules does not cause any conflicting behavior.
For detailed troubleshooting steps, using the debug mode, status messages, and fixes for common issues, see How-To: Troubleshoot Akamai Integration.
Quick reference
| What | Value or action |
|---|---|
| Rule placement | Schema App CDN, then Schema App Inject |
| Schema App CDN rule criteria | Request header X-SchemaApp-CDN-Request exists |
| Schema App CDN origin hostname | data.schemaapp.com |
| Schema App CDN Forward Host Header | Origin Hostname (required) |
| Schema App CDN caching | No Store |
| Schema App Inject rule criteria (Match All) | User-Agent is one of your bot list (include *SchemaBot*); Request Method is GET; request header X-Subrequest does not exist |
PMUSER_SCHEMAAPP_CDN_BASE_URL | Single project: https://<your-property-hostname> (same as the request hostname; not data.schemaapp.com) |
PMUSER_SCHEMAAPP_ACCOUNT_ID | Single project: your Schema App account ID; variable name with no trailing space |
PMUSER_SCHEMAAPP_PROJECTS | Multiple hostnames or path-split accounts: JSON array of {baseUrl, accountId, pathPrefix}. Replaces the two variables above when set. |
PMUSER_SCHEMAAPP_DEBUG | (Optional) true while troubleshooting |
Data Flow Diagrams
For bots you can see the flow that is taken

For normal web users (humans) the flow is much simpler as it skips injecting markup

In terms of accessing the CDN the functionality is shown below

Frequently Asked Questions
How many milliseconds does the Edge Worker add to the Time to First Byte (TTFB)?
The worker only fires for bot User-Agents (a Property Manager condition), so real users have zero TTFB impact by design.
For bots, the three sub-requests — origin HTML, Schema App main JSON-LD, and the highlighter — are dispatched in parallel via Promise.allSettled. TTFB is therefore bounded by the slowest of the three, not their sum:
The HtmlRewritingStream is a streaming transformer, not a buffer, so it adds only ~1–5 ms regardless of page size.
In total for bots the typical is ~50ms.
If the Schema App API or the Edge Worker fails, does the page still render the core content, or is there a risk of breaking the source code?
The worker is well-hardened. Every CDN failure path falls back to serving the origin HTML untouched if the worker fails your page is rendered as if the worker didn't execute.
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article