Architecture
How Amplify Up, Edge, personalization tiers, and SDK(s) work together.
This page is the shared model for every SDK. Amplify Up publishes a page; Edge serves it and chooses a variation; an SDK on your site renders that page and sends visitor events.
You do not run a personalization engine, host layout storage, or hold content-source credentials on your site. Install and render steps differ by SDK — those guides live under SDK in the sidebar (Node is available today).
How a page reaches a visitor
Composer (compose, bind content, write rules)
→ Deploy
Edge (published layout + personalization)
↑
Your site — SDK(s)
• render the composed page
• send page / track / identify events
- Operators compose the page in Composer, connect content, and write personalization rules.
- Deploy publishes that page to Edge. Until a route is deployed, visitors see your fallback.
- An SDK asks Edge for the layout for the current route (and variation, when personalized).
- Your registered components render with the props Edge already filled in.
- The SDK sends page, track, and identify events so returning visitors can match profile-based rules.
Composer preview is a separate path: when the page loads inside Amplify Up, the SDK shows the draft. Visitors always see the last Deploy.
Edge
Edge is Amplify Up’s delivery surface for live sites. After Deploy it holds the published layout for each route — structure, content props, and the rules that choose a variation.
SDK(s) talk to Edge to:
| Job | What an SDK does |
|---|---|
| Resolve a page | Load the published layout (and a specific variation when one matches) |
| List routes | Pre-render published paths at build, when the SDK supports it |
| Pick a variation | Ask which variation this visitor should get, then load that layout |
| Runtime content | Fetch more rows after the visitor searches or loads more |
HTML (or the equivalent payload) is cached per variation, not per visitor. Most first-time visitors get the default published page. Returning visitors with a visitor ID can get a personalized variation without the client evaluating rules.
Production Edge and event endpoints are the SDK default. You only pass a tracking ID.
Personalization tiers
Every condition in Composer belongs to a tier. The tier is about what Edge can see when it chooses a variation — not something you configure in an SDK.
| Tier | Product name | Matches on | When it applies |
|---|---|---|---|
| Instant | Edge Powered (Instant) | Facts on this request — region, device, campaign parameters, time of day, experiment split | As soon as Edge can see the request. No visitor history required. |
| Profile lookup | Profile Lookup (Fast) | Visitor history — pages viewed, engagement, audiences, and similar profile fields | After Amplify Up knows the visitor (typically a returning visit with a visitor ID). The lookup still runs on Edge — Edge loads the profile and applies the rule there. |
| First visit / overlay | — | Same rules, applied after the default page paints | First visit, missing visitor ID, or Edge timed out. An SDK can swap in the matching variation after paint. |
A rule that mixes instant and profile conditions uses the slower of the two (profile lookup). First match in Composer order still wins.
Profile lookup is not a browser or app-side decision. Instant rules and profile-lookup rules both execute on Edge. Profile lookup only adds a profile read on Edge before it picks the variation.
What this means on the site
- Returning visitors: an SDK can ask Edge for the variation before the page is served, then reuse that variation later.
- First-time visitors: the default page paints immediately so the first frame stays fast. If a rule then matches, an SDK can overlay the personalized layout.
- Fail-open: if Edge cannot decide in time, visitors keep the default. They are not stuck behind a decision.
You do not pick a tier when you install an SDK. You pick conditions in Composer; Amplify Up assigns the tier.
Profile-lookup rules need events. If tracking is missing, instant rules (region, device, campaign) still work; history-based rules will not.
SDK tracking
Every SDK identifies the site with the tracking ID and keeps a first-party visitor ID so Edge and Insights can recognize the same person across page views.
| Call | What it records |
|---|---|
page(path) | A page view |
track(name, properties) | A named action (clicks, conversions, custom) |
identify(userId, traits) | A known user attached to that visitor |
Events are how visitor profiles get pages viewed, engagement, and similar fields. Insights shows those profiles after events are processed. Composer preview does not send visitor events.
Prefer an SDK over raw HTTP so visitor IDs and retries stay consistent. HTTP details are under API.
Package names and render helpers differ by SDK. The events model and the Edge resolve/select flow stay the same.
What you own vs what Amplify Up owns
| You own (your site + SDK(s)) | Amplify Up owns |
|---|---|
| Component registry and field / slot names | Composer, rules, and Deploy |
| Fallback content until a route is deployed | Published layouts on Edge |
Calling page / track / identify | Visitor profiles and Insights |
| Framework helpers your SDK provides (for example static generation) | Choosing the matching variation — including profile lookup on Edge |
Content sources stay connected in Amplify Up. Edge fills component props at resolve time. Your site never talks to the content source with stored credentials.
Next
- Install (Node SDK) — available today
- Render pages
- Track events