Going Further

Optional integrations, security options, and help if something goes wrong.

Prerequisites

Before using JWT-based authentication, you need:
Server-side token exchange
Your backend must be able to request a widget JWT for the current user (e.g. after the user logs in). The widget does not call our API; it only reads the JWT from a cookie that your server has set.
Unibo API key
Your backend needs an API key to call the Unibo token endpoint. If you don’t have one, contact your Unibo account manager or support.


JWT Based Authentication

For integrations that need stricter security. Your backend requests a JWT from the Unibo API and sets it in a cookie.
NOTE: This is optional today but may be required for future features with higher security requirements.
Required cookie
Cookie
Example
Description
unibo_userToken
eyJhbGciOiJI...
JWT obtained from the Unibo API

<script>
  document.cookie = "unibo_userToken=eyJhbGciOiJI...; path=/; Secure; SameSite=Lax";
</script>

<script src="https://<brand-name>.widgets.unibo.io/on-site/widget.js"></script>
How it works:
Player logs in to your site
        ↓
Your backend requests a JWT from the Unibo API
        ↓
Your backend sets the unibo_userToken cookie
        ↓
Widget loads and authenticates using the JWT
        ↓
Tournaments are loaded for this player

Note: When using JWT authentication, the unibo_userId and unibo_registrationDate cookies are not needed, the JWT contains all required player information.

Technical Notes

Detail
Value
Bundle size
Single file, all dependencies included
Style isolation
Shadow DOM — widget styles never affect your site
z-index
9999 (widget overlays your page when open)
Scroll behavior
Page scroll is locked while the widget is open

Troubleshooting

Widget doesn't open when clicking the button
Check that the button ID matches the pattern exactly: unibo-osw-custom-1, unibo-osw-custom-2, etc. The number must be a positive integer. Load the widget script after the button exists in the DOM.
Widget loads but shows no tournaments
Check authentication cookies. Open the browser console and filter by [unibo-widget] — all widget logs are prefixed. Verify that the unibo_userId value matches what's registered in the Unibo platform.
Widget styles are broken
The widget uses Shadow DOM for complete style isolation. If you see unstyled content, verify that your CSP allows 'unsafe-inline' for style-src. Some ad blockers or browser extensions can interfere with Shadow DOM rendering.
Console shows "Authentication failed"
  • Legacy auth: Verify both unibo_userId and unibo_registrationDate are set and readable (check document.cookie in the console). Ensure the registration date format is valid.
  • JWT auth: Verify the unibo_userToken cookie contains a valid, non-expired JWT from the Unibo API.