# Crossdeck for WordPress

> Source: https://cross-deck.com/docs/wordpress/ · Crossdeck developer docs (generated from the published page).

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

- **Install, then connect.** Install the Crossdeck plugin (WordPress.org directory once approved, or upload the zip), activate it, then open **Settings → Crossdeck** and click **Connect Crossdeck** — a one-click OAuth handshake provisions a project + web app and loads the SDK on your front end.

- **Or paste keys.** Prefer manual? Expand **Advanced: paste keys manually** and enter a **Publishable key** (`cd_pub_…`) and **App ID** (`app_…`) from your Crossdeck dashboard.

- **Publishable-only storage.** The plugin stores **only** the publishable key + App ID (ingest-only). The write credential is used in memory during connect and then discarded — never written to your database.

- **Identity is automatic.** No action to wire, no attribute to bind. When a WordPress / WooCommerce / membership user is logged in, the plugin emits `Crossdeck.identify()` server-side, so they resolve to a known person out of the box.

- **Verify from the first real visit.** Load the site, then watch a live visitor land in **Overview** / **People**. That first heartbeat also locks your Allowed Origins to that domain.

- **Custom domain = one 20-second step.** The origin lock happens on the first heartbeat, so a domain added later must be added to your [Allowed Origins](https://cross-deck.com/docs/allowed-origins/index.html) yourself.

- **Connect a rail for revenue.** Connect Stripe (or Apple / Google) so revenue and entitlements join the same identity graph as analytics and errors.

## 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

- 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.

- **Activate** the plugin from the **Plugins** screen. (Activation provisions nothing on its own — connecting is an explicit step.)

### B. Connect — one click

- Go to **Settings → Crossdeck**.

- Choose an **Environment** (Production is the default; a Sandbox option is available) and click **Connect Crossdeck**.

- 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)

- On the settings screen, expand **Advanced: paste keys manually**.

- 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](https://cross-deck.com/docs/allowed-origins/index.html)

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](https://cross-deck.com/docs/how-identity-works/index.html) for the full model.)

## Step 5 — Revenue (connect a payment rail)

To join **revenue** to those people:

- In the Crossdeck dashboard, open **Developers → Rails** (Payment rails).

- Connect **Stripe** (or Apple / Google) in one click — Crossdeck never asks for a raw secret key.

- 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

- **WordPress** (this): install the plugin, then **connect** (one-click OAuth) or paste your **Publishable key** + **App ID**. Identity is **automatic** — the plugin reads the logged-in user server-side and emits `identify()` with no action to wire.

- **Bubble:** paste your **Publishable key** + **App ID** into the plugin. Identity via the **“Crossdeck – Identify user”** workflow action (Bubble exposes Current User to workflows).

- **Webflow:** one-click OAuth marketplace install → account + project auto-created → SDK injected. Identity via a `data-crossdeck-identify-email` binding.

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](https://cross-deck.com/docs/allowed-origins/index.html), fully automatic server-side identity for logged-in users, and revenue on a connected rail (August 4, 2026). Related: [Identify users](https://cross-deck.com/docs/identify-users/index.html), [Connect Stripe](https://cross-deck.com/docs/connect-stripe/index.html).