Skip to documentation
PoolstatisDocs
Integrations

Bitrix integration

Poolstatis can instrument a classic Bitrix site, an AJAX-heavy Bitrix application, or a Bitrix-managed landing. The Browser SDK runs in the rendered site; MCP runs in the developer agent that edits and audits the project. Do not put an MCP process or an MCP token inside Bitrix.

1. Prepare the project

Create the project in Poolstatis Cloud or self-host, then copy its API URL and write-only pk_ ingest key from Setup. Never put an sk_ or pt_ token in a template, browser bundle, Tag Manager, Bitrix option visible to the browser, or repository.

Connect the developer's MCP client with the version-pinned @poolstatis/mcp@0.7.0 runner. MCP uses the pt_ or project-scoped sk_ token in the agent host's private environment. MCP runs in the developer agent, not inside Bitrix. No GitHub App is required: the agent can work with a local checkout, SSH/SFTP workspace, or any other deployment workflow the team already uses.

Install the exact public Browser SDK before building the site's own bundle:

pnpm add @poolstatis/sdk@0.4.0

Do not load an unversioned registry or CDN URL at runtime.

2. Add the browser bundle

Bundle the SDK import with the site's normal JavaScript build and upload the output as, for example, /local/js/poolstatis-browser.js. A classic template can register it in /local/templates/<template>/header.php:

<?php
use Bitrix\Main\Page\Asset;

Asset::getInstance()->addJs('/local/js/poolstatis-browser.js');

Tag Manager and template loading

The same self-hosted bundle can be loaded by a Bitrix custom module or by a Tag Manager custom HTML tag. Do not load analytics from an unversioned third-party URL. Keep endpoint, project, environment, route vocabulary, and release id in a small non-secret configuration object; keep the pk_ key project- and environment-specific.

The bundle starts Browser analytics immediately:

import { createClient } from '@poolstatis/sdk';
import { createBrowserAnalytics } from '@poolstatis/sdk/browser';

const client = createClient({
  url: window.poolstatisConfig.url,
  ingestKey: window.poolstatisConfig.ingestKey, // pk_ write-only
});

const analytics = createBrowserAnalytics({
  client,
  captureAcquisition: true,
  mapPagePath: (pathname) => {
    if (pathname === '/') return '/home';
    if (pathname.startsWith('/catalog/')) return '/catalog/:section';
    if (pathname === '/order/') return '/order';
    return '/other';
  },
});

analytics.start();

Poolstatis does not add a consent gate. The Bitrix site owner remains responsible for any notice, consent, pause, or deletion behavior required by its own product policy.

3. Handle Bitrix navigation

  • On classic full-page navigation, load the bundle once per document. The SDK records the bounded canonical page after it starts.
  • History API pushState, replaceState, back, and forward navigation are observed by the Browser module.
  • If a Bitrix component swaps content with custom AJAX but does not update browser history, update the application's canonical route state and call analytics.pageViewed() once after the navigation completes. Do not call it on every component render.

Use a finite mapPagePath vocabulary. Never send a full URL, query string, search text, order id, account slug, email, form value, page text, or arbitrary user-controlled path.

4. Add click and scroll evidence

Register the Bitrix surface and canonical routes through MCP, mark only meaningful controls with data-poolstatis-label, and mark named sections with data-poolstatis-section. Start BrowserExperience with the page analytics runtime. Give each deploy a stable version from the deployment process or a <meta name="poolstatis-release" content="..."> value; the SDK receives that value explicitly. This works without GitHub.

Click and scroll overlays require an exact screenshot tuple for surface, route, version, device, and environment. Without that snapshot, the normalized grid is only a layout-agnostic fallback. See Browser Experience for the labelled capture contract, Session Replay for the separate consented DOM recorder, and MCP reference for the bounded agent tools.

5. Accept the integration

The developer agent performs the proof; Bitrix sends the product evidence:

list_projects()
get_onboarding_status(project, { env: "prod" })
sample_events(project, { event: "page.viewed", registered: true, limit: 20 })
query_trend(project, {
  metric: "web_page_views",
  date_from: "-7d",
  interval: "day",
  env: "prod"
})
get_onboarding_status(project, { env: "prod" })

Do not accept the integration from a network request alone. Confirm one real browser visit, one accepted stored page.viewed, the expected bounded route and session context, an active purpose-first metric, a typed query result, and no rejected or privacy-unsafe properties.