Widget API — Technische Referenz

[api] [widget]

Für Entwickler:innen, die das licensio-Widget in ihre Webseite integrieren oder die Branding-Endpoints direkt nutzen wollen.

Embed-Code

Minimaler HTML-Snippet:

<script
  src="https://<tenant>.licensio.io/widget.js"
  data-tenant="<tenant>">
</script>

Das Widget rendert einen <a>-Button im Container-<div> direkt nach dem Script-Tag. Alle Customizations (Text, Farben, Stil, Größe) werden live aus der Branding-API gelesen.

Optionale data-Attribute (Override pro Embed)

Override für einzelne Embeds (überschreibt API-Werte):

Attribut	Werte	Zweck
data-button-text	string	Beschriftung
data-color	hex #RRGGBB	überschreibt branding.widget_button_color
data-text-color	hex #RRGGBB	überschreibt branding.widget_button_text_color
data-style	solid | outline	überschreibt branding.widget_button_style
data-size	small | medium | large	überschreibt branding.widget_button_size
data-href	URL	überschreibt Default <baseUrl>/join
data-custom-domain	string	Wenn der Tenant eine Custom-Domain hat
data-debug	"true"	Console-Logs aktivieren (für Entwicklung)

Override-Reihenfolge

Pro Style-Property wird folgendermaßen aufgelöst:

`data-Attribut > branding.widget_button_<X> > branding.<base> > Default`

z.B. für primaryColor:

data-color || branding.widget_button_color || branding.primary_color || '#FF6600'

Branding-API

GET /api/portal/branding

Cross-Origin-fähig (Access-Control-Allow-Origin: *), keine Auth nötig.

Response 200 OK:

{
  "branding": {
    "primary_color": "#F87627",
    "button_text_color": "#ffffff",
    "button_style": "rounded",
    "company_name": "Plant Technology",
    "logo_url": "https://...",
    "favicon_url": "https://...",
    "font": "Oswald",
    "widget_button_text": "Lizenz Portal",
    "widget_button_color": null,
    "widget_button_text_color": null,
    "widget_button_style": "solid",
    "widget_button_size": "medium"
  }
}

Tenant-Auflösung: über x-tenant-slug-Header gesetzt durch Portal-Middleware (entweder Subdomain-Match oder Custom-Domain-Lookup).

Cache: keine HTTP-Cache-Header (live aus DB). Defaults: widget_button_color fällt auf branding.primary_color zurück, widget_button_text auf 'Lizenz Portal'.

OPTIONS /api/portal/branding

CORS-Preflight. Liefert:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Content-Type

Style-Varianten

Solid

background: <primaryColor>
color: <textColor>
border: 2px solid <primaryColor>

Outline

background: transparent
color: <primaryColor>
border: 2px solid <primaryColor>

Responsive Größe

Padding + font-size werden via <style>-Tag mit Media-Query injiziert. Button bekommt id="licensio-widget-btn" als Selector.

Größe	Mobile	Desktop (≥750px)
Klein	4px 10px / 11px	8px 16px / 13px
Mittel	6px 14px / 12px	10px 20px / 14px
Groß	8px 18px / 13px	14px 28px / 16px

Robustheit

• !important auf allen Style-Properties (schlägt Theme-CSS)
• CSS-Reset (margin, box-sizing, vertical-align, text-transform, box-shadow)
• DOM-Insertion mit 3-stufigem Fallback: script.parentNode.insertBefore(container, script.nextSibling) → document.body.appendChild → wait for DOMContentLoaded
• document.currentScript-Fallback für async/defer Scripts: querySelector('script[data-tenant][src*="widget.js"]')
• Duplicate-Protection: window.__licensioWidgetLoaded Flag
• Branding-API-Down: rendert mit Default-Farben statt sichtbar zu fehlen

Debugging

Setze data-debug="true" und öffne Console:

[licensio widget] init { tenant: '...', styleAttr: null, baseUrl: 'https://...' }
[licensio widget] fetching branding https://.../api/portal/branding
[licensio widget] branding response { ok: true, status: 200 }
[licensio widget] branding parsed { primary_color: '#F87627', ... }
[licensio widget] render { style: 'solid', size: 'medium', primaryColor: '#F87627', ... }
[licensio widget] inserted after script tag

CORS für eigene Endpoints

Wenn du eigene Endpoints im Tenant-Portal von externer Domain ansprechen willst, beachte: nur /api/portal/branding ist CORS-offen. Alle anderen Routes prüfen Session-Cookies und sind Same-Origin-only.

Verwandt

• Widget-Feature — Creator-fokussierte Anleitung
• Custom Domain — Domain für data-custom-domain