Web SDK Integration Guide

GoWind UBA's Web data collection SDK (@go-wind-uba/uba-sdk) is for browser / Node environments, reporting user behavior and risk events to the Collector service.

Applies to: event tracking on web pages. For game / Unity / Godot clients, use the C# SDK. Source code: frontend/sdk/web/uba/.

1. Capability Overview

• Application-level authentication: appId + appSecret in the request body, no token needed.
• Batch reporting: local buffering, automatic flush by timer / count.
• High-level API: track / trackRisk / identify / setSuperProperties / flush.
• Auto completion: device / session / time / platform information.
• Retry and degradation: exponential backoff, no retry on 401, overflow dropped to limit memory.
• Unload fallback: pagehide / beforeunload fall back to sendBeacon.

2. Installation & Build

cd frontend/sdk/web/uba
npm install      # install typescript
npm run build    # build dist/

3. Initialization & Reporting

import { UbaClient } from '@go-wind-uba/uba-sdk';

// Initialize (singleton; appId/appSecret are obtained after creating an app in the admin console's "App Management")
const uba = UbaClient.init({
  appId: 'your_app_id',
  appSecret: 'your_app_secret',
  endpoint: 'http://localhost:5700', // collector service address
});

// Set super properties (every subsequent event carries them automatically)
uba.setSuperProperties({ platform: 'web', version: '1.0.0' });

// Behavior event (most common)
uba.track('click', { button: 'buy' }, {
  objectType: 'button',
  objectId: 'btn_buy',
});

// Risk event
uba.trackRisk('abnormal_click', {
  riskType: 'device_anomaly',
  riskLevel: 'HIGH',
  riskScore: 85,
  description: '短时间内频繁点击，疑似机器操作',
});

// Bind the logged-in user (subsequent events automatically carry userId)
uba.identify(1001);

// Key conversion point, report immediately
uba.track('purchase', { orderId: 'ORD-001' });
await uba.flush();

4. Configuration Options

5. API Overview (UbaClient)

6. Auto-Completed Fields & Auto Collection

SDK auto-completed fields (carried by every event)

Auto-collected events (autotrack)

With autoTrack enabled (default true), the SDK listens for click during the document capture phase and automatically reports a behavior event named click, filling in heatmap fields:

⚠️ Currently autotrack only collects click; there is no PV / pageView auto collection and no route listening. For page view event tracking, call track('page_view', ...) yourself.

7. Reporting Protocol Contract

Integrates with the collector's unified interface POST /uba/v1/report.

Authentication

• appId + appSecret go in the request body (not headers); no Authorization token.
• Authentication failure returns 401, and the SDK does not retry (to avoid endlessly spamming failed requests).

Request Body Structure

{
  "appId": "your_app_id",
  "appSecret": "your_app_secret",
  "clientInfo": { "userAgent": "...", "referer": "..." },
  "events": [
    {
      "eventId": "uuid",
      "eventName": "click",
      "eventTime": "RFC3339",
      "deviceId": "...",
      "sessionId": "...",
      "platform": "web",
      "userId": 1001,
      "properties": { "button": "buy" },
      "behavior": { "objectType": "button", "objectId": "btn_buy" }
    }
  ]
}

Response Conventions

• HTTP 200 may still contain partial failures: when the response body has failedCount > 0 or a non-empty errorsByType, the SDK logs a warning.
• Error codes: 400 validation failure, 401 authentication failure (no retry), 500 server error (retry).
• Field naming is always camelCase (aligned with the backend proto contract). tenantId is not reported; the server authoritatively overrides it based on appId.

For the complete set of event fields, see Backend API Contract · Report Service.

8. Integration & Troubleshooting

# Start the local collector (listens on 5700 by default)
cd backend
go run ./app/collector/service/cmd/server/ -c ./app/collector/service/configs

1. cd frontend/sdk/web/uba && npm run build to generate dist/.
2. Modify appId / appSecret / endpoint in test.html.
3. Open it in the browser, click buttons to trigger reporting, and watch the Network panel and Console.

Common Issues

9. Advanced Usage

Super properties

Suitable for fields needed by every event, such as appVersion / channel / channel ID:

uba.setSuperProperties({ appVersion: '1.2.0', channel: 'appstore' });
uba.clearSuperProperties();

Timed events (manually measuring durations)

const t0 = Date.now();
// ... user actions ...
uba.track('level_play', { level: '1-1' }, { durationMs: Date.now() - t0 });

Batching & throttling tuning

10. Related Documentation

• Product Introduction
• C# SDK Integration
• Backend API Contract · Report Service
• System Architecture