Arenza event integration

English | 简体中文

Use this guide to tell Arenza when a visitor does something you want to measure—for example, confirms a booking, submits an enquiry or activates a trial. You choose the trigger; your code sends the event when it happens. The visitor ID links the event to that visitor's website visits.

Choose HTML or JavaScript to report from your website, or Python or Go to report from your backend. Start by getting the credentials below, then copy the example for your language. Report each event through one path, not both. Browser reporting currently records generic interactions; configured server events can use named event types.

1. Prerequisites · 2. Examples · 3. Parameters and responses

1. Prerequisites

Website: installation ID

Open Arenza Portal → AI Integrations, select your brand, and copy Website install ID. It starts with arz_pub_. Replace YOUR_INSTALL_ID below with that value.

This public ID identifies your brand; it is not a secret API key. HTML/JavaScript use it to obtain a short-lived browser session; the SDK sends that session token with track(). It binds requests to a visitor and origin, but does not prove website ownership or business success. Origin restrictions are optional; see browser authentication.

Python / Go: create an API Key

1. Open AI Integrations → Personal Access Tokens.
2. Click New token, enter a name such as Server events, and select Write.
3. Click Create token and copy the arn_pat_… value. It is displayed only once.
4. Save it on your backend as ARENZA_API_KEY. Save your Website install ID as ARENZA_INSTALL_ID.

The examples use these environment variable names. Inject the Key from your server's secret manager; never place it in website code. No separate Signing Secret is needed. The receiver checks Authorization: Bearer <API_KEY>, the Key's write permission and access to the brand.

To replace a Key, create another, update your backend, then revoke the old one in the same token list. Revoked Keys stop working on subsequent requests.

Event setup is separate from Key creation. The selected brand must already have a configured server event connection and allowed event_handle. A measurement-only Website install ID returns 422 server_event_not_configured; creating a Key does not create a billing contract or enable arbitrary event types. Ask Arenza to confirm the supported event for that brand if it is not configured.

Before you start

• Use an HTTPS website. If the integration has a reporting-origin allowlist, your origin must match it. Without that optional restriction, other valid HTTPS origins can also obtain sessions using the public install ID.
• Choose the business condition you want to report. Do not report both a button click and its successful outcome unless you intend two events.

2. Examples

Choose one way to report each event:

HTML | JavaScript | Python | Go

HTML/JavaScript send from the website. Python/Go send from your server; for website attribution, pass the visitor ID using the handoff below.

HTML

Initialize

Replace YOUR_INSTALL_ID, then add this block to your page through your site's analytics-consent integration. The first tag loads and initializes the SDK; the second lets your event code wait until it is ready.

HTML

<script src="https://arenza.ai/sdk/v1.js"
        data-arenza-install-id="YOUR_INSTALL_ID"></script>
<script>
  window.arenzaReady = window.arenzaEvents.init()
    .then(() => window.arenzaEvents);
  window.arenzaReady.catch(() => {
    console.warn('Arenza initialization failed.');
  });
</script>

Send an event

For example, to report a completed booking: find the code that handles a successful response from your booking API, and add the following code there. Do not add it to the error handler.

JavaScript (browser)

// Your code has confirmed the booking (or another event you chose).
void window.arenzaReady
  .then((client) => client.track())
  .catch(() => console.warn('Arenza event could not be sent.'));
// Continue your normal workflow.

JavaScript

Initialize

Load https://arenza.ai/sdk/v1.js using a script tag without data-arenza-install-id, then run this once after it loads and after analytics consent.

JavaScript (browser)

// ArenzaBilling is provided by the loaded SDK.
window.arenzaEvents = window.ArenzaBilling.create({
  endpoint: 'https://api.arenza.ai/api/v1/events/collect/YOUR_INSTALL_ID',
  consent: true,
});
window.arenzaReady = (async () => {
  await window.arenzaEvents.init();
  return window.arenzaEvents;
})();
window.arenzaReady.catch(() => console.warn('Arenza initialization failed.'));

Initialization records a page visit and prepares sending credentials. It does not send your business event. The SDK supplies the visitor ID, request IDs and authentication.

Send an event

For example, to report a completed booking: find the code that handles a successful response from your booking API, and add the following code there. Do not add it to the error handler.

JavaScript (browser)

// Your code has confirmed the booking (or another event you chose).
void window.arenzaReady
  .then((client) => client.track())
  .catch(() => console.warn('Arenza event could not be sent.'));
// Continue your normal workflow.

Python

Use ARENZA_API_KEY and ARENZA_INSTALL_ID from Prerequisites. Supply the event object and a saved delivery UUID. No browser session token is needed.

Copy the HTTP helper into your project as arenza_events.py. Then call it from your event handler:

from arenza_events import send_event

# event: saved event object from Server event fields below.
# delivery_id: your saved delivery UUID (generate once, not on each retry).
receipt = send_event(event, delivery_id)
# Save receipt["receipt_id"] with your delivery record.

Go

Use ARENZA_API_KEY and ARENZA_INSTALL_ID from Prerequisites. Supply the event object and a saved delivery UUID. No browser session token is needed.

Copy the HTTP helper into your Go module's arenza package (Go 1.18+). Import that package in your handler:

// event: saved event map from Server event fields below.
// deliveryID: saved delivery UUID. ctx: your worker's context.
receipt, err := arenza.SendEvent(ctx, event, deliveryID)
if err != nil {
    return err // Let your worker apply its retry/error policy.
}
// Save receipt.ReceiptID with your delivery record.

3. Parameters and responses

When to send

You decide when to execute that snippet:

Current limit: browser track() does not support named event types. These are possible trigger locations, not distinct event names in Arenza reports. track('booking_confirmed') is unsupported. Choose one reporting path per occurrence: SDK, raw HTTP or server webhook.

Visitor ID handoff

After installing the HTML or JavaScript example, read the visitor ID:

JavaScript (browser)

const visitorId = window.arenzaEvents.getVisitorId();

Add that value as arenza_visitor_id to your existing request to your own backend. Your backend should save it with the relevant business record so an asynchronous worker can use it later. The getter sends no event. Do not also call browser track() for the same server-reported event.

Server event fields

Use this endpoint:

POST https://api.arenza.ai/api/v1/billing-events/{website_install_id}

With API Key authentication, the arz_pub_… Website install ID is an alias for your brand's configured connection. Existing connection UUIDs also remain valid; do not put the API Key in the URL.

Required headers: Authorization: Bearer <API_KEY>, Content-Type: application/json, and webhook-id: <delivery UUID>. No HMAC signature or timestamp is required on this path.

In the Arenza request, put that same ID under attribution.visitor_id, not a top-level arenza_visitor_id:

JSON — example test event; replace values with your business record

{
  "spec_version": "1.0",
  "event_id": "booking-event-123",
  "event_handle": "YOUR_CONFIGURED_EVENT_HANDLE",
  "occurred_at": "2026-09-24T12:00:00Z",
  "subject": { "type": "booking", "id": "booking-123" },
  "attribution": { "visitor_id": "arz_v_aaaaaaaaaaaa" },
  "status": "test"
}

Responses and errors

HTML / JavaScript: trigger an approved test once, then check DevTools → Network for one /events request returning 202. This means received, not independent proof of the business outcome.

Python / Go:

A successful request returns 202:

{
  "accepted": true,
  "receipt_id": "<receipt ID>",
  "duplicate": false,
  "status_url": "/api/v1/billing-events/<connection ID>/receipts/<receipt ID>"
}

202 means queued, not that attribution, reporting or billing has completed. Save the receipt for processing checks.

• 401: the API Key is missing, invalid or revoked.
• 403 insufficient_scope: create a Key with Write permission.
• 404: the connection is unavailable or the Key has no access to its brand.
• 422 server_event_not_configured: this installation has no configured server event binding.
• 422 event_handle_not_allowed: the event type is not configured for this connection.
• 409: an event/delivery ID may have been reused with a changed body.
• Network failures or 5xx: retry through your worker using the same IDs and unchanged event; do not generate a new event ID or delivery ID for the retry. Avoid unbounded immediate retries.

Test only against an approved connection. The examples do not send until you call the function.

Browser SDK methods

Existing preconfigured connections

An existing pre-bound integration can accept just {"arenza_visitor_id":"arz_v_…"} at /api/v1/billing-events/{website_install_id}/preconfigured, with the same Bearer, content-type and webhook-id headers. It only supports its preconfigured event binding. Do not use that minimal body on the general endpoint above, and do not assume it supports arbitrary event types.

HTTP / curl reference · JSON Schema · Stopping collection

Existing HMAC-signed integrations continue to work with their connection UUID and signature headers. API Key callers do not need to obtain or rotate those signing secrets.

Production verification: 2026-09-24 — tested paths, deployed version, authentication checks and limits of the evidence.