Connect a website to Cygnetree

Choose a public entry point

Use a Cygnetree form for inquiries, a booking page for scheduling, a service page for service selection, and the client sign-in link for returning clients. Keep the source object authoritative; the website should reference it instead of copying questions, availability, prices, or contract content into another system.

Use links before custom code

A normal branded link is the safest zero-code integration and works on WordPress, Next.js, Squarespace, Wix, Webflow, social profiles, and plain HTML. Add campaign parameters that identify the site and placement without including personal data.

Do not put an API key, provider credential, signing secret, client token, or private project link in browser markup. Public identifiers must be scoped and revocable.

Use the brochure-site builder

Open Settings → Website and public links and create a private starter site. Choose a lead form, booking page, or service page from the workspace; the site stores references to those records rather than copied questions, availability, or prices.

Save changes as often as needed. A save changes only the private draft. Publish current draft validates all pages and creates an immutable version before atomically replacing the public snapshot. Pause public site removes public access without deleting drafts or versions. Restoring a version changes the private draft and requires another deliberate publish.

The current builder supports accessible multi-page brochure sites, organization theme tokens, hero/story/services/testimonial/FAQ/call-to-action sections, announcements, navigation, live entry points, private visual preview, page duplicate/reorder/archive, public versioning, rollback-to-draft, JSON export, and first-party attributed project/pipeline/paid-invoice summaries. It does not yet replace a full WordPress or custom Next.js content system.

Connect WordPress

The preview plugin lives in integrations/wordpress/cygnetree. Install that directory as a plugin, verify the public app and client-portal origins under Settings → Cygnetree, and add a Cygnetree public link Gutenberg block. Choose its destination, copy the public slug from Cygnetree, and optionally label its campaign and placement.

The equivalent shortcode is:

[cygnetree_link type="form" slug="consultation" label="Start a project"]

Supported types are form, booking, brochure, and client_login. The server-rendered block and shortcode store only public origins and identifiers. They do not request a workspace login, OAuth grant, API key, provider credential, or private project link. Diagnostics, update delivery, and broad plugin-compatibility certification are not yet claimed.

Connect Next.js or another website

Copy a generated plain-HTML or Next.js link from Website and public links. For a progressively enhanced plain website, load /embed/cygnetree-link.js from the Cygnetree public website and use the generated <cygnetree-link> element. A normal anchor remains the safest fallback.

The @cygnetree/web-presence package provides typed URL, HTML-link, and WordPress shortcode helpers. Import @cygnetree/web-presence/react for server-renderable CygnetreeFormLink, CygnetreeBookingLink, CygnetreeBrochureLink, and CygnetreeClientLoginLink components. They render ordinary anchors and require no browser JavaScript.

The helpers deliberately accept only public origins, bounded campaign values, and validated public slugs. Tenant credentials remain server-only.

Reuse the workspace theme

The authenticated site export includes the validated workspace theme alongside drafts and published versions. A published site's bounded CSS variables are also available at:

https://app.cygnetree.com/api/web-presence/public/{site-slug}/theme.css

Load that stylesheet or use cygnetreeThemeTokens and cygnetreeThemeCss from the typed package. The export contains colors, fixed typography families, radius, and density. It never contains tenant-authored CSS or script, which keeps white-label configuration portable without making a tenant stylesheet an execution boundary.

Report privacy-aware conversion events

Use cygnetreeMetricAttributes for a Cygnetree-rendered call to action or reportCygnetreeMetric for a custom website. The helper sends only the public site ID, public page ID, and one bounded event type: view, cta, form, booking, or brochure. It sends no cookie, visitor ID, URL, query string, IP address, user agent, or referrer.

reportCygnetreeMetric stops before making a request when the browser advertises Global Privacy Control or Do Not Track. The public event endpoint supports credential-free cross-origin requests and is rate limited. Counts are aggregate activity, not unique people or a cross-page journey.

Diagnose an embed

Call diagnoseCygnetreeIntegration in a setup check or support diagnostic. It reports an insecure origin, incompatible major helper version, or a Content Security Policy connect-src that omits the Cygnetree application origin. The diagnostic returns bounded error codes and origins; it does not inspect page content or credentials.

Use the public integration playground to generate a fixture link and check these values without signing in or touching a real workspace.

For an external event reporter, allow the application origin in connect-src. Ordinary links and the public theme stylesheet still work without JavaScript. The package exports neutral test fixtures from @cygnetree/web-presence/fixtures so a site can test integration code without using a real workspace.

Preserve attribution

Use UTM source, medium, campaign, content, and a consent-aware first-party referral value. Carry that acquisition evidence into the person and project without third-party cookies. Do not infer a marketing source when no evidence exists.

Test duplicate submit, blocked script, back/forward navigation, cross-domain referrer policy, and privacy choices. Attribution must never change who can access a project.

Test safety and accessibility

Before publishing:

1. Complete the flow with keyboard, screen reader, 200% zoom, and a phone-size viewport.
2. Test with JavaScript blocked and a slow/interrupted network.
3. Verify labels, errors, focus, contrast, tap targets, and confirmation behavior.
4. Confirm rate limits, bot challenge, duplicate-submit handling, and no secret in HTML or logs.
5. Verify the website can remove the integration without losing collected Cygnetree records.

Export a Cygnetree-built site from its version-history card before a destructive website change. The export contains the private draft and immutable publish versions; it contains no provider credential.