Grundlagen
AlpViewer ist eine mandantenfähige Digital-Signage- und DOOH-Plattform. Jede Funktion ist auf zwei Wegen steuerbar:
- GUI — das Portal unter /app (Login, Demo ohne Login).
- API — REST unter https://alpviewer.bitblade.io, Authentifizierung per Header x-api-key: <API-Key>.
Die drei Zugangsdaten findest du im Portal unter Einstellungen:
| Schlüssel | Zweck |
|---|---|
| api_key | Voller Mandanten-Zugriff (Header x-api-key) — alle /v1/*-Endpunkte. |
| reporting_token | Nur-Lese-Reporting für customer.bitblade.io / app.maintably.com (Header Authorization: Bearer). |
| enrollment_key | Auto-Enrollment der nativen Android-App per MDM. |
curl https://alpviewer.bitblade.io/v1/screens -H "x-api-key: <API-Key>"
Mandanten, Login & Rollen
Multi-Tenant ab der ersten Zeile: jeder Mandant ist sauber getrennt. Rollen: member, admin, platform_admin, demo.
GUI: Registrierung /app#/register · Login /app#/login · Demo (ohne Login) /app#/demo · Benutzerverwaltung unter Einstellungen · Plattform-Admin legt Mandanten an.
| Methode | Pfad | Zweck |
|---|---|---|
| POST | /auth/register | Mandant + Erst-Benutzer anlegen |
| POST | /auth/login | Login (Session-Cookie) |
| GET | /auth/me | Aktueller Benutzer/Mandant |
| GET/POST | /v1/users | Benutzer auflisten/anlegen |
| GET | /v1/keys | api_key, reporting_token, enrollment_key |
Screens & Player
Jeder Screen erhält eine eindeutige 64-Zeichen-Player-URL /p/<token> — im Browser des Abspielgeräts öffnen, fertig. Läuft auf Smart-TV, Android, Windows, Linux, Raspberry Pi, iOS. Als PWA installierbar; native Android-App (Watchdog, Kiosk, Selbst-Update) und Electron-Wrapper verfügbar.
Pro Screen einstellbar: Name, Auflösung, Ausrichtung, Standort, player_protected (Zugriffsschutz), cache_ahead_days (0–60 Tage Offline-Vorlauf), granular_pop (Quartil-Rückmeldung), layout_id (Multi-Zonen), enroll_serial/enroll_device_name (MDM-Zuordnung).
GUI: Screens (anlegen, bearbeiten, Player öffnen, App-Anleitung, Karte, „▶ Jetzt", löschen).
| Methode | Pfad | Zweck |
|---|---|---|
| GET/POST | /v1/screens | Screens auflisten/anlegen |
| PATCH/DELETE | /v1/screens/:id | Bearbeiten/löschen |
| POST | /v1/screens/:id/locate | Sofort-GPS anfordern |
| GET | /p/:token | Web-Player (HTML) |
| GET | /p/:token/info · /manifest · /commands | Player-Daten, Cache-Manifest, Kommandos |
| GET | /p/:token/app.apk | Vorkonfigurierte Android-APK |
Medien
Upload aller gängigen Formate. Bilder werden automatisch zu WebP/AVIF konvertiert, PDF wird direkt gespeichert, PowerPoint (.pptx) beim Upload serverseitig zu PDF konvertiert (LibreOffice). Außerdem YouTube-Videos per URL. Content-adressiert (SHA-256), signierte Download-URLs.
GUI: Medien (Upload mit Fortschritt, Vorschau, umbenennen, stummschalten, löschen; YouTube hinzufügen).
| Methode | Pfad | Zweck |
|---|---|---|
| GET | /v1/assets | Medien auflisten |
| POST | /v1/assets?filename=&mime= | Upload (Body roh, Content-Type application/octet-stream) |
| POST | /v1/assets/youtube | YouTube-Video per URL |
| PATCH/DELETE | /v1/assets/:id | Umbenennen/stummschalten/löschen (?force=1) |
curl -X POST "https://alpviewer.bitblade.io/v1/assets?filename=deck.pptx&mime=application/vnd.openxmlformats-officedocument.presentationml.presentation" \ -H "x-api-key: <API-Key>" -H "content-type: application/octet-stream" --data-binary @deck.pptx
Standorte
Ein Standort kann einen einzelnen Player (z. B. Bushaltestelle) oder eine Gruppe (z. B. Friseur mit mehreren Screens) umfassen. Mit Öffnungszeiten (Wochentag×Zeit) und Sprachen. Stummschalten wirkt auf alle Screens des Standorts.
GUI: Screens → Standorte (anlegen, Öffnungszeiten/Sprachen bearbeiten, stummschalten).
| Methode | Pfad | Zweck |
|---|---|---|
| GET/POST | /v1/locations | Standorte auflisten/anlegen |
| PATCH/DELETE | /v1/locations/:id | Öffnungszeiten, Sprachen, Ton, löschen |
Kampagnen & Targeting (Self-Service-Buchung)
Kunden buchen Kampagnen selbst — Medium zuweisen und programmatisch planen. Das komplette Targeting liegt im target-jsonb der Kampagne:
- Sprache (fail-closed), Region (GPS-Kreis), Standort-Ausschluss, explizite Screen-Liste
- POI-Umkreis: Kunde lädt eine Liste von Orten hoch (Adressen oder Koordinaten); das System prüft passende Standorte im Umkreis (z. B. „500 m um jeden Lidl"). Felder pois:[{name,lat,lng}], poi_radius_m
- Zuschauer (Kamera, live): age_min/age_max, genders (male/female), audiences (Kind/Teenie/Mann/Frau/Rentner), emotions (happy/neutral/sad/angry/surprise), attention_min (% die hinschauen)
- Wetter vor Ort: weather.codes (clear/clouds/rain/snow/storm), temp_min/temp_max (live via open-meteo)
- Zeit: Zeitraum, Daypart, Öffnungszeiten respektieren
- Zielgruppen-Varianten: ein Medium mit bis zu 10 Versionen — die Kamera wählt zur Laufzeit die passende
GUI: Kampagnen → „+ Kampagne anlegen" (alle Targeting-Optionen, „Standorte prüfen" für POI).
| Methode | Pfad | Zweck |
|---|---|---|
| GET/POST | /v1/campaigns | Kampagnen auflisten/anlegen (Targeting im target) |
| PATCH/DELETE | /v1/campaigns/:id | Bearbeiten/pausieren/löschen |
| POST | /v1/poi-check | Orte (Adressen/Koordinaten) + Umkreis → passende Screens |
curl -X POST https://alpviewer.bitblade.io/v1/poi-check -H "x-api-key: <API-Key>" -H "content-type: application/json" \
-d '{"radius_m":500,"pois":[{"address":"Lidl, Freiburg"},{"name":"Filiale","lat":47.99,"lng":7.85}]}'
curl -X POST https://alpviewer.bitblade.io/v1/campaigns -H "x-api-key: <API-Key>" -H "content-type: application/json" \
-d '{"name":"Aktion","start_at":"2026-08-01","end_at":"2026-08-31","creative_asset_id":"<asset>",
"target":{"languages":["de"],"age_min":25,"age_max":45,"genders":["female"],"emotions":["happy"],
"attention_min":40,"pois":[{"lat":47.99,"lng":7.85}],"poi_radius_m":500,"weather":{"codes":["clear"]}}}'Slots & SMADOOH-Loops
Slot-Reihenfolgen definieren den Ablauf (SMADOOH-Muster: Werbung×2 → Standortbesitzer → Unterhaltung, dann von vorn). Geltungsbereich Mandant, Standort oder einzelner Player — der spezifischste gewinnt. Faire LRU-Rotation, loop_cursor pro Screen.
GUI: Kampagnen → Slots (Reihenfolge je Geltungsbereich).
| Methode | Pfad | Zweck |
|---|---|---|
| GET/POST | /v1/slots | Slots auflisten/anlegen (kind campaigns|entertainment, scope) |
| DELETE | /v1/slots/:id | Löschen |
Unterhaltungsvideos (Batches)
Unterhaltungsvideos als Batches — z. B. 30 Videos in DE/FR/IT, mit Zeitraum und Sprache pro Video. Nicht mit regulären Kampagnen zu verwechseln; werden in Entertainment-Slots ausgespielt (Sprachfilter nach Screen/Standort).
YouTube-Wiedergabe: YouTube-Videos (Kampagne, Unterhaltung oder Zone) starten automatisch. Untertitel werden erzwungen und auf die Standort-Sprache gesetzt (Screen-Sprache → sonst Standort-Sprache, z. B. de/fr/it; inkl. YouTube-Auto-Übersetzung via cc_lang_pref). Der Ton folgt der Mute-Kaskade (Mandant → Standort → Player → Medium): stumm = ohne Ton, sonst mit Ton. Der Player liefert dazu das Feld lang in der Ad-Antwort.
GUI: Unterhaltung (Batch anlegen → Sprachen wählen → Videos hochladen).
| Methode | Pfad | Zweck |
|---|---|---|
| GET/POST | /v1/ent-batches | Batches auflisten/anlegen |
| POST | /v1/ent-batches/:id/videos | Videos zum Batch hochladen |
Multi-Zonen-Layouts & Widgets
Bildschirme zeigen mehrere Zonen gleichzeitig. Zonen-Typen: media (Kampagnen-Loop), ticker (Newsticker: fester Text oder RSS-Feed), clock (Uhr), weather (Wetter via open-meteo), web (Web-Embed — Power BI „Publish to web", Grafana, Dashboards), image, pdf, youtube. Vorlagen: Vollbild, Hauptbild+Newsticker, Seitenleiste, Zwei Spalten, Vier Kacheln. Danach einem Screen zuweisen.
GUI: Layouts (Vorlage wählen → Zonen konfigurieren → Screen zuweisen).
| Methode | Pfad | Zweck |
|---|---|---|
| GET | /v1/layout-presets | Zonen-Typen + Vorlagen |
| GET/POST | /v1/layouts | Layouts auflisten/anlegen/aktualisieren (zones-jsonb) |
| DELETE | /v1/layouts/:id | Löschen |
| POST | /v1/screens/:id/layout | Layout zuweisen (layout_id, null = Vollbild) |
curl -X POST https://alpviewer.bitblade.io/v1/layouts -H "x-api-key: <API-Key>" -H "content-type: application/json" \
-d '{"name":"Retail","zones":[{"type":"media","x":0,"y":0,"w":100,"h":88},{"type":"ticker","x":0,"y":88,"w":100,"h":12,"config":{"rss":"https://www.tagesschau.de/index~rss2.xml"}}]}'Instant-Play
Schiebt sofort ein Medium als Prioritäts-Override auf einen Screen (Player übernimmt in ca. 5 s, danach läuft die normale Wiedergabe weiter). Quelle: Medium aus der Bibliothek (asset_id), youtube_id oder direkte url. Löst zusätzlich das Webhook-Event playnow.triggered aus.
GUI: Screens → „▶ Jetzt" pro Screen.
| Methode | Pfad | Zweck |
|---|---|---|
| POST | /v1/screens/:id/play-now | Sofort ausspielen |
curl -X POST https://alpviewer.bitblade.io/v1/screens/<id>/play-now -H "x-api-key: <API-Key>" -H "content-type: application/json" \
-d '{"asset_id":"<asset>","duration_s":20,"muted":true}'Webhooks
Outbound-Events an deine Systeme (Zapier, n8n, eigener Endpoint). Jede Zustellung ist per HMAC-SHA256 signiert — Header x-alpviewer-signature: sha256=… über dem rohen Body, mit deinem Secret (nur bei Erstellung sichtbar). Events: screen.online, screen.offline, playout.completed, device.enrolled, playnow.triggered.
GUI: Einstellungen → Webhooks (anlegen, Events wählen, testen, löschen).
| Methode | Pfad | Zweck |
|---|---|---|
| GET/POST | /v1/webhooks | Auflisten / anlegen (gibt Secret einmalig zurück) |
| POST | /v1/webhooks/:id/test | Test-Event senden |
| DELETE | /v1/webhooks/:id | Löschen |
Zuschauer-Analyse (Kamera)
Optionale Kamera-Analyse lokal im Browser (DSGVO-freundlich, keine Bildspeicherung): Personenzahl, Alter, Geschlecht, Aufmerksamkeit (Blick zum Screen), Emotion. Steuert Zielgruppen-/Kampagnen-Targeting und liefert Auswertungen pro Spot und pro Stunde/Tag.
Feingranular pro Spot: Während jeder Ausspielung werden Aufmerksamkeits-Samples aufgezeichnet (Sekunde × % der Personen, die hinschauen). Der Report zeigt pro Kampagne den Trend — so sieht der Kunde direkt, ob die Aufmerksamkeit während seines Spots abnimmt.
GUI: Reports → Zuschauer (pro Spot / pro Zeit) und „Aufmerksamkeit pro Kampagne" (Trend). Aktivierung über Kampagnen-Zielgruppen bzw. Player-Kamera.
| Methode | Pfad | Zweck |
|---|---|---|
| GET | /v1/reports/audience | Aggregiert (?group=hour) |
| GET | /v1/reports/audience-spots | Publikum pro Spot/Kampagne |
| GET | /v1/reports/attention | Aufmerksamkeits-Trend pro Kampagne (Ø, Trend, Anteil fallend) |
| POST | /p/:token/telemetry · /attention | Player meldet audience-Snapshot bzw. feingranulare Aufmerksamkeits-Samples |
Karten, GPS & Moving-DOOH
Karten-Übersicht aller Player (nach Standort gruppiert) und Detailkarte pro Player. GPS-Telemetrie (alle 60 s), „Orten" fordert sofort eine frische Position an. Moving-DOOH: jeder Ad-Request trägt die GPS-Position mit.
GUI: Karte (Übersicht) · Screens → „📍 Karte" (Detail + Orten).
| Methode | Pfad | Zweck |
|---|---|---|
| POST | /v1/screens/:id/locate | Sofort-Ortung anfordern |
| POST | /p/:token/telemetry | Player meldet GPS/Geräteinfo |
Reports & Proof-of-Play
Jede Ausspielung wird belegt — auf Wunsch mit 25/50/75/100-%-Quartilen (nur 100 % zählt als Playout). Auswertung pro Tag, Kampagne, Screen, Standort, Sprache und Slot. Offline-gequeued und idempotent. Plus Speicher-/Bandbreiten-Nutzung pro Mandant.
GUI: Reports (Playouts, PoP, Zuschauer) · Dashboard (Live-Kennzahlen).
| Methode | Pfad | Zweck |
|---|---|---|
| GET | /v1/reports/playouts?group=day|campaign|screen|location|language|slot | Playout-Auswertung |
| GET | /v1/pop-events | Proof-of-Play-Rohevents |
| GET | /v1/reports/summary | Kennzahlen fürs Dashboard |
Enterprise-Verteilung (MDM & Enrollment)
Native Android-App per MDM (Intune, Scalefusion, SOTI, Esper, VMware) als Managed Configuration ausrollen. Zwei Wege: (A) pro Gerät player_url setzen; (B) per Seriennummer/Gerätename — enrollment_key auf allen Geräten, am Screen Serien-/Gerätename hinterlegen, die App meldet sich automatisch. Unbekannte Geräte landen unter „Wartende Geräte".
GUI: Einstellungen (MDM-Anleitung, Enrollment-Key) · Screens → „Wartende Geräte" (zuweisen).
| Methode | Pfad | Zweck |
|---|---|---|
| POST | /enroll | Gerät meldet Serie/Name (Auth: enrollment_key) |
| GET | /v1/pending-devices | Wartende Geräte |
| POST | /v1/pending-devices/:id/assign | Gerät einem Screen zuweisen |
Mute-Kaskade
Ton stummschalten auf fünf Ebenen — die höhere Ebene überstimmt: Mandant → Standort → Screen → Medium → Kampagne/Slot.
GUI: Einstellungen (Mandant) · Standort · Screen · Medium · Kampagne — jeweils per Stumm-Schalter.
| Ebene | Feld |
|---|---|
| Mandant | PATCH /v1/tenant {muted} |
| Standort/Screen/Medium/Kampagne | muted | -Feld am jeweiligen Objekt
Reporting-API (Partner)
Separate Nur-Lese-Schnittstelle für customer.bitblade.io und app.maintably.com — Authentifizierung per Authorization: Bearer <reporting_token> (bzw. Master-Token für alle Mandanten).
| Methode | Pfad | Zweck |
|---|---|---|
| GET | /reporting/v1/usage · /usage/daily | Speicher, Bandbreite, Playouts |
| GET | /reporting/v1/tenants/usage | Alle Mandanten (Master-Token) |