Setup and Using ESNI
Setup
The ESNI Server
To leverage Zixi’s ESNI implementation, please request that ESNI be enabled for your account by your Zixi account team. Once done, valid ESNI/SCTE-224 element XML payloads can be added to the ESNI database via HTTP PUT.
URL Endpoint
The production URL is: https://esni.zen.zixi.com/<customer-zenmaster-prefix>/
Authentication
Per ESNI standard, use Amazon Signature version 4 for API Requests.
Access Key and Secret Key can be rotated by request. Reach out to your Zixi account rep as required.
HTTP Methods
- PUT – Adding a new XML payload to the Database / Updating the XML payload in the database
- DELETE – Removing an XML payload from the database
- GET – Retrieving XML payloads from the database
XML HTTP PUT ordering
Within the XML payloads are hrefs that reference other media elements. Referenced XMLs must be added to the database prior to broadcasting the media that references these XMLs.
- Audience
- Viewingpolicy
- Policy
- Media
Working with ESNI Elements
Media, Policy, ViewingPolicy, and Audience all have @lastUpdated XML attributes. These must be updated each time a new ESNI element is posted. If @lastUpdated is older than what is currently in the database, the XML will not update.
Tip: When using postman use this variable: lastUpdated="{{$isoTimestamp}}" to ensure current time stamp.
Adding an ESNI Element
- PUT: https://esni.zen.zixi.com/{customer-zenmaster-prefix}/{element}/id/of/element
- BODY: XML formatted Media
- When creating the other ESNI elements, replace “{element}” from the URL above with the ESNI element type – media, policy, viewingpolicy, audience.
Modifying/Viewing an ESNI Element
- PUT/GET: https://esni.zen.zixi.com/{customer-zenmaster-prefix}/{element}/id/of/element
- BODY for PUT: XML formatted Media with edits and updated <lastUpdated> value.
Deleting an ESNI Element
- DELETE: https://esni.zen.zixi.com/{customer-zenmaster-prefix}/{element}/id/of/element
- BODY: empty
Viewing all elements of a certain type in the database
- GET: https://esni.zen.zixi.com/{customer-zenmaster-prefix}/?role={element}
- Replace “{element}” from the URL above with a capitalized version of the ESNI element type – Media, Policy, ViewingPolicy, Audience.
Validating ESNI element XML
PUT: https://esni.zen.zixi.com/{customer-zenmaster-prefix}/__validate
BODY: XML formatted Media
This request will return any errors in the XML preventing a successful upload
Checking Zixi ESNI Decisioning service version
GET: https://esni.zen.zixi.com/{customer-zenmaster-prefix}/__status/about
BODY: empty
Configuration notes:
- Audience tags. By default, the Zixi ESNI backend will only be aware of audience ID’s, Vird tags and DMA tags for associating ZEN Master Targets with Audience files for timing optimization purposes. Options can be added as needed.
- UPID Formats. By default, SCTE-224 UPID asserts will match with SCTE-35 payloads presented in Hex, Base64, or Text. If your deployment requires this to be limited to a specific format, this can be arranged.
- Schedule offset. Depending on upstream workflows, streaming latency can cause a timing disparity between UTC schedule timing and currently displayed content on the stream. An offset can be applied so that matchTime and SCTE-35 effective windows align with video stream.