Skip to content

Commit 66d1ea9

Browse files
hillslatthillslatt
authored
Concurrent Streams API
MVP and base for Concurrent Streams API
1 parent 7758e23 commit 66d1ea9

File tree

2 files changed

+256
-1
lines changed

2 files changed

+256
-1
lines changed

‎Concurrent-Streams.md‎

Lines changed: 223 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
1+
# About the IAB Tech Lab <a name="techlab"></a>
2+
The IAB Technology Laboratory is a nonprofit research and development consortium charged with producing and helping companies implement global industry technical standards and solutions. The goal of the Tech Lab is to reduce friction associated with the digital advertising and marketing supply chain while contributing to the safe growth of an industry. The IAB Tech Lab spearheads the development of technical standards, creates and maintains a code library to assist in rapid, cost-effective implementation of IAB standards, and establishes a test platform for companies to evaluate the compatibility of their technology solutions with IAB standards, which for 18 years have been the foundation for interoperability and profitable growth in the digital advertising supply chain. Further details about the IAB Technology Lab can be found at www.iabtechlab.com
3+
### IAB Tech Lab Lead:
4+
5+
Hillary Slattery, Sr. Director of Product, IAB Tech Lab
6+
7+
### License <a name="license"></a>
8+
9+
This specification is licensed under a Creative Commons Attribution 3.0 License. To view a copy of this license, visit creativecommons.org/licenses/by/3.0/ http://creativecommons.org/licenses/by/3.0/ or write to Creative Commons, 171 Second Street, Suite 300, San Francisco, CA 94105, USA.
10+
11+
### Disclaimer <a name="disclaimer"></a>
12+
13+
THE STANDARDS, THE SPECIFICATIONS, THE MEASUREMENT GUIDELINES, AND ANY OTHER MATERIALS OR SERVICES PROVIDED TO OR USED BY YOU HEREUNDER (THE “PRODUCTS AND SERVICES”) ARE PROVIDED “AS IS” AND “AS AVAILABLE,” AND IAB TECHNOLOGY LABORATORY, INC. (“TECH LAB”) MAKES NO WARRANTY WITH RESPECT TO THE SAME AND HEREBY DISCLAIMS ANY AND ALL EXPRESS, IMPLIED, OR STATUTORY WARRANTIES, INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AVAILABILITY, ERROR-FREE OR UNINTERRUPTED OPERATION, AND ANY WARRANTIES ARISING FROM A COURSE OF DEALING, COURSE OF PERFORMANCE, OR USAGE OF TRADE. TO THE EXTENT THAT TECH LAB MAY NOT AS A MATTER OF APPLICABLE LAW DISCLAIM ANY IMPLIED WARRANTY, THE SCOPE AND DURATION OF SUCH WARRANTY WILL BE THE MINIMUM PERMITTED UNDER SUCH LAW. THE PRODUCTS AND SERVICES DO NOT CONSTITUTE BUSINESS OR LEGAL ADVICE. TECH LAB DOES NOT WARRANT THAT THE PRODUCTS AND SERVICES PROVIDED TO OR USED BY YOU HEREUNDER SHALL CAUSE YOU AND/OR YOUR PRODUCTS OR SERVICES TO BE IN COMPLIANCE WITH ANY APPLICABLE LAWS, REGULATIONS, OR SELF-REGULATORY FRAMEWORKS, AND YOU ARE SOLELY RESPONSIBLE FOR COMPLIANCE WITH THE SAME, INCLUDING, BUT NOT LIMITED TO, DATA PROTECTION LAWS, SUCH AS THE PERSONAL INFORMATION PROTECTION AND ELECTRONIC DOCUMENTS ACT (CANADA), THE DATA PROTECTION DIRECTIVE (EU), THE E-PRIVACY DIRECTIVE (EU), THE GENERAL DATA PROTECTION REGULATION (EU), AND THE E-PRIVACY REGULATION (EU) AS AND WHEN THEY BECOME EFFECTIVE.
14+
15+
# Table of Contents
16+
- [About the IAB Tech Lab](#techlab)
17+
- [License](#license)
18+
- [Disclaimer](#disclaimer)
19+
- [Introduction](#intro)
20+
- [Concurrent Streams Request](#streamsrequest)
21+
- [Concurrent Streams Request](#streamsresponse)
22+
- [Object: StreamsData](#streamsdata)
23+
- [Object: MediaStreams](#mediastreams)
24+
- [Object: StreamCount](#streamcount)
25+
- [Object: Content](#content)
26+
- [Implementation Guidance](#impguide)
27+
- [General Information](#geninfo)
28+
- [Content Information](#contentinfo)
29+
- [json Examples](#json)
30+
31+
# Introduction <a name="intro"></a>
32+
This is version 1.0 of the Concurrent Streams specification and every attempt will be made to make future versions backward compatible if possible.
33+
34+
## Executive Summary
35+
Due to challenges of forecasting live inventory, and dynamic viewership changes that occur during the live event playout, advertising systems may be inappropriately scaled to process ad decision transactions, causing poor UX and lost revenue opportunities for DSPs, SSPs, pub ad servers, and publishers.
36+
37+
This API aims to give a standard way for subscribers to ask for information on how many viewers are in a stream when a live event is occurring at the time of ping.
38+
39+
## Business Problem
40+
SSAIs: Need a standard way to provide viewership signals to subscriber systems, so that they can receive ad decisions back in a timely, low-latency manner to improve user experience and minimize slate during a live event.
41+
42+
Subscribers to the API on the sell side such as Publishers, Publisher Ad Servers, and/or SSPs need a way to understand near real time viewership data to ensure optimal monetization, avoid slate, and scale their capacity to be able to handle spikes in traffic.
43+
44+
Subscribers on the buy side such as DSPs and advertisers need to adjust their infrastructure to manage QPS spikes during an event to ensure valuable inventory doesn’t get blocked due to hitting upper limits on QPS, ensure effective campaign pacing and adjust their bids appropriately. All of this will help advertisers increase advertising opportunities during live events they’re interested in.
45+
46+
47+
## Concurrent Streams Request <a name="streamsrequest"></a>
48+
49+
| Attribute | Type | Required | Description |
50+
| --------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
51+
| version | string | yes | E.g., 1.0.0 |
52+
| requestor | string | recommended | Authorized party requesting information from the endpoint. Not required if the endpoint allows anonymous requests. |
53+
| sdp | string | optional | Streams Data Provider. This is the content owner or distributor for which live viewership data is being requested. Recommended only when the endpoint provides data from multiple providers, and the requestor needs to filter to specific Streams Data Providerss. |
54+
55+
## Concurrent Streams Response <a name="streamsresponse"></a>
56+
57+
| Attribute | Type | Required | Description |
58+
| ------------ | ------------- | -------- | ---------------------------------------------------------- |
59+
| version | string | yes | E.g., 1.0.0 |
60+
| timestamp | integer | yes | Date/time of the snapshot (Unix timestamp in milliseconds) |
61+
| streamsdata | object, array | yes | Streams data requested by the caller |
62+
63+
### Object: StreamsData <a name="streamsdata"></a>
64+
65+
| Attribute | Type | Required | Description |
66+
| ------------ | ------------- | -------- | ------------------------------------------------------------------------------------ |
67+
| sdp | string | | Streams Data Provider |
68+
| mediastreams | object, array | yes | Snapshot of viewership data for live events. Each mediastream includes stream count. |
69+
70+
### Object: MediaStreams <a name="mediastreams"></a>
71+
72+
| Attribute | Type | Required | Description |
73+
| ---------- | ------------- | -------- | --------------------------------------- |
74+
| content | object | | See: Object: Content in AdCOM 1.0 |
75+
| eventstart | integer | yes | Event start time (Unix timestamp in ms) |
76+
| eventend | integer | yes | Event end time (Unix timestamp in ms) |
77+
| streamsdata | object, array | | Contains separate SSAI and CSAI metrics |
78+
79+
### Object: StreamCount <a name="streamcount"></a>
80+
81+
| Attribute | Type | Required | Description |
82+
| --------- | ------- | ----------- | ------------------------------------------------------------------------------ |
83+
| region | integer | | Region codes: 1 - N\_America\_East, 2 - N\_America\_West, etc. |
84+
| sstreams | integer | recommended | Concurrent SSAI streams. At least one of sstreams or cstreams must be present. |
85+
| cstreams | integer | yes | Concurrent CSAI streams. At least one of sstreams or cstreams must be present. |
86+
87+
### Object: Content <a name="content"></a>
88+
Refer to [Object: Content from AdCOM 1.0](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/main/AdCOM%20v1.0%20FINAL.md#object--content-) for specific values.
89+
90+
91+
# Implementation Guidance <a name="impguide"></a>
92+
93+
## General Information <a name="geninfo"></a>
94+
It is expected that some security model or authentication mechanism is in place prior to the API being called to ensure only authorized subscribers are able to request or receive the data.
95+
96+
This API is decoupled from the Request/Response in OpenRTB.
97+
98+
The region is expected to represent the endpoint traffic distribution across different geographic areas. Coarse granularity acceptable for MVP and is expected to drive system scaling in regional datacenters. E.g. US West Coast.
99+
100+
SSAI includes SGAI. Streamers leveraging Server Guided Ad Insertion models should leverage ‘SSAI’ workflows.
101+
102+
As a best practice, it is recommended that viewership values be representative of users at the live edge/timepoint.
103+
104+
Requests will be coming from an API consumer to SSAI vendors on behalf of the Content Owner.
105+
106+
When API is called, metadata will be returned for all live events the Subscriber has access to.
107+
108+
Event name and/or ID is sharable with API subscribers at run time and/or event name is known to subscribers of the API <i>a priori</i> to the request for concurent streams
109+
App information is known <i>a priori</i> to the request
110+
111+
Providers are expected to return information for all Live Events occurring at time of API request.
112+
113+
## Content Information <a name="contentinfo"></a>
114+
The attributes under the <code>mediastream</code> object provide various options for providers to declare a live event, and so that consumers of this data can identify that event in other contexts
115+
A provider can sufficiently identify a specific live event with one or more of the optional attributes from the [<code>content</code> object](#content), each of which is paired with the required attributes of <code>eventstart</code> and <code>eventend</code>:
116+
- Content ID (E.g., global/persistent ID ABC123, or synthetic ID XYZ-456, either of which points to a specific NBA game)
117+
- Title (E.g., NBA Basketball: Lakers vs. Celtics)
118+
- Series (E.g., NBA Basketball)
119+
- Channel: (E.g., ESPN)
120+
121+
It is strongly recommended that some identifier for the content in question is passed. This could correspond to the content owners Content Management System (CMS), and/or some other commercially available content identifier. Whatever content ID is provided, should be the same as the ID that is provided on the Bid Request. Additional information about the Content can be provided in the Extended Content IDs array.
122+
123+
124+
## json Examples <a name="json"></a>
125+
126+
```
127+
{
128+
"version": "1.0.0",
129+
"timestamp": "1713366138",
130+
"streamsdata": [
131+
{
132+
"sdp": "TV Network A",
133+
"mediastreams": [
134+
{
135+
"content": {
136+
"id": "CMS123",
137+
"genres": [646],
138+
"gtax": 9,
139+
"contentrating": "PG-13",
140+
"channel": {"name": "Comedy Channel"},
141+
"data": {
142+
"name": "vendorA.com",
143+
"cids": ["alpha", "beta", "gamma", "delta", "epsilon"]
144+
}
145+
},
146+
"eventstart": "1713366132",
147+
"eventend": "1713378132",
148+
"streamcount": [
149+
{"region": "1", "sstreams": "140000", "cstreams": "400000"},
150+
{"region": "2", "sstreams": "100000", "cstreams": "20000"},
151+
{"region": "3", "sstreams": "500000", "cstreams": "10000"}
152+
]
153+
},
154+
{
155+
"content": {
156+
"id": "CMS456",
157+
"genres": [162],
158+
"gtax": 9,
159+
"contentrating": "PG-13",
160+
"channel": {"name": "WXYZ Channel"},
161+
"data": {
162+
"name": "vendorA.com",
163+
"cids": ["ayyy", "beee", "ceee", "deee", "eeee"]
164+
}
165+
},
166+
"eventstart": "1713366132",
167+
"eventend": "1713378132",
168+
"streamcount": [
169+
{"region": "1", "sstreams": "150000", "cstreams": "500000"},
170+
{"region": "2", "sstreams": "130000", "cstreams": "23000"},
171+
{"region": "3", "sstreams": "520000", "cstreams": "12000"}
172+
]
173+
}
174+
]
175+
},
176+
{
177+
"sdp": "TV Network B",
178+
"mediastreams": [
179+
{
180+
"content": {
181+
"id": "CMS789",
182+
"genres": [483],
183+
"gtax": 9,
184+
"contentrating": "PG",
185+
"channel": {"name": "Sports Now!"},
186+
"data": {
187+
"name": "vendorA.com",
188+
"cids": ["zeta", "eta", "theta", "iota", "kappa"]
189+
}
190+
},
191+
"eventstart": "1713366132",
192+
"eventend": "1713378132",
193+
"streamcount": [
194+
{"region": "1", "sstreams": "140050", "cstreams": "400050"},
195+
{"region": "2", "sstreams": "100060", "cstreams": "20060"},
196+
{"region": "3", "sstreams": "500070", "cstreams": "10070"}
197+
]
198+
},
199+
{
200+
"content": {
201+
"id": "CMS101112",
202+
"genres": [483],
203+
"gtax": 9,
204+
"contentrating": "PG",
205+
"channel": {"name": "Sports 8 (The Ocho)"},
206+
"data": {
207+
"name": "vendorA.com",
208+
"cids": ["efff", "geee", "aych", "aiii", "jayy"]
209+
}
210+
},
211+
"eventstart": "1713366132",
212+
"eventend": "1713378132",
213+
"streamcount": [
214+
{"region": "1", "sstreams": "150050", "cstreams": "500050"},
215+
{"region": "2", "sstreams": "130060", "cstreams": "23060"},
216+
{"region": "3", "sstreams": "520070", "cstreams": "12070"}
217+
]
218+
}
219+
]
220+
}
221+
]
222+
}
223+
```

‎README.md‎

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,33 @@
1-
# Live-Event-Ad-Protocols
1+
![IAB Tech Lab](https://drive.google.com/uc?id=10yoBoG5uRETSXRrnJPUDuONujvADrSG1)
2+
3+
# **Live Event Ad Protocols**
4+
5+
#### About Live Event Ads Program
6+
https://iabtechlab.com/leap
7+
8+
#### About OpenRTB
9+
https://iabtechlab.com/openrtb
10+
11+
#### Contact
12+
For more information, or to get involved, please email [email protected].
13+
14+
#### About IAB Tech Lab
15+
The IAB Technology Laboratory is a nonprofit research and development consortium charged with producing and helping companies implement global industry technical standards and solutions. The goal of the Tech Lab is to reduce friction associated with the digital advertising and marketing supply chain while contributing to the safe growth of an industry. The IAB Tech Lab spearheads the development of technical standards, creates and maintains a code library to assist in rapid, cost-effective implementation of IAB standards, and establishes a test platform for companies to evaluate the compatibility of their technology solutions with IAB standards, which for 18 years have been the foundation for interoperability and profitable growth in the digital advertising supply chain.
16+
17+
Learn more about IAB Tech Lab here: [https://www.iabtechlab.com/](https://www.iabtechlab.com/)
18+
19+
20+
#### Contributors and Technical Governance
21+
22+
Live Event Ad Program, a sub-Working Group of Programmatic Supply Chain Working Group members provide contributions to this repository. Participants in the LIve Event Ad Program and/or the Programmatic Supply Chain Working Group(s) must be members of IAB Tech Lab. Technical Governance and code commits for the project are provided by the IAB Tech Lab Programmatic Supply Chain Commit Group.
23+
24+
Learn more about how to submit changes in our working group: [So, You'd Like to Propose a Change...](http://iabtechlab.com/blog/so-youd-like-to-propose-a-change-to-openrtb-adcom/)
25+
26+
### License
27+
Specificaitons pertaining to Live Event Ad Protocols from the IAB Tech Lab are licensed under a Creative Commons Attribution 3.0 License. To view a copy of this license, visit creativecommons.org/licenses/by/3.0/ or write to Creative Commons, 171 Second Street, Suite 300, San Francisco, CA 94105, USA.
28+
29+
By submitting an idea, specification, software code, document, file, or other material (each, a “Submission”) to the Live Event Ad Protocol repository, to any member of the Programmatic Supply Chain Working Group and/or the Live Event Ad Serving sub-Working Group, or to the IAB Tech Lab in relation to the Live Event Ad Protocols, you agree to and hereby license such Submission to the IAB Tech Lab under the Creative Commons Attribution 3.0 License and agree that such Submission may be used and made available to the public under the terms of such license. If you are a member of the IAB Tech Lab then the terms and conditions of the [IPR Policy](https://iabtechlab.com/ipr-iab-techlab/acknowledge-ipr/) may also be applicable to your Submission, and if the IPR Policy is applicable to your Submission then the IPR Policy will control  in the event of a conflict between the Creative Commons Attribution 3.0 License and the IPR Policy.
30+
31+
#### Disclaimer
32+
33+
THE STANDARDS, THE SPECIFICATIONS, THE MEASUREMENT GUIDELINES, AND ANY OTHER MATERIALS OR SERVICES PROVIDED TO OR USED BY YOU HEREUNDER (THE “PRODUCTS AND SERVICES”) ARE PROVIDED “AS IS” AND “AS AVAILABLE,” AND IAB TECHNOLOGY LABORATORY, INC. (“TECH LAB”) MAKES NO WARRANTY WITH RESPECT TO THE SAME AND HEREBY DISCLAIMS ANY AND ALL EXPRESS, IMPLIED, OR STATUTORY WARRANTIES, INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AVAILABILITY, ERROR-FREE OR UNINTERRUPTED OPERATION, AND ANY WARRANTIES ARISING FROM A COURSE OF DEALING, COURSE OF PERFORMANCE, OR USAGE OF TRADE. TO THE EXTENT THAT TECH LAB MAY NOT AS A MATTER OF APPLICABLE LAW DISCLAIM ANY IMPLIED WARRANTY, THE SCOPE AND DURATION OF SUCH WARRANTY WILL BE THE MINIMUM PERMITTED UNDER SUCH LAW. THE PRODUCTS AND SERVICES DO NOT CONSTITUTE BUSINESS OR LEGAL ADVICE. TECH LAB DOES NOT WARRANT THAT THE PRODUCTS AND SERVICES PROVIDED TO OR USED BY YOU HEREUNDER SHALL CAUSE YOU AND/OR YOUR PRODUCTS OR SERVICES TO BE IN COMPLIANCE WITH ANY APPLICABLE LAWS, REGULATIONS, OR SELF-REGULATORY FRAMEWORKS, AND YOU ARE SOLELY RESPONSIBLE FOR COMPLIANCE WITH THE SAME, INCLUDING, BUT NOT LIMITED TO, DATA PROTECTION LAWS, SUCH AS THE PERSONAL INFORMATION PROTECTION AND ELECTRONIC DOCUMENTS ACT (CANADA), THE DATA PROTECTION DIRECTIVE (EU), THE E-PRIVACY DIRECTIVE (EU), THE GENERAL DATA PROTECTION REGULATION (EU), AND THE E-PRIVACY REGULATION (EU) AS AND WHEN THEY BECOME EFFECTIVE.

0 commit comments

Comments
 (0)