Bringing your own site

​

What the archive should contain

• Build output and dependency folders. node_modules, .next, dist, and any local emulator state don’t belong in the archive — they’re rebuilt for you, and including them only makes the upload slower and harder to read.
• Your own copies and version-control files. Leave out .git and any backup or “original” copies of the project sitting alongside it.
• Content. Your database rows and media files are not part of the code archive — see Media and Migrations for a new site below for how those travel separately.

​

Dependencies: no install scripts, keep the lockfile

• No install scripts. Dependencies are installed with lifecycle scripts turned off, so a package that only finishes setting itself up through a postinstall step won’t finish setting itself up. Most everyday packages — UI libraries, routing, forms, styling — need nothing like this. If a dependency in your project does, it needs to come out before you send us the project.
• Commit your pnpm-lock.yaml. We build with pnpm, and we install exactly what that lockfile lists — we never resolve a version off the package registry on your behalf. Keep it committed and current: run pnpm install locally after any dependency change, so the lockfile reflects what package.json asks for. We read only pnpm-lock.yaml; an npm, yarn or bun lockfile isn’t read at all, so a project that ships one of those instead — or no lockfile — is refused before anything is built, naming exactly what’s missing.

​

Analytics and consent

​

The deploy manifest

​

Migrations for a new site

​

Media

• Files your pages serve directly — images and assets your code references by path — ship inside the archive’s static folder. They’re classified as ordinary site files and go live with your first publish.
• Files your backend reads from your own storage are different. Your storage is created the first time a build that declares it is staged — before you publish — and it starts out empty. There’s no bulk import for existing media today. For a brand-new site, the honest path is to add files through your site’s own upload flow once it’s live, or ask us about a one-time bulk load.

​

Check it, then ship it

​

Bringing a new site

1. Import. Creates the site and starts the build.
2. Preview. See below — preview is live-bound, not read-only.
3. Publish. Moves your live address to the build you just previewed — one exact version, reviewed before anything changes.

​

Replacing a site you already run with us

1. Import — see the diff first. The response tells you nothing was written, and carries a handle together with a diff of what would change if you went ahead:
   {
     "outcome": "pending_confirmation",
     "siteId": "<site-id>",
     "handle": "h1.<sha256 of your archive>.<the current build>",
     "base": { "kind": "bundle", "ref": "<the current build>" },
     "diff": {
       "added": [{ "path": "about.html", "bytes": 1204 }],
       "removed": [],
       "changed": [{ "path": "index.html" }],
       "summary": { "added": 1, "removed": 0, "changed": 1, "unchanged": 4 }
     }
   }
   
   The diff names only code-project files — never your storage, your media, your domain, or anything else that makes the site yours. Your database is the one exception, and the rule is exact: a replacement whose migrations are byte-identical to what’s already applied changes no data; a replacement that carries new migration files applies them to your live database at that same build, before you ever publish — see Migrations for a new site above.
2. Confirm — resend the identical archive, with the handle on the URL. Send the exact same bytes to the exact same endpoint, adding the handle from step 1 as a query parameter:
   POST https://app.goosybear.ai/api/pages/ingest?confirm=<handle>
   
   Same file, same siteId — only the query string changes. That call is the one that actually writes: it answers with an "outcome": "ingested" body and starts the build.
3. New migrations run against your real database, at that same build — before you ever publish. If your replacement adds new migration files, this is where they run; see Migrations for a new site above for what makes a migration safe to send this way.
4. Preview. See below.
5. Publish. Moves your live address to the build you just previewed.

​

Preview is live-bound, not read-only

​

Republish to roll back

​

The consent banner, ad pixels and conversions

• Consent banner. Our banner becomes the one consent source on your site, and your own code can read its decision.
• Ad pixels. The pixels of the ad accounts you’ve connected load on your site. They need the banner on.
• Ask before tracking. On (the default), nothing that needs consent loads until a visitor accepts. Off, analytics and your ad pixels load when a visitor arrives, and the banner is a notice that lets them opt out. Either way, a browser that sends Global Privacy Control is treated as opted out, and so is a visitor who opted out before.

​

What your HTML needs

• Every page has a real <head> element. We add two script tags, <script src="/__goosy/collector.v1.js"> then <script src="/__platform.js">, as its first children; a page without a <head> tag gets nothing.
• No second cookie banner. With ours on, remove yours.
• If you send a Content Security Policy, it has to allow our script and the hosts of the ad pixels you’ve switched on. Our scripts are served from your own site, so script-src 'self' covers them. CSPs that use 'strict-dynamic' aren’t supported yet.
• window.goosy and the rs-page-consent storage key are ours. Don’t define the first, and don’t read or write the second.

​

Reading the visitor’s decision

import posthog from "posthog-js";

function applyConsent(state) {
  if (state === "granted" && !posthog.__loaded) posthog.init("phc_YOUR_KEY", { api_host: "https://us.i.posthog.com" });
  else if (state === "granted") posthog.opt_in_capturing();
  else if (state === "denied" && posthog.__loaded) posthog.opt_out_capturing();
}

const goosy = window.goosy;
if (goosy) {
  applyConsent(goosy.consent);
  window.addEventListener("goosy:consent", (event) => applyConsent(event.detail.state));
}

​

Reporting a lead your server sends us as a conversion

1. In the browser, before you call your server, take window.goosy.leadFields(). It returns { consent, eventId, fbp, fbc, fields }. eventId is a fresh id when the visitor has granted consent, and null otherwise. fields holds the same values under the names our intake reads (rs_meta_event_id, rs_meta_fbp, rs_meta_fbc, rs_page_path, and rs_attribution for the visitor’s first ad click and campaign tags).
2. On your server, add fields to the lead’s own fields unchanged, and send your page’s hostname beside them.
3. Back in the browser, once your server says the lead was accepted, call window.goosy.trackLead(eventId) with the eventId our intake answered. That fires the browser Lead on each connected platform with the same id as our server-side event, so each platform counts the conversion once. It returns true when it fired.

// In your form's submit handler.
const plumbing = window.goosy ? window.goosy.leadFields() : { fields: {} };
const answer = await submitApplication({ ...answers, ...plumbing.fields });
if (answer.ok && window.goosy) window.goosy.trackLead(answer.eventId);

// In your server action: forward the lead, and hand back the id we answered.
const response = await fetch(`${env.GOOSY_API_BASE}/api/pages/leads`, {
  method: "POST",
  headers: { "content-type": "application/json", authorization: `Bearer ${env.GOOSY_API_KEY}` },
  body: JSON.stringify({ fields: { form: "application", ...fields }, hostname }),
});
const body = response.ok ? await response.json() : null;
return { ok: response.ok, eventId: body?.eventId ?? null };

• We answer an eventId only when the lead becomes a conversion: the visitor granted consent, the form is one your site counts as a conversion (every form, until you name some in site settings), and the address isn’t a test address. Otherwise it is null, and trackLead fires nothing.
• A value in one of those fields that isn’t in the shape leadFields() produces is refused with 400 {"error":"invalid_field","fields":[…]}, and nothing is stored. Pass them through unchanged.
• The consent is your visitor’s claim, as on any web form. We treat a lead without an eventId as not consented and report nothing for it.

​

Where to go next

• Pages API — the full call reference for each step above.
• The deploy contract — every pages.deploy.json field, and the complete ceilings list.
• Site and project databases — how your code reads its database once it’s live.
• Recipes — a complete run, from an empty folder to a live site.