#Modules for Websites

Status: Available: Bitrix sapport.connector 1.2.1 and WordPress sapport-connector-wp 1.1.1. Beta: FastAPI sapport-connector 1.0.0 and Nuxt @sapport/nuxt-connector 1.0.0. The packages are ready, but the dashboard marks them "coming soon" (not published).

Purpose: connect a site built on a CMS or framework to Walker Formulation Academy with a single module: visit counter, server beacon (visible to bots and AI crawlers), chat, behavior tracking, and publishing of articles from Walker Formulation Academy.

#Contents

1. When to use it
2. Common to all modules
3. Bitrix
4. WordPress
5. FastAPI
6. Nuxt
7. Connector protocol for custom modules
8. Open questions

#When to use it

#Common to all modules

#Access

#What the module does

#How to bind a site: the binding code

1. In the dashboard: "Promotion → System → Sites (module)" → add the domain → get a binding code.
2. The code carries the cell prefix: RU-…, EN-…, or ID-…. It lives for 15 minutes and is single-use. A code from another cell gives the error "code not found".
3. Enter the code in the module. The module exchanges it for site_id, a public key, a secret, and a beacon key (the secret is returned once).
4. If the code has expired or been used, click "New code". "Disconnect" unbinds the site on the cloud side.

Site states in the dashboard: pending (code issued, not yet bound), bound, disabled.

Binding accepts only the registered domain. A domain alias or another host gives the error domain_mismatch (on binding) or 400 (on the server beacon); www. is supported if the module accounts for it.

#Download

Archives and SHA-256 checksums are in the dashboard: "Settings → Integrations → Modules for websites". Verify the checksum before installing.

Files are served from your cell's domain (RU https://formula-cream.pro, EN https://wfacademy.org, ID https://wfacademy.id).

#Server beacon modes

#Bitrix: sapport.connector 1.2.1

Status: Available.

#Requirements

#Installation

1. Unpack the archive into /local/modules/.
2. In the admin area, open "Marketplace → Installed solutions" (/bitrix/admin/partner_modules.php) and click "Install" next to "Sapport: connector".
3. Get a binding code in the Walker Formulation Academy dashboard (see above).
4. "Settings → Product settings → Module settings → Sapport: connector" → enter the code → "Bind".
5. Click "Check connection".

Recommendations:

• Run Bitrix agents from cron (otherwise the heartbeat and the publisher lag).
• If the site runs behind a proxy and passes X-Forwarded-For, tick "Site runs behind a proxy"; otherwise the visitor's IP will be replaced with the proxy's address.

#What the module does

#Settings

Which parts are on (tracker, behaviour, chat, the consent mode, the beacon mode) is set in the dashboard.

#Verification

1. The "Check connection" button → success.
2. In the dashboard, the site state is bound.
3. After a visit from an ordinary browser, the counter in Overview grows; a bot hit can be checked with curl -A "Googlebot" https://your-site/.
4. The page outputs the loader.js?k=… tag in <head>.

#Update and removal

• Update: replace the module folder contents with the new version; rebinding is not needed. If the cloud answers update_required (unknown_kid or kid_wrong_cell), update the module: it does not know the job signing key.
• Removal: Marketplace → "Delete". Unbind the site beforehand ("Disconnect" in the dashboard), otherwise the binding stays on the cloud side.

#Common problems

#Security

The binding secret is stored in the b_option table in clear text, so database backups contain it. The secret can be reissued only by unbinding and binding again.

#WordPress: sapport-connector-wp 1.1.1

Status: Available.

#Requirements

#Installation

1. "Plugins → Add New → Upload Plugin", choose the zip, click "Install" and "Activate".
2. "Settings → Walker Formulation Academy".
3. Paste the binding code → "Connect".
4. Click "Check connection".

#What the plugin does

#Specifics

#Verification, update, removal

• Verification: "Check connection" → success; the dashboard state is bound; loader.js?k=… is present in <head>.
• Update: upload the new zip over the old one (there is no auto-update).
• Removal: first "Disconnect" in the dashboard, then deactivate and delete the plugin.

#Common problems

#FastAPI: sapport-connector 1.0.0 (Beta)

Status: Beta. The package is built and documented, but the dashboard marks it "coming soon / Package in preparation"; there are no files on the download page yet.

#Requirements

Python 3.11 or later, PostgreSQL (the same database that holds the site's articles), outbound HTTPS to the cell's domain. The module opens no inbound addresses for the cloud.

#Installation and binding

# 1. Verify the checksum of the file from the dashboard
sha256sum sapport_connector-1.0.0-py3-none-any.whl

# 2. Install
pip install "./sapport_connector-1.0.0-py3-none-any.whl[postgres]"

# 3. Create the module's tables
sapport-connector migrate

# 4. Bind the domain with the code from the dashboard
SAPPORT_SITE__RU_MAIN__HOST=example.ru \
sapport-connector bind --site ru_main --code RU-XXXXXXXXXX \
  --secret-file /run/secrets/sapport_ru_main --env-file /etc/sapport/sapport.env

# 5. Self-check: all lines show [OK]
sapport-connector selftest

# 6. Start the worker (systemd/supervisor) or cron: sapport-connector run-once
sapport-connector worker

CLI commands: bind, migrate, selftest, run-once, status, worker, unbind (irreversible). The name on PyPI is taken by a placeholder; install only the archive from the dashboard.

#Environment variables

The secret is written to a file, not to an environment variable. The full list and the article adapter contract are in the package documentation (README, INTEGRATION, ADAPTER, PROTOCOL, ERRORS, ACCEPTANCE, SECURITY, CSP, OPERATIONS, COMPATIBILITY, TROUBLESHOOTING).

#What you need to write

The publisher requires an adapter for your articles table (contract: ADAPTER), and covers require a media storage class on storage shared between replicas. Without media storage, articles are published without a cover. While the publisher is off, the module only maintains the connection and the heartbeat.

#Verification

sapport-connector status and selftest; the site is bound in the dashboard. For detailed diagnostics of the web process, mount healthz_router() and close the address on the reverse proxy.

#Nuxt: @sapport/nuxt-connector 1.0.0 (Beta)

Status: Beta. The package is not published.

The Nuxt part works together with the Python worker: the worker binds the site, and Nuxt receives only a derived beacon key. That key cannot be used to fetch jobs or unbind the site.

#Requirements

Nuxt 3.13+ or 4.x in Node server mode (Nitro 2, Node 18.17+; for Nuxt 4, Node 20+). Nuxt 5 is not supported.

#Installation

sha256sum sapport-nuxt-connector-1.0.0.tgz
npm install ./sapport-nuxt-connector-1.0.0.tgz

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@sapport/nuxt-connector'],
  sapport: {
    exclude: ['/admin'],
    trustedProxies: ['127.0.0.1'],
  },
});

The key is not written to nuxt.config. Environment variables of the Nuxt server:

SAPPORT_SITES=ru_main
SAPPORT_SITE__RU_MAIN__HOST=example.ru
SAPPORT_SITE__RU_MAIN__CELL=ru
SAPPORT_SITE__RU_MAIN__ID=<site_id>
SAPPORT_SITE__RU_MAIN__BEACON_KEY_FILE=/run/secrets/beacon/sapport_ru_main.beacon
NUXT_SAPPORT_DIAGNOSTICS_TOKEN=<a random string of at least 16 characters>

Run the worker and Nuxt under different OS users: the root secret file must not be readable by the Nuxt process.

#Usage in pages

<script setup lang="ts">
useSapportPage({ type: 'article', id: article.id });
const consent = useSapportConsent();
</script>
<template>
  <button @click="consent.grant()">Accept</button>
  <button @click="consent.deny()">Decline</button>
</template>

#Diagnostics

curl -s -H "Authorization: Bearer $NUXT_SAPPORT_DIAGNOSTICS_TOKEN" https://your-site/_sapport/health

Expect "ok": true, config.state: "valid" on the binding, and beacon.sent ≥ 1 after the first view.

#Limitations

#Connector protocol for custom modules

Status: Available for modules that you write yourself. The protocol is used by the four ready-made modules; its list of methods may be extended compatibly.

Address: https://<cell domain>/api/v1/connector/…. All requests except bind are signed with HMAC.

#Request signature

Headers:

String to sign (five lines joined by \n):

<ts>
<nonce>
<METHOD>
<path without the query string>
<sha256hex(request body)>

• The permitted clock skew is ±300 seconds.
• A nonce is stored for 600 seconds; a repeat gives 401. If the nonce store is unavailable, the response is 503.
• The HMAC key is the root binding secret. For track/visit and beacon-config, a derived beacon key is allowed:

beacon_key = hex(HMAC-SHA256(secret, "sapport-beacon-v1:" + site_id))

Test vectors for signatures and jobs are shipped with the modules (tests/_vectors/, files signing-vectors.json and job-vectors.json). Do not copy secrets from documentation examples into working systems.

#Methods

#bind

POST /api/v1/connector/bind
Content-Type: application/json

{
  "code": "RU-XXXXXXXXXX",
  "site_url": "https://example.ru",
  "cms": "fastapi_nuxt",
  "module_version": "1.0.0"
}

Response 200:

{
  "site_id": "00000000-0000-4000-8000-000000000000",
  "public_key": "0123456789abcdef0123456789abcdef",
  "secret": "EXAMPLE_SECRET_SHOWN_ONCE",
  "beacon_key": "0000000000000000000000000000000000000000000000000000000000000000",
  "api_base": "https://formula-cream.pro/api/v1",
  "loader_url": "https://formula-cream.pro/api/v1/connector/loader.js?k=0123456789abcdef0123456789abcdef",
  "config": { "tracker": true, "behaviour": false, "chat": false, "consent_mode": "wait", "server_beacon": "full" },
  "disabled": false
}

secret is returned once. Errors: 400/413 bad_request, 404 code_not_found (the code is unknown, expired, used, or belongs to another cell), 409 domain_mismatch, 429 rate_limited, 500 internal.

#heartbeat

Response 200: { "config": {…}, "min_module_version": "1.2.1", "disabled": false, "pending_jobs": 0 }. A 403 response with { "disabled": true } means the site is disabled.

#beacon-config

{
  "tracker": true,
  "server_beacon": "full",
  "disabled": false,
  "consent_mode": "wait",
  "loader_url": "https://formula-cream.pro/api/v1/connector/loader.js?k=0123456789abcdef0123456789abcdef",
  "public_key": "0123456789abcdef0123456789abcdef",
  "ttl_seconds": 3600
}

Cache the snapshot for ttl_seconds.

#track/visit (server hit)

The body fields are described on the JS/PHP tracker page. Specifics of the signed call:

• The hit's host is taken from the binding registry. If it does not match the registered domain, the response is 400.
• server_beacon=off, a disabled tracker, or a tenant without access give 403.
• anonymous mode nulls the IP and User-Agent hashes, the UA sample, and the country.
• The token's daily quota gives 204 without recording.

#jobs and result

Jobs are signed with Ed25519 (the kid field with a cell prefix ru-/en-/id-, canonical JSON with keys sorted in UTF-16 order). The response to GET /jobs is not idempotent: a job that was issued but not confirmed is issued again after 15 minutes. The error 503 signing_unavailable means job signing is temporarily unavailable.

result accepts the status applied, skipped, conflict, or failed. The first outcome submitted is final.

Article limits are the same for the cloud and the modules: HTML up to 2,000,000 bytes, job payload up to 3,000,000 bytes. See Articles for details.

#Recommendations for a custom module

• Sign the body with exactly the bytes you send.
• Treat a server hit as statistics: do not retry on error, and do not block the page response (a reasonable timeout is 150–200 ms).
• Do not give the root secret to the frontend: the derived key is enough for the beacon.

#Open questions

1. Technical. FastAPI and Nuxt: the actual presence of files in the distribution directory has not been verified; the dashboard marks the module "coming soon". Until the packages are published, the pages remain Beta.
2. Technical. Bitrix module, anonymous mode: WordPress nulls the query string on its own side, while in full mode the cloud reads UTM from the query. A single rule for all modules needs to be decided.
3. For the owner. The cms value for custom modules: only bitrix, wordpress, and fastapi_nuxt are allowed. How to register a module for another platform is not defined.
4. Technical. Settings path in Bitrix: the module README names the dashboard section "site connections" without a path; here the path from the interface, "Promotion → System → Sites (module)", is used.