Reference

Compatibility Setup

How to configure your app's security policies so Checkpoint can embed it, run the agent, and map comment anchors accurately.

ℹUse this guide when a shared session shows: Comment mapping degraded: this app may block the Checkpoint agent via CSP or restrictive frame policy.

Why this happens

Checkpoint comments rely on three things:

  1. The app can be embedded in the Checkpoint share frame.
  2. The Checkpoint agent can run in the embedded page.
  3. The DOM is stable enough to re-find comment anchors.

If any of these fail, comments still work, but precise pin and code mapping may degrade.

Quick status meanings

StatusMeaning
Agent connectedCheckpoint agent loaded and messaging is active
Framing blockedYour app prevents iframe embedding via frame-ancestors or X-Frame-Options
CSP blockedContent Security Policy blocks agent execution
Anchor fallback modeMapping uses coordinate/text fallback rather than strong anchors

Required policy changes

1. Allow embedding from Checkpoint

Add https://app.checkpoint.build to your CSP frame-ancestors directive.

2. Avoid restrictive frame headers on review pages

Do not use X-Frame-Options: DENY or strict SAMEORIGIN for routes reviewed in Checkpoint.

3. Keep script policy compatible

Your CSP must allow scripts needed by your app and Checkpoint review instrumentation.

Copy-paste snippets

Next.js

next.config.js
const securityHeaders = [
{
key: "Content-Security-Policy",
value:
"default-src 'self'; " +
"script-src 'self' 'unsafe-inline' 'unsafe-eval'; " +
"style-src 'self' 'unsafe-inline'; " +
"img-src 'self' data: blob: https:; " +
"font-src 'self' data: https:; " +
"connect-src 'self' https: wss:; " +
"frame-ancestors 'self' https://app.checkpoint.build"
}
];

Express

server.js
app.use((req, res, next) => {
res.setHeader(
"Content-Security-Policy",
"default-src 'self'; " +
"script-src 'self' 'unsafe-inline' 'unsafe-eval'; " +
"style-src 'self' 'unsafe-inline'; " +
"img-src 'self' data: blob: https:; " +
"font-src 'self' data: https:; " +
"connect-src 'self' https: wss:; " +
"frame-ancestors 'self' https://app.checkpoint.build"
);
// Do not set X-Frame-Options: DENY/SAMEORIGIN for review pages
next();
});

Nginx

nginx.conf
add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: https:; font-src 'self' data: https:; connect-src 'self' https: wss:; frame-ancestors 'self' https://app.checkpoint.build" always;
# Avoid DENY/SAMEORIGIN on review pages
# add_header X-Frame-Options SAMEORIGIN;

Best reliability for exact mapping

Add explicit anchors to important UI elements using the data-checkpoint-anchor attribute:

html
<button data-checkpoint-anchor="save-order-button">Save</button>

Use stable IDs and keys for repeated list items when possible.

Security recommendation

Apply relaxed policies on review and staging routes when possible, rather than globally across all production pages.

Troubleshooting checklist

  1. Confirm the page loads inside the Checkpoint share frame.
  2. Check the browser console for CSP or frame violations.
  3. Verify frame-ancestors includes https://app.checkpoint.build.
  4. Remove or reduce restrictive X-Frame-Options for review routes.
  5. Add data-checkpoint-anchor attributes to critical interaction points.