Decision based on Cookies

What you'll build

You will learn how to use a Surface component workflow to read cookies forwarded by the MonetizationOS proxy and make decisions based on them. If your page is served via a MonetizationOS Proxy, selected cookies from the client request and origin Set-Cookie headers are included automatically in the Surface Decisions API request.

1. Prerequisites

1. You will need a Component Workflow in a Surface
2. Your site must be deployed behind a MonetizationOS Proxy, such as the Cloudflare Worker Proxy

2. Configure cookie forwarding in the proxy

By default, no cookies are forwarded to the Surface Decisions API. You must configure the proxy to select which cookies to send by providing comma-separated regex patterns in the surfaceDecisionsCookies config option.

For the Cloudflare Worker proxy, set the SURFACE_DECISIONS_COOKIES environment variable to the patterns that match the cookies your workflows need:

{
  "vars": {
    "SURFACE_DECISIONS_COOKIES": "^__session$, ^theme$, ^user-segment$"
  }
}

This configuration forwards the __session, theme, and user-segment cookies (matching the exact names) to the Surface Decisions API. Each pattern is a regular expression — ^__session$ matches only the cookie named __session, while a broader pattern like ^user- would match any cookie whose name starts with user-.

3. Add a component

The selected cookies are available in the Surface Workflow context via context.cookies. The keys are cookie names and the values are their string values as parsed by the proxy from the Cookie request header and the origin Set-Cookie headers.

const workflow: SurfaceWorkflow = async ({ context }) => {
  const session = context.cookies?.__session ?? null;

  return {
    properties: {
      session,
    },
  };
};
export default workflow;

For example, you could use the forwarded cookie value to set properties that downstream component workflows can reference:

const workflow: SurfaceWorkflow = async ({ context }) => {
  const userSegment = context.cookies?.["user-segment"] ?? "default";
  const isVip = userSegment === "vip";

  return {
    content: {
      append: [
        {
          type: "html",
          content: isVip
            ? '<div class="vip-banner">Welcome, VIP member!</div>'
            : '<div class="guest-banner">Discover our premium content</div>',
        },
      ],
    },
  };
};
export default workflow;

Result

When a client request includes a matching cookie, the cookie value is forwarded to the Surface Decisions API and becomes available in the workflow context. The proxy selects cookies from both the incoming Cookie request header and any Set-Cookie headers from the origin response, allowing you to react to session values set during the same request.

For example, if a visitor's browser sends Cookie: __session=eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0, the workflow above would set the session property to the JWT value, which can then be used by other workflows or returned in the surface behavior response.

Additional resources

• Surface Workflows reference
• Perform Surface Decision API reference
• Proxies concept guide
• Component Workflows reference
• Cloudflare Worker Proxy Getting Started