The Quividi conditional play feature connects to your local Quividi VidiReports WebSocket API and evaluates audience data against conditions you define. When conditions are met, the associated content becomes eligible to play.
Prerequisites
1. Quividi VidiReports must be installed and running on the same device as the embed signage player
2. The Quividi Audience Data Conditional Play feature must be enabled for your embed signage account
3. Your device must be configured with the correct WebSocket URL (if different from the default)
🙋♀️ - The Quividi Audience Data Conditional Play feature is available upon request. If you'd like to use it, please contact us to activate it on your account.
Device Configuration
Setting the WebSocket URL
By default, the integration connects to `ws://127.0.0.1:2974` which is the standard VidiReports WebSocket endpoint.
If your Quividi installation uses a different port or address, do this:
1. Navigate to Devices in the embed signage CMS
2. Edit the device you want to configure
3. Find the Quividi section
4. Enter your custom WebSocket URL (e.g., `ws://192.168.1.100:2974`)
5. Save the device
Creating Conditional Play Rules
Adding a Quividi Condition
1. Open a Playlist (via Layout Builder or standalone playlist)
2. Select the content item you want to apply conditions to
3. Open the Conditional Play settings
4. Select Quividi from the condition type dropdown
5. Configure your condition:
- Attribute: The data point from the Quividi API to evaluate
- Operator: How to compare the value (`more than`, `less than`, `equals`)
- Value: The threshold value to compare against
Understanding Attributes
The Quividi VidiReports API returns audience data in a structured JSON format. To access this data, you need to specify the correct attribute path.
How Attribute Paths Work
The API returns data in a nested structure within the `audience_current.count` object. Your attribute path tells the system where to find the value you want to evaluate.
Single Attribute
When you enter a single word as the attribute, the system will:
1. First look for it in the top-level totals
2. If not found there, treat it as a category name and return the total count for that category
Nested Attribute (Dot Notation)
Use dot notation to access specific nested values.
The format is: category.attribute
This allows you to drill down into specific sub-categories of the data.
Finding Available Attributes
Refer to your Quividi VidiReports API documentation to understand the structure of the `audience_current` response. The available attributes depend on your Quividi configuration and license.
The general structure follows this pattern:
count
├── [top-level category]
│ ├── total
│ ├── [attribute 1]
│ ├── [attribute 2]
│ └── ...
├── [another category]
│ ├── total
│ ├── [attribute 1]
│ ├── [attribute 2]
│ └── ...
└── ...
Condition Operators
Operator | Description | Example Use Case |
more than | Value must be greater than threshold | Show content when audience count exceeds a number |
less than | Value must be less than threshold | Show content when audience is below a threshold |
equals | Value must exactly match threshold | Show content for a specific count |
Multiple Conditions
You can add multiple Quividi conditions to a single content item. When multiple conditions are applied, ALL conditions must be met (AND logic) for the content to be eligible to play.
Examples:
Example 1: Basic Threshold
Show content only when there are viewers present:
Attribute: total
Operator: more than
Value: 0
Example 2: Category-Based
Show content based on a specific audience category total:
Attribute: [category name]
Operator: more than
Value: 0
Example 3: Nested Attribute
Target a specific subset within a category:
Attribute: [category].[attribute]
Operator: more than
Value: `0`
Example 4: Multiple Conditions
Combine conditions for more specific targeting:
Condition 1:
Attribute: total
Operator: more than
Value: 2
Condition 2:
Attribute: [category]
Operator: more than
Value: 0
This would require both a minimum total audience of 3 people AND presence in a specific category.
Technical Details
WebSocket Connection
- Default URL: `ws://127.0.0.1:2974`
- Subprotocol: `quividi`
- Auto-reconnect: Yes (5 second delay)
- Check interval: 1 second
API and Data Processing
The integration uses Periodic Mode in the Quividi Real-Time API and listens for messages containing `audience_current.count` data to then evaluate your conditions against the most recent data received.
Condition Evaluation
- Conditions are evaluated every second
- All conditions on a content item use AND logic
- Content becomes eligible when all conditions pass
- Content becomes ineligible when any condition fails
- When no audience data is available (e.g., before the Quividi WebSocket connects), all values are treated as 0.
Data Privacy Note
This integration processes audience analytics data locally on the device. The attribute paths and values you configure are stored in your channel data. Ensure your use of audience analytics complies with applicable privacy regulations and your organisation's data protection policies.
Troubleshooting
Content Not Playing
Verify VidiReports is Running and Licensed: Ensure the Quividi VidiReports service is active on the device and with an active license.
Check Attribute Path: Verify your attribute path matches the structure in the Quividi API response
Test with Browser: You can test the WebSocket connection directly using browser developer tools
Check WebSocket Connection: Open browser developer tools on the device and look for "Quividi: WebSocket connected" in the console.
Connection Errors
If you see "Quividi: WebSocket error" or repeated reconnection attempts:
1. Verify the WebSocket URL is correct in device settings
2. Check that VidiReports is running and accessible
3. Ensure no firewall is blocking the WebSocket port on the device
4. Confirm the device can reach the VidiReports endpoint
Debugging Attribute Paths
To verify you're using the correct attribute path:
1. Connect to your Quividi WebSocket directly using a WebSocket client
2. Observe the `audience_current` messages
3. Note the structure of the `count` object
4. Build your attribute path based on the actual response structure
For further assistance, contact embed signage support or refer to the Quividi VidiReports API documentation for detailed information about available data attributes.