Crossdeck Docs
Dashboard

Crossdeck for WordPress — full setup guide

Setup Plugin install · automatic identity, custom domain, revenue · ~5 min read · Updated August 4, 2026

Everything from install to identity to revenue. Install the Crossdeck plugin and it enqueues the Crossdeck web SDK on every front-end page of your WordPress site — so page analytics, journeys, and front-end error impact start flowing with no theme edits. And WordPress is the one connector where identity is fully automatic: the plugin reads the logged-in user server-side and resolves them to a known person with zero configuration. This doc covers each step, plus the two parts that still need a decision from you: a custom domain and connecting a payment rail for revenue.

TL;DR

What the connector does

Install the Crossdeck plugin and it enqueues the Crossdeck web SDK on every front-end page of your site — hooked into wp_enqueue_scripts and initialized with a single init() call — so page analytics, journeys, and front-end error impact start flowing with no theme edits and no per-page setup. Nothing loads in wp-admin, and nothing loads until you connect. Because Crossdeck joins identity, revenue, errors, and analytics on one identity graph, you can answer questions no single-layer tool can — for example, “which paying customers hit this error last week.”

Publishable key only — never a write credential.

The one-click connect completes an OAuth (authorization-code + PKCE) handshake and uses a workspace token in memory, only during setup, to provision your project and app. That token — and any refresh token — is discarded the moment setup finishes. The plugin persists only a publishable key (cd_pub_), your App ID, your project ID, and the selected environment. It cannot read or change your Crossdeck account.

Step 1 — Install

A. Install the plugin on WordPress

  1. Install Crossdeck from the WordPress.org plugin directory once approved — or upload the zip: Plugins → Add New → Upload Plugin, choose the crossdeck zip, and install.
  2. Activate the plugin from the Plugins screen. (Activation provisions nothing on its own — connecting is an explicit step.)

B. Connect — one click

  1. Go to Settings → Crossdeck.
  2. Choose an Environment (Production is the default; a Sandbox option is available) and click Connect Crossdeck.
  3. You are sent to Crossdeck to authorize the connection, then returned to your site. Crossdeck registers a dedicated OAuth client for your site, provisions a project + web app for your domain, and stores your publishable key. The SDK now loads on your front-end pages.

C. Or paste your two values (advanced)

  1. On the settings screen, expand Advanced: paste keys manually.
  2. Paste your Publishable key (must start cd_pub_) into the Publishable key field and your App ID (starts app_) into the App ID field, pick an environment, and Save keys.
Environment and the key prefix.

You pick the environment during connect — Production by default, with a Sandbox toggle you can switch later from the connected view. Crossdeck test publishable keys carry a cd_pub_test_ prefix while production keys do not, so the key and the environment always agree. Until a valid cd_pub_ key and App ID are both stored, the plugin enqueues nothing — zero cost and a clean front end.

Publishable key only.

The plugin holds only your publishable, ingest-only key (cd_pub_). Never paste a secret or workspace key (cd_sk_ / cd_wk_) — the manual path refuses anything without a cd_pub_ prefix. Provisioning happens on the Crossdeck engine, never on the WordPress host.

Step 2 — Verify it's working

Visit your site's front end (a real page, not wp-admin) and click around. Crossdeck's first heartbeat auto-learns your site's origin. Then open the Crossdeck dashboard → Overview / People — you'll see a live visitor with geo, and the pages they viewed. (Data begins from the first real visit — that first heartbeat also locks your Allowed Origins to that domain.)

Nothing showing yet?

Check that Settings → Crossdeck shows Connected (both a publishable key and an App ID are stored), that you're viewing a front-end page rather than the admin, and that the environment you're viewing in the dashboard matches the connected environment. The first heartbeat can take a few moments.

Step 3 — Custom domain

When you move WordPress to a new domain, or add one, add it to your Allowed Origins — 20 seconds, and it pulls you into the dashboard:

→ Add a domain to your Allowed Origins

The origin lock happens on the first heartbeat — then it locks.

Your site learns the domain it was first served on on its first heartbeat. It will not auto-learn a domain you add later — if you migrate hosts, move to a custom domain, or add a second domain, add it to your Allowed Origins yourself, or traffic from it won't be accepted.

Step 4 — Identity (automatic — the WordPress advantage)

Analytics works anonymously out of the box. Turning anonymous visitors into known people — the Crossdeck cross — is where WordPress pulls ahead. Unlike Bubble (a workflow action you wire) and Webflow (a data-attribute you bind), WordPress identity is fully automatic with no configuration.

WordPress exposes the current user server-side, so the plugin doesn't need any client-side accessor. On each front-end page it reads wp_get_current_user(), and when is_user_logged_in() is true it emits an inline Crossdeck.identify(email, { email }) call right after init() — the same shape every other connector produces. So any logged-in WordPress, WooCommerce, or membership user resolves to a known person in People the moment they load a page. Nothing to add, nothing to bind.

How it behaves with caching.

Anonymous pages — the cacheable ones — emit nothing: a full-page cache serves logged-out visitors a page with no email. Logged-in users, whom full-page caches bypass by default, get a fresh page carrying only their own email, escaped through wp_json_encode and wrapped in a guarded try/catch so it can never throw into the page.

Don't cache pages for logged-in users.

If a caching plugin is configured to serve cached pages to logged-in users, disable that — it would serve one user's identity to another (and is discouraged by standard WordPress guidance regardless). The default behaviour of every major cache is to bypass logged-in users, which is exactly what the automatic identify relies on.

Why email is the anchor.

Crossdeck keys identity on email — the no-backend join rail — so the logged-in user's WordPress email is what resolves them across analytics, errors, and revenue. (See How identity works for the full model.)

Step 5 — Revenue (connect a payment rail)

To join revenue to those people:

  1. In the Crossdeck dashboard, open Developers → Rails (Payment rails).
  2. Connect Stripe (or Apple / Google) in one click — Crossdeck never asks for a raw secret key.
  3. Stamp the Crossdeck reference onto your checkout / subscription events so each payment threads back to the right person. If you sell through WooCommerce or a Stripe checkout, see Rails → Stripe in the dashboard for the exact one-liner.

Once a rail is connected, revenue and entitlements join the same identity graph as your analytics and errors. (Sending revenue events is done from your Crossdeck account setup — not from the WordPress plugin.)

How this differs from the other connectors

Every connector loads the same Crossdeck SDK and feeds the same dashboard — only the install + identity binding differ per platform, and WordPress needs the least.

Crossdeck for WordPress — plugin install with one-click OAuth connect (or manual publishable key + App ID), SDK enqueued site-wide via wp_enqueue_scripts, publishable-only storage (write credential discarded after setup), custom-domain add via Allowed Origins, fully automatic server-side identity for logged-in users, and revenue on a connected rail (August 4, 2026). Related: Identify users, Connect Stripe.

Using an AI assistant? Read this page as clean markdown — index.md — or the whole docs index at /docs/llms.txt.