Physical World Analytics API

Integrate real-time audience & emotion analytics into your app.

Instant AI Setup

Use this to instantly prompt the AI

Paste the Booya SDK GitHub URL into your vibe coding platform and the AI will set everything up for you.

Copy the SDK GitHub URL

Simply paste this URL into your vibe coding platform (Cursor, Lovable, v0, Bolt, etc.) and the AI will read the SDK docs and integrate Booya automatically.

url

https://github.com/booya-ai/booya-sdk

Provide your App ID & API Key when prompted

The AI will ask for your App ID and API Key. You can get both from the API Keys page on this dashboard.

You're live!

The AI will handle installation, initialization, and wiring up the emotion analytics — no manual setup required.

Getting Started

Get an API Key

Go to API Keys in your dashboard and create a new key.

Install the SDK

bash

npm install booya-sdk

Initialize & Start

javascript

import { BooyaSDK } from 'booya-sdk';

const booya = new BooyaSDK({
  apiKey: 'bya_your_key_here',
  appId: '696c3f16411b3004620a0942',
  cdnBase: 'https://pub-8a8663514dfc4903b92d92bad4ead7b1.r2.dev',
});

await booya.init('#camera-container');

booya.onMetrics(metrics => {
  console.log('Viewers:', metrics.viewerCount);
  console.log('Emotions:', metrics.emotions);
});

const sessionId = await booya.startSession();
// ... when done:
const summary = await booya.endSession();

SDK Reference

Constructor

javascript

new BooyaSDK({
  apiKey: string,          // Required. Your API key
  appId: string,           // Required. Your Base44 app ID
  skin: string,            // 'default' | 'minimal' | 'none'. Default: 'default'
  dashboardId: string,     // Optional. Zone/dashboard ID to associate sessions
  serverUrl: string,       // Optional. Base44 server URL. Default: 'https://base44.app'
  cdnBase: string,         // Optional. CDN URL for WASM assets
  metricsInterval: number, // Metrics update interval in ms. Default: 200
  eventInterval: number,   // Event logging interval in ms. Default: 2000
  customCss: string,       // Optional. Custom CSS injected into container
  onMetrics: function,     // Optional. Metrics callback
  onError: function        // Optional. Error callback
})

Methods

init(container)→ Promise<void>

Initialize SDK. Pass a CSS selector or DOM element. Loads WASM engine.

startSession()→ Promise<string> (session_id)

Start camera, begin processing, create a session via API.

endSession()→ Promise<Object> (session summary)

Stop processing, close camera, end session via API.

onMetrics(callback)→ void

onError(callback)→ void

getMetrics()→ Object | null

Get the latest metrics snapshot synchronously.

destroy()→ void

Clean up all resources, remove DOM elements.

Metrics Object

javascript

{
  viewerCount: number,      // Current number of detected faces
  totalPersons: number,     // Total unique persons detected
  engagementScore: number,  // 0-100 engagement percentage
  avgLookTimeSec: number,   // Average gaze duration in seconds
  emotions: {
    happy: number,          // Seconds of each emotion detected
    surprised: number,
    angry: number,
    sad: number,
    disgust: number,
    neutral: number
  }
}

Static API Helpers

Use these without initializing the WASM engine — pure REST wrappers:

javascript

const API_KEY = 'bya_your_key_here';
const APP_ID = '696c3f16411b3004620a0942';

// List sessions
const sessions = await BooyaSDK.api.getSessions(API_KEY, APP_ID, {
  dashboardId: 'optional',
  limit: 50,
  offset: 0
});

// Get single session with events
const detail = await BooyaSDK.api.getSession(API_KEY, APP_ID, 'session_id');

// Get aggregated analytics
const analytics = await BooyaSDK.api.getAnalytics(API_KEY, APP_ID, {
  startDate: '2026-01-01',
  endDate: '2026-03-01',
  dashboardId: 'optional'
});

REST API

Base URL: https://base44.app/api/apps/696c3f16411b3004620a0942/functions

All endpoints require an X-API-Key header. Responses are JSON with a success boolean and data or error field. Rate limits apply based on your subscription plan (429 status when exceeded).

POST/functions/apiCreateSession

Start a new measurement session.

Request Body

json

{
  "dashboard_id": "optional-zone-id",
  "metadata": { "source": "my-app" }
}

Response

json

{
  "success": true,
  "data": {
    "session_id": "abc123",
    "start_time": "2026-03-04T...",
    "status": "active"
  }
}

POST/functions/apiEndSession

End an active session.

Request Body

json

{ "session_id": "abc123" }

Response

json

{
  "success": true,
  "data": {
    "session_id": "abc123",
    "end_time": "2026-03-04T...",
    "duration_seconds": 120,
    "status": "completed"
  }
}

POST/functions/apiLogEvent

Log an emotion/metrics event to a session.

Request Body

json

{
  "session_id": "abc123",
  "emotions": { "happy": 0.8, "neutral": 0.2 },
  "viewer_count": 3,
  "attention_score": 85,
  "timestamp": "2026-03-04T..."
}

Response

json

{
  "success": true,
  "data": { "event_id": "evt_456" }
}

POST/functions/apiGetSessions

List sessions. Query params: dashboard_id, limit, offset.

Response

json

{
  "success": true,
  "data": [
    {
      "id": "abc123",
      "start_time": "...",
      "end_time": "...",
      "duration_seconds": 120,
      "status": "completed",
      "source": "sdk"
    }
  ],
  "pagination": { "total": 42, "limit": 50, "offset": 0 }
}

POST/functions/apiGetSession

Get a single session with all events and computed analytics.

Request Body

json

{ "session_id": "abc123" }

Response

json

{
  "success": true,
  "data": {
    "session": { "id": "abc123", "start_time": "...", ... },
    "analytics": {
      "dominant_emotion": "happy",
      "average_viewer_count": 2.5,
      "average_attention_score": 78,
      "total_events": 60
    },
    "events": [ { "id": "...", "timestamp": "...", "emotions": {...} } ]
  }
}

POST/functions/apiGetAnalytics

Get aggregated analytics. Query params: dashboard_id, start_date, end_date.

Response

json

{
  "success": true,
  "data": {
    "sessions": { "total": 100, "completed": 95, ... },
    "emotions": { "dominant": "happy", "breakdown": [...] },
    "audience": { "average_viewer_count": 3.2, "average_attention_score": 72 }
  }
}

Skin System

Built-in Presets

'default'

Glass-morphism panel with blur backdrop, full metrics display

'minimal'

Text-only overlay with drop shadow, compact layout

'none'

No overlay — use onMetrics callback to build your own UI

Custom CSS

javascript

const booya = new BooyaSDK({
  apiKey: 'bya_...',
  skin: 'default',
  customCss: `
    .booya-metrics-overlay {
      background: rgba(99, 102, 241, 0.9) !important;
      border-radius: 20px !important;
      font-family: 'Your Brand Font', sans-serif !important;
    }
  `
});

Standalone Stylesheet

Include booya-skins.css for class-based skin control:

html

<link rel="stylesheet" href="/booya-skins.css" />
<div id="camera" class="booya-skin-default">
  <!-- SDK renders here -->
</div>

Code Examples

html

<!DOCTYPE html>
<html>
<head>
  <title>Booya Quick Start</title>
  <script src="https://pub-8a8663514dfc4903b92d92bad4ead7b1.r2.dev/booya-sdk.js"></script>
  <style>
    #camera { width: 640px; height: 480px; border-radius: 12px; overflow: hidden; }
  </style>
</head>
<body>
  <div id="camera"></div>
  <button id="start">Start</button>
  <button id="stop">Stop</button>

  <script>
    const booya = new BooyaSDK({
      apiKey: 'bya_your_key_here',
      appId: '696c3f16411b3004620a0942',
      cdnBase: 'https://pub-8a8663514dfc4903b92d92bad4ead7b1.r2.dev',
      skin: 'default'
    });

    booya.init('#camera').then(() => {
      document.getElementById('start').onclick = () => booya.startSession();
      document.getElementById('stop').onclick = () => booya.endSession();
    });
  </script>
</body>
</html>

Rate Limits

API access is rate-limited based on your subscription plan. Limits reset daily at midnight UTC. When limits are exceeded, endpoints return HTTP 429.

Plan	Daily Requests	Daily Sessions
Unsubscribed	100	10
Subscribed (Monthly / Yearly)	10,000	1,000

Check your current usage on the API Keys page.