# Showtimes Finder Widget
Showtimes Finder Widget
export const DOMAIN = (typeof import.meta !== 'undefined' && import.meta.env?.ZUDOKU_PUBLIC_CIN_DOMAIN) || 'cineamo.com';
The Showtimes Finder Widget is an embeddable iframe that displays cinema showtimes for a specific movie. It provides an interactive map and list view of nearby cinemas, allowing users to search for showtimes by location and date.
## Quick Start
Add the following iframe to your HTML:
```html
```
**Important**: The `allow="geolocation"` attribute is required for the location-based search feature to work in the embedded widget.
Replace:
- `en` with your desired language code (`en` or `de`) in the URL path
- `YOUR_TOKEN` with your authentication token
- `MOVIE_ID` with the Cineamo movie ID (e.g., `699236`)
- All color values to match your website's branding
## Live Example
## Configuration
### Required Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `locale` (in URL path) | string | Language code in URL path: `/en/embedded` or `/de/embedded` |
| `token` | string | Authentication token for API access |
| `movie` | string | Movie ID from Cineamo (e.g., `699236`) |
:::warning{title="Legacy Alphanumeric Movie ID deprecation"}
The `movie` parameter now expects a numeric Movie `id` (e.g. `699236`). For backwards compatibility, the legacy alphanumeric `cineamoId` (e.g. `967941m`) is still accepted, but is considered **deprecated**, and will be phased out, removing support after a grace period. For more information, see the [release notes](/changelog/2026-07-01).
:::
#### Style Customization
Customize the widget's appearance to match your website's branding:
| Parameter | Type | Description |
|-----------|------|-------------|
| `backgroundColor` | HEX color | Background color (e.g., `#111111`) |
| `onBackgroundColor` | HEX color | Text color on background (e.g., `#FFFFFF`) |
| `surfaceColor` | HEX color | Surface/card color (e.g., `#FFFFFF33`) |
| `onSurfaceColor` | HEX color | Text color on surface (e.g., `#F2F2F2`) |
| `primaryColor` | HEX color | Primary action color (e.g., `#24B9DC`) |
| `onPrimaryColor` | HEX color | Text color on primary (e.g., `#000023`) |
**Note**: When passing HEX colors in URLs, encode the `#` symbol as `%23`.
#### Date filter customization
| Parameter | Type | Description |
|-----------|------|-------------|
| `initiallySelectedDate` | String, one of ['all', 'today', 'previews'] | Date filter that should be active by default. Omit it to let the release date decide: `all` while the movie is unreleased, `today` once it has released. `previews` requires the movie to have preview showings (see `showPreviews`); otherwise the widget falls back to `all`. |
| `showPreviews` | Boolean (`false`) | The PREVIEWS tab, listing showings that take place before the movie's release date, is shown by default — pass `false` to suppress it. The tab only appears while the release date still lies ahead and the movie has such showings. Implied when `initiallySelectedDate=previews`. While the tab is available, the day buttons next to it start at the release date instead of today. |
| `fontSize` | Number, one of [10, 12, 14] | Font size for the date-selector buttons |
## Examples
### Basic Implementation
```html
Movie Showtimes
Find Showtimes
```
### Custom Styling
```html
```
## Features
### Interactive Search
- **Location-based search**: Find cinemas near the user's current location
- **Manual search**: Search by city name or postal code
- **Auto-complete**: Suggestions while typing location
### Date Filtering
- View showtimes for today or up to 7 days in advance — for an unreleased movie the 7 days start at its release date
- Easy date selection with horizontal date picker
- "All dates" option to see all available showtimes
- "Previews" tab for advance screenings before the movie's release date, shown by default (suppress with `showPreviews=false`)
### Cinema Information
Each cinema card displays:
- Cinema name and address
- Distance from selected location
- Available showtimes with direct booking links
- Cinema amenities and features
## Security
### CORS and Embedding
The widget is configured to be embedded on any domain. However:
- Authentication tokens are required for API access
- Tokens should be specific to your domain/application
- Contact support to obtain production tokens
### Content Security Policy
If your website uses CSP headers, add the following directives:
```
frame-src https://showtimes-finder.{DOMAIN};
```
## Best Practices
### Height Considerations
- **Minimum height**: 500px recommended
- **Mobile**: Consider full viewport height (`100vh`)
- **Desktop**: 600-800px works well for most layouts
### Performance
- The widget loads asynchronously and won't block your page
- Initial load includes map tiles (if enabled), consider loading indicators
- Widget caches cinema data for better performance
### User Experience
- Place widget prominently on movie detail pages
- Consider adding a heading or context above the widget
- Ensure sufficient space for the map view on desktop
- Test on various screen sizes
### Accessibility
- Always include a descriptive `title` attribute on the iframe
- Ensure parent page has proper heading structure
- Consider adding skip links for keyboard navigation
## Customization
### Color Scheme Examples
#### Dark Mode
```
&backgroundColor=%23000000&onBackgroundColor=%23FFFFFF&surfaceColor=%23212121&onSurfaceColor=%23FFFFFF&primaryColor=%2300E5FF&onPrimaryColor=%23000000
```
#### Light Mode
```
&backgroundColor=%23FFFFFF&onBackgroundColor=%23000000&surfaceColor=%23F5F5F5&onSurfaceColor=%23333333&primaryColor=%23007AFF&onPrimaryColor=%23FFFFFF
```
#### Cinema Branding Example
```
&backgroundColor=%23082655&onBackgroundColor=%23FFFFFF&surfaceColor=%23224377&onSurfaceColor=%23FFFFFF&primaryColor=%23F8132D&onPrimaryColor=%23FFFFFF
```
## Browser Compatibility
The widget supports:
- Chrome/Edge (latest)
- Firefox (latest)
- Safari (latest & iOS Safari)
- Mobile browsers (iOS, Android)
### Required Features
- ES6+ JavaScript support
- CSS Grid and Flexbox
- Geolocation API (optional, for location features)
## Troubleshooting
### Widget not loading
1. Check the iframe `src` URL is correct
2. Verify your authentication token is valid
3. Check browser console for CORS errors
4. Ensure the movie ID exists in Cineamo database
4. Ensure you specified all style color values
5. **Verify the `locale` parameter is included** - this is a required parameter
### Geolocation not working
The location-based search requires the `allow="geolocation"` attribute on the iframe:
```html
```
**Common issues**:
1. **Missing `allow` attribute**: The iframe must explicitly allow geolocation access
2. **HTTPS required**: Geolocation only works on secure (HTTPS) websites
3. **Browser permissions**: Users must grant location permission when prompted
4. **Fallback behavior**: If geolocation fails, the widget automatically falls back to IP-based location
**Browser Support**:
- Chrome/Edge: Full support with `allow="geolocation"`
- Firefox: Full support with `allow="geolocation"`
- Safari: Full support with `allow="geolocation"`
- Mobile browsers: May require additional user interaction due to privacy restrictions
### Missing or incorrect locale
If translations are not working or the widget shows errors:
- Ensure the `locale` parameter is present in the URL
- Verify the locale value is one of: `en`, `de`, or `fr`
- The widget does **not** auto-detect browser language - you must specify it explicitly
### Map not displaying
- Map requires sufficient height (minimum 400px)
- Map only displays on desktop (>1024px width)
- Check for JavaScript errors in console
### Colors not applying
- Ensure HEX colors use `%23` instead of `#` in URLs
- Verify all 6 color parameters are provided
- Check for URL encoding issues
## API Integration
The widget uses the following Cineamo APIs:
- **Showings API**: Fetch showtimes for cinemas
- **Cities API**: Search and geocode locations
- **Movies API**: Validate movie availability
For direct API integration instead of the widget, see the [API Reference](/api).
## Support
### Getting Started
- Request an authentication token: support@cineamo.com
- Check movie availability via API or admin panel
- Test with the demo token on staging environment
### Technical Support
- Email: support@cineamo.com
- Include: token (redacted), movie ID, and browser info
- Attach screenshots if experiencing visual issues
### Feature Requests
Contact us to discuss custom features or white-label options.
## Changelog
### 2026-07-01
- The `movie` parameter now expects a numeric Movie `id` (e.g. `699236`). For backwards compatibility, the legacy alphanumeric `cineamoId` (e.g. `967941m`) is still accepted, but is considered **deprecated**, and will be phased out, removing support after a grace period. For more information, see the [release notes](/changelog/2026-07-01).
❌ OLD (deprecated, still accepted)
```
https://showtimes-finder.{DOMAIN}/en/embedded?token=YOUR_TOKEN&movie=967941m
```
✅ NEW
```
https://showtimes-finder.{DOMAIN}/en/embedded?token=YOUR_TOKEN&movie=699236
```
### 2025-12-11
- The Iframe URL changed its structure related to locale configuration:
❌ OLD
```
https://showtimes-finder.{DOMAIN}/embedded?token=YOUR_TOKEN&movie=MOVIE_ID&locale=en
```
✅ NEW
```
https://showtimes-finder.{DOMAIN}/en/embedded?token=YOUR_TOKEN&movie=MOVIE_ID
```
### 2025-11-27
- Initial widget release
- Support for location-based search
- Date filtering
- Dual view modes (list/map)
- Full color customization