Skip to main content
platform

Deploy the WordPress plugin

active
Audience: developerUpdated 2026-10-27

The Binoban plugin is one WordPress zip. Upload it, activate it, and its setup wizard connects it to Binoban, confirms how people are identified, and switches it on. It takes about 10 minutes and needs no developer, no theme edit and no code snippet. For what the plugin does once installed, see How the WordPress plugin works.

Before you start​

You needWhy
WordPress 6.0 or later on PHP 7.4 or later (Tools → Site Health → Info)The plugin is built for these versions
An Administrator accountTo install the plugin and open its admin pages
WooCommerce 8.0 or later, if the site is a storeOptional. Without it the store events are greyed out and everything else works
HTTPS from the web server to the Binoban API host, with a trusted certificateWordPress sends server events to Binoban directly from the server
From Binoban: the API host, the Web SDK URL, and two sources, each with a sourceIdentifier and apiKeyA Web source for the visitor's browser and a Server source for WordPress itself. Both are under Data → Data Sources in your Binoban workspace
The WP Consent API plugin, if tracking must wait for consentThe plugin reads consent through it, so it works with any banner built on it

Binoban matches people by userId, anonymousId and device IDs out of the box. To match guests and form leads by phone or email, ask your Binoban team to add phone and email to your workspace's identity strategy before you go live.

Install​

  1. Upload the plugin. Plugins → Add New → Upload Plugin → choose binoban-for-wordpress-<version>.zip → Install Now → Activate. The plugin adds a Binoban menu and opens its setup wizard. Nothing is sent to Binoban until step 5.

  2. Connect. Enter the API host, the Web SDK URL, and the source identifier and API key of both sources, then press Test connection:

    • Server must say Connected. The test sends one connection_tested event to the Server source.
    • Web must say SDK bundle and API host reachable. A Web key can only be checked by a browser, so its first real event is the check (step 5).

    Press Save and continue. The Server key is stored on the server only; the field shows Saved afterwards and is never filled back in.

    Setup wizard, Connect step: the API host, Web SDK URL, the Web and Server sources, and a passing connection test

  3. Identity. Press Scan now. The plugin looks through the user table for phone numbers, emails and names, and lists every field it found with how many users have it. Untick any field that isn't a real identifier, set the default country code used to write phone numbers as E.164, and choose the roles that are never tracked (Administrator and Shop manager by default). Tick the identity-strategy box once your Binoban team has confirmed phone and email matching. Press Save and continue.

    Identity tab: the identifiers found with their user counts, the userId source, the default country code, the roles not tracked, and the identity-strategy check

    To match the IDs a mobile app or CRM already sends, choose A user meta key under userId and type its name, for example a customer code. To send another user field as a trait, type its meta key under Add a custom user meta key.

  4. Events. Every group is on by default. Each event is labelled SDK (sent by the visitor's browser) or API (sent by WordPress). Groups for plugins that aren't active are greyed out. Untick anything you don't want and press Save and continue.

    Events tab: the seven event groups, each event ticked and labelled SDK or API, with the Wishlist group greyed out

    Below the groups, the Page events table lists every kind of page on the site: the home page, each WordPress Page, each post type and template, every archive and the store pages, with the event it fires, such as about_us_viewed or product_category_viewed. A Page whose slug isn't Latin is named after its template or its ID, so give it a readable name: type it in the Event name field. Untick a row to send only the page call for it. Press Save page events.

    Page events table: each page or template with its event name; the blog page switched off and a Persian page renamed about_fa_viewed

  5. Consent. Choose Always on, or Wait for consent if the site has a consent banner that supports the WP Consent API. Press Save and continue.

    Setup wizard, Consent step: Always on or Wait for consent, and what to do with guest orders when consent is missing

  6. Go live. Press Switch on. Binoban starts receiving events from this site. Administrators aren't tracked, so press Open the site in trace mode to watch your own visit arrive (see Check it works).

  7. Optional: backfill. Open the Backfill tab, tick Existing users and Past orders, and press Start backfill. Users become Identify calls and processing or completed orders become order_completed events, each with its original date. Progress shows on the tab, and you can pause and resume.

    Backfill tab: users loading, orders waiting, and the Pause button

The wizard can be run again at any time from the Setup tab. Every value it sets also has its own tab.

Check it works​

On the Trace a visit tab, press Open the site in trace mode. A new tab opens the site with a bnb_trace link. Browse a few pages, open a product and add it to the cart, then come back:

  • Browser events (traced browser) lists what your browser sent: page, the page events such as shop_viewed and product_viewed, element_clicked, cart_viewed and so on, each with the page it came from.
  • Server events lists what WordPress queued. Your product_added is highlighted, and turns sent (200) within a minute.
  • In Binoban, the visit arrives as an anonymous profile. It joins the person's profile, with the userId wp_<user id>, when they sign up or log in.

Trace a visit: the traced browser&#39;s events on the left, and server events on the right with the traced product_added highlighted and sent

A trace ends by itself after 12 hours or 250 events. While it lasts, that one browser is tracked even though you are logged in as an administrator.

The Queue tab lists every server event: Pending (waiting to be sent or retried), Sent (kept 7 days) and Dead-letter (rejected, kept 30 days). Press View on a row to see exactly what was sent. Drain now sends what is due at once, and Export downloads the list as JSON.

Queue tab, Sent: server events with Binoban&#39;s response, and the payload of an order_completed event opened below its row

A dead-letter shows Binoban's error code. Fix the cause, tick the row and press Retry selected.

Queue tab, Dead-letter: two rejected events with Binoban&#39;s error code

The Health tab shows whether sending is on, when the last event was sent, when the queue runner last ran, how many events are waiting, the dead-letters of the last 24 hours, the page cache it found, and the identity-strategy check.

Health tab: sending on, the last event sent, the queue runner&#39;s last run, events waiting, dead-letters and the identity strategy

If it doesn't work​

Start with the Health tab. Anything that blocks sending is marked in red.

SymptomLikely causeFix
Test connection: Server Wrong API key (401) or Unknown source (404)The Server source identifier or key, or the API host, is wrongCopy them again from Data → Data Sources, then test again
Test connection: Web does not serve the SDK bundleThe Web SDK URL is wrongUse the SDK URL shown with your Web source
Test connection: Web API host has no Web SDK endpointThe API host is wrongUse the API host shown with your sources
No browser events from your own visitsAdministrators and Shop managers aren't trackedUse Trace a visit, or test from a private window
No browser events from anyoneTracking is off, the Web SDK URL is empty, or Wait for consent is on and no one has consentedConnection tab: tick Tracking; check the SDK URL; check the consent banner
Browser console shows a CORS error for bobcs.wasm or /api/tracker/sdk/webThe SDK couldn't load its checksum module from the SDK host, so Binoban rejected the batchCheck the Web SDK URL is the one for your deployment. If it is, send the console lines to your Binoban team
Banner Binoban sending is pausedBinoban refused the Server key or source (401/404)Correct the value on the Connection tab, then Test connection; sending resumes and nothing queued is lost
Health: events have waited more than 15 minutesWP-Cron only runs when someone visits the siteAdd a server cron job that requests wp-cron.php every minute
Queue row Dead-letterBinoban rejected that eventRead the error on the row, fix the cause, press Retry selected
Health: New identifier fields foundA login plugin started storing phone numbers in a new fieldIdentity tab: tick or untick the new field, then Save

Update​

Download the newer binoban-for-wordpress-<version>.zip and upload it the same way: Plugins → Add New → Upload Plugin → Replace current with uploaded. Settings, the queue and the backfill state are kept. The version installed is on the Plugins screen and in every event's plugin_version.

Uninstall​

Plugins → Deactivate → Delete. Deleting removes the plugin's settings, its queue table, its scheduled jobs and the flags it stored on orders. Data already sent to Binoban stays there.