How the marketplace is put together

1. Platform structure

Each request travels the same path as a media buy: inventory → creative → approval → payment → scheduling → playback → proof → settlement.

2. Data model

An advertising opportunity is structured inventory, never a free-text listing. Six tables carry the transaction.

Inventory record (location × device)

3. API surface

One REST surface for the portals, the device players and future DSP/SSP connections. Booking is a single idempotent call so a retried payment can never double-book a loop.

Booking request

POST /v1/bookings
{
  "advertiser_id": "adv_10231",
  "campaign": { "objective": "coupon", "start": "2026-10-01", "days": 14 },
  "lines": [
    { "location_id": "LC-1042", "device_ids": ["DV-1042-A"], "sov": 50 },
    { "location_id": "LC-5104", "device_ids": ["DV-5104-A"], "sov": 50 }
  ],
  "creative": { "asset_id": "as_9f21", "form": "hologram", "languages": ["zh-HK", "en"] },
  "ai_studio": { "enabled": true, "hologram_conversion": true },
  "payment": { "provider": "stripe", "method": "card" },
  "idempotency_key": "bk_8f2c1a"
}
→ 201 { "booking_id": "BK-7F21", "status": "in_review",
        "total": 11900, "approvals": ["AP-3001"], "invoice": "INV-2026-1042" }

Proof of play is exposed per device and per campaign, with a signed export for agencies, and the DOOH fields map onto the OpenRTB DOOH representation when the platform is ready for programmatic buyers.

4. The AI creative service (DeepSeek)

The studio is a thin orchestration layer over a hosted LLM plus an image/video pipeline. In this build the studio runs in demo mode by default; switch LG_CONFIG.ai.mode to proxy and run the bundled server to use a real DeepSeek API key.

Getting a DeepSeek API key

1. Register at the DeepSeek platform

   Create an account at platform.deepseek.com (the API platform, not the chat app). Sign in with email or phone.

2. Verify and open the API keys page

   Complete any identity checks the platform requests, then create a key under API keys. Copy it once — it is shown in full only at creation.

3. Top up the balance — yes, the API is paid

   The API is pay-as-you-go against a prepaid balance. Usage is deducted from the topped-up balance, and from any granted promotional balance first when both exist. There is no permanently free production tier, so budget a small top-up to test.

4. Call the API

   OpenAI-compatible base URL api.deepseek.com; Anthropic-format base URL api.deepseek.com/anthropic. Keep the key server-side.

5. Watch spend, prefer off-peak

   Off-peak rates are half of peak rates. Peak hours are 01:00–04:00 and 06:00–10:00 UTC, Monday to Friday, excluding Chinese public holidays.

Models and list prices

Prices are per 1M tokens and were correct at the time of writing — always confirm on the official pricing page, which also lists context length, concurrency limits and current model names. Charges = tokens × price.

How the studio uses it

• Structured brief in, strict JSON out: headline, sub, CTA variants per language, subtitle lines, voice-over script and storyboards.
• A deterministic hologram rule-set validates the result: square 1:1, pure black background, safe area, 10–30 s loop, no small text.
• Image and video work (cut-outs, black-background conversion, encoding) runs in a separate rendering queue, not in the LLM call.
• Every AI-generated asset is stored with prompt, model, version and reviewer decision for audit and disclosure.

Server-side proxy (never ship a key to the browser)

// server/deepseek-proxy.mjs  —  node server/deepseek-proxy.mjs
// export DEEPSEEK_API_KEY=sk-...  then set LG_CONFIG.ai.mode = 'proxy'
// in assets/js/config.js

const upstream = await fetch('https://api.deepseek.com/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.DEEPSEEK_API_KEY}`
  },
  body: JSON.stringify({
    model: 'deepseek-flash',            // or 'deepseek-v4-pro'
    messages: [
      { role: 'system', content: 'You are a Hong Kong OOH creative director. Reply with JSON only.' },
      { role: 'user', content: prompt }
    ],
    response_format: { type: 'json_object' },
    temperature: 1.0,
    max_tokens: 1400
  })
});
const data = await upstream.json();

5. Measurement framework

Three tiers, always labelled. This structure follows the IAB DOOH measurement guidance: delivery facts are separated from audience estimates, and modelled numbers are never relabelled as plays.

6. Playback, devices and hologram rules

Rotating LED fans are pseudo-volumetric: black pixels emit no light, so a black background is what produces the floating image. Small text will not resolve, white backgrounds destroy the illusion, and the fan needs 8–10 hours of running followed by roughly 30 minutes of rest with at least 30 cm of clearance.

7. Roadmap and scope discipline

8. Compliance, privacy and content policy

• Regulated categories (medical claims, financial products, tobacco/vaping, alcohol, gambling) require evidence of approval and venue consent before scheduling.
• Every creative must be lawful, cleared for third-party rights (music, fonts, likeness, trademarks) and consistent with venue restrictions.
• QR and NFC landing pages that collect personal data must publish a collection-purpose statement and follow the Personal Data (Privacy) Ordinance in Hong Kong; coupon data is stored pseudonymously.
• Noise, light spill and operating-hour rules are enforced by the scheduler, including mandatory rest periods and dimming at night.
• AI-generated advertising is disclosed to the operator during moderation, and AI assets keep a prompt and model audit trail.
• People-counting, if ever deployed, stays on-device, keeps no images and no identifiers, and is disclosed at the venue.

9. Location-based services and availability

Inventory is geospatial: every location carries WGS-84 coordinates, so the marketplace can answer the two questions a rate card cannot — what is near my shop, and what is actually free for my dates.

10. Payments and settlement

Four rails, one invoice. The advertiser pays in HKD; the provider fee is charged on top of media value and is never taken out of the landlord share.

11. Explainer video and localisation

The explainer is an animated, chaptered player with narration and subtitles in every built-in language, so one asset serves an advertiser pitch, a landlord pitch and a sales deck. It can be replaced by your own footage without touching the rest of the site.

// assets/js/config.js — three ways to publish the explainer
video: {
  mode: 'builtin',                  // animated four-language player in video.html
  // mode: 'file',    src: 'assets/video/3dNakedEye-explainer.mp4', poster: 'assets/img/poster.jpg',
  // mode: 'youtube', youtubeId: 'XXXXXXXXXXX',
  durationSec: 146,
  voiceOver: true,                  // browser speech narration; 繁體中文 always uses a Cantonese voice
  references: [ /* curated third-party DSP / DOOH videos */ ]
}

12. Markets and coverage

Two markets run on one platform today: Hong Kong and Thailand. Each market carries its own districts, landmarks, map projection bounds and settlement currency, while inventory, pricing and proof of play use a single data model.

13. Advertiser console and email automation

The advertiser console borrows the column logic advertisers already know from Meta Ads Manager and Google Ads — delivery state, budget, spend, verified plays, modelled impressions, QR clicks, CTR, CPM, conversions, cost per conversion and a comparison against the platform benchmark — while the notification engine turns every handover into an email in the recipient language.

14. Accounts, membership and the two dashboards

Advertisers and landlords share one sign-in and each lands on their own dashboard.

15. FAQ, enquiry and the AI assistant

The FAQ corpus is also the assistant's knowledge base.

16. WhatsApp Business and contact channels

One place configures every channel: config.js.

Handles are placeholders.

17. Creative preview and the upload pipeline

preview.html accepts any file the advertiser has, and decodes it in the browser.

18. Catalogue, dimensions and the cloud walkthrough

The catalogue, the calculator and the cloud walkthrough are transcribed from the supplier’s own documents. Nothing is estimated: where a document is silent the page says so.