Server Side Rendering — Akamai Setup Instructions

Modified on Mon, 2 Mar at 4:30 PM

Schema App CDN Injection — Akamai Setup Instructions

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.

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. 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 two user-defined variables to your property.
Add a Conditional Origin rule so the worker’s CDN subrequests go to Schema App’s CDN.
Add a Schema App Inject rule that runs the Edge Worker only for bot User-Agents.
Configure cache key and bypass so the worker and subrequests behave correctly.
Activate to staging, test, then activate to production.

Rule order matters: The Conditional Origin 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 or curl -O https://cdn.schemaapp.com/javascript/schemaapp-edgeworker.tgz). The bundle contains bundle.json and main.js at the root, as required by Akamai.
Upload the bundle in Akamai:
- Control Center: Edge Workers → Create / Manage → upload the downloaded .tgz and create a new Edge Worker (or new version of an existing one).
- CLI: Use the Akamai Edge Workers CLI to upload the bundle.
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 two user-defined variables (e.g. under the Variables section or in the default rule’s configuration):

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.

Important:

Variable names must match exactly (no extra spaces before or after).
PMUSER_SCHEMAAPP_CDN_BASE_URL must be the hostname clients use to reach your property. The worker sends subrequests to this host; your Conditional Origin rule then forwards those requests to Schema App’s CDN.

3. Add the Conditional Origin rule (CDN proxy)

This rule sends the worker’s CDN subrequests to Schema App’s CDN. It must be a top-level rule (sibling of your other rules), and it should be placed above the Schema App Inject rule so it is evaluated first.

Create a new rule (e.g. name: Conditional Origin Definition).
Criteria:
- Request Header → Header name: X-SchemaApp-CDN-Request
- Match: Exists (or value true).
  No path or other conditions.
Behaviors:
- Origin (or Origin Server / Conditional Origin):
  - Origin hostname: data.schemaapp.com
  - Origin type: HTTPS (port 443).
  - Forward host header: Origin hostname (so CloudFront receives Host: data.schemaapp.com). This is required; if you forward the request host instead, CloudFront may return 503.
  - Save the origin.
- Optionally add CP code if your property uses it.
Path: Forward the path as-is. Do not strip or rewrite the path. The worker sends paths like /{accountId}/{base64PageUrl} that the Schema App CDN expects.
Do not cache responses from this rule — add a Caching behavior to this rule and set it to NO_STORE (or Do not store). Responses from the Schema App CDN must not be cached by Akamai; caching of markup is managed on the Schema App side. If you omit this, a parent rule may cache these responses and bots could receive stale or incorrect JSON-LD.

4. Add the Schema App Inject rule (Edge Worker)

Create a new rule (e.g. name: Schema App Inject).
Criteria:
Request Header → User-Agent → Matches one of (or Matches regex), with a list of bot identifiers. For example:
- *SchemaBot*
- *Googlebot*
- *Bingbot*
- *Slurp*
Schema App maintains a recommend list of Bots here.
Add or remove bots per your requirements. Only requests that match will invoke the worker. Be sure to add *SchemaBot* since that allows Schema App's crawler to evaluate the markup. Also make sure to add wildcards around each botname so it will match against the useragent string.
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. Cache key and subrequest bypass

The worker fetches the page HTML from the same URL the client requested. To avoid cache collisions and infinite loops:

Cache key: Add the X-Subrequest header to the cache key for the behavior (or rule) that serves the Edge Worker. That way the worker’s internal “origin fetch” (which sends X-Subrequest: true) is cached separately from the response the client receives (the modified HTML).
Bypass the worker on subrequests: Add a condition (or rule) so that when the request has the header X-Subrequest = true, the Edge Worker is not invoked. The worker itself adds this header only to its own origin fetch; normal clients do not send it. This prevents the origin subrequest from re-triggering the worker.

(Exact placement of cache key and bypass depends on your property structure; ensure the origin fetch uses a distinct cache key and does not run the worker again.)

6. 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.html and 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 you see 503, verify the Conditional Origin rule uses Forward host header: Origin hostname.
Activate to Production when staging looks correct.

Quick reference

What	Value or action
CDN origin hostname	`data.schemaapp.com`
Forward host header (for CDN origin)	Origin hostname (required)
Conditional Origin match	Request header `X-SchemaApp-CDN-Request` exists
Conditional Origin caching	NO_STORE — do not cache CDN responses on this rule
`PMUSER_SCHEMAAPP_CDN_BASE_URL`	`https://<your-property-hostname>` (same as request host; not data.schemaapp.com)
`PMUSER_SCHEMAAPP_ACCOUNT_ID`	Your Schema App account ID; variable name with no trailing space
Cache key	Include `X-Subrequest` so origin fetch is cached separately
Bypass worker when	Request header `X-Subrequest` is present

Troubleshooting

No CDN subrequests / only one subrequest: Check that both variables are set with exact names (no spaces) and that PMUSER_SCHEMAAPP_CDN_BASE_URL is your property host (e.g. https://www.yourdomain.com), not https://data.schemaapp.com.
503 on CDN subrequests: Set the Conditional Origin’s Forward host header to Origin hostname so CloudFront receives Host: data.schemaapp.com.
Worker not running: Ensure the request User-Agent matches one of the bot patterns in the Schema App Inject rule.
Stale or wrong JSON-LD: Ensure the Conditional Origin rule has Caching: NO_STORE. If that rule (or a parent) caches responses from the Schema App CDN, bots may receive outdated markup.