Server Side Rendering — Akamai Setup Instructions

Modified on Fri, 6 Nov at 6:58 PM

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/



Overview

You will:

  1. Deploy the Edge Worker bundle and note its ID.
  2. Add the user-defined variables to your property.
  3. Add a Schema App CDN rule that sends the Edge Worker's markup requests to Schema App's CDN.
  4. Add a Schema App Inject rule that runs the Edge Worker on page requests from bots.
  5. 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

  1. Download the bundle from Schema App’s CDN:

  2. 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.
  3. 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 nameValueNotes
PMUSER_SCHEMAAPP_ACCOUNT_IDYour Schema App account ID (e.g. ExampleAccount)Exact name — no leading or trailing spaces.
PMUSER_SCHEMAAPP_CDN_BASE_URLhttps://<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 nameValueNotes
PMUSER_SCHEMAAPP_PROJECTSA 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:

FieldRequiredMeaning
baseUrlYesScheme + host (e.g. https://www.yourdomain.com). Must be a hostname on this property, not data.schemaapp.com.
accountIdYesSchema App account ID for that entry (same format as PMUSER_SCHEMAAPP_ACCOUNT_ID).
pathPrefixNoMatch 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 nameValueNotes
PMUSER_SCHEMAAPP_DEBUGtrueTurns 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 each baseUrl in PMUSER_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.

  1. 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.

  2. Criteria: Request Header, header name X-SchemaApp-CDN-Request, exists (or is one of true).

  3. 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.
  4. 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.

  5. 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.

  6. (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)

  1. Create a new rule (e.g. name: Schema App Inject).

  2. Select 'Match All'. Only requests that match all the criteria will invoke the worker.

  3. 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.

  4. Criteria: Match → Request Method → is → GET. Only requests to pages that should display Schema Markup will invoke the worker.

  5. 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.

  6. 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

  1. Save the property version.

  2. Activate to Staging. In Property Manager, use Activate → Activate to Staging (or equivalent) for this version.

  3. 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 markup is missing or subrequests fail, see How-To: Troubleshoot Akamai Integration.
  4. 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

WhatValue or action
Rule placementSchema App CDN, then Schema App Inject
Schema App CDN rule criteriaRequest header X-SchemaApp-CDN-Request exists
Schema App CDN origin hostnamedata.schemaapp.com
Schema App CDN Forward Host HeaderOrigin Hostname (required)
Schema App CDN cachingNo 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_URLSingle project: https://<your-property-hostname> (same as the request hostname; not data.schemaapp.com)
PMUSER_SCHEMAAPP_ACCOUNT_IDSingle project: your Schema App account ID; variable name with no trailing space
PMUSER_SCHEMAAPP_PROJECTSMultiple 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:

ScenarioAdded latency
CDN edge-cached (typical after first crawl)
2–10 ms
CDN slightly slower than origin
15–40 ms
CDN cold cache miss
50–150 ms

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

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article