The AVP 3DWS Deck app brings 3D streaming to your application now easier than ever before. It comes equipped with all required UI elements to interact with the stream. Its focus is set to minimize effort on the integrator side.
The app is provided as a web component, which makes it very easy to add into existing websites.
Add the following <script> tag anywhere in your HTML, e.g. in the <head> section
<script
type="module"
src="https://avp-3dws-deck.eu-west-1-web-streaming.avp.tech/avp-3dws-deck.js"
></script>
or add it programmatically via
const script = document.createElement("script");
script.src = "https://avp-3dws-deck.eu-west-1-web-streaming.avp.tech/avp-3dws-deck.js";
script.type = "module";
document.head.appendChild(script);
This will download the library and make a new HTML tag <avp-3dws-deck> available,
which now can be used anywhere in your HTML.
Similarly to the standard installation, there is also two options for integrating the web-component into a react project.
To load the script, you can either import in into the index.html like this:
<script
type="module"
src="https://avp-3dws-deck.eu-west-1-web-streaming.avp.tech/avp-3dws-deck.js"
></script>
The other option is to do it programmatically. You can, like in the example, e.g. use the useEffect hook for this, another good option might be to write a custom hook to load the script.
useEffect(() => {
const script = document.createElement("script");
script.src = "https://avp-3dws-deck.eu-west-1-web-streaming.avp.tech/avp-3dws-deck.js";
script.type = "module";
document.body.appendChild(script);
return () => {
document.body.removeChild(script);
};
}, []);
Just use the new HTML tag <avp-3dws-deck> anywhere in your HTML (or component), e.g.
<avp-3dws-deck
config-id="audi-test"
active
pr-string="etrongt,F83RJ7,2024,6Y6Y,JN,E0A,6H0,1PA,2DS,0GA,4UF,GV0,6XD,EA0,5SL,GM4,5RU,0K9,1X1,J9K,A8F,6K8,2EB,J2B,1LS,6FA,B0A,KB3,0VC,QJ0,C10,IT3,IU1,JE3,IW3,GW0,1BH,3S0,3FG,NI8,7AA,5MT,7M0,7X2,6A0,1P0,VF0,8K4,FP1,2V1,5L0,7G0,F0A,9R0,0YB,0JC,N02,8T6,VC0,G1X,GH1,A51,0N1,6NJ,5KA,KH5,8IY,KS0,KM2,4L6,K8S,EK0,QR8,4D0,GB0,KA0,KK3,6P1,6W1,5K5,QQ0,NW1,NJ0,ES7,L0L,QZ7,8G9,70T,73P,76H,EH1,1XW,AV1,9VD,2C5,7HA,FM0,D2V,7UG,FZ0,GP0,FT0,AQ0,47K,9JA,ER1,7K3,I43,1G8,4QE,4X4,A00,8VM,QL1,VI6,9P6,N4M,3L5,4A3,0LW,JX0,8Y1,5XC,7Y0,6I3,4KC,FA0,2W0,4I3,9B0,B01,5D1,NT0,QV3,1EX,2Z8,1T3,GA2,Q1G,9ZX,EW0,4GF,2WA,0TD,4ZC,3A1,JS1,VH0,9M3"
></avp-3dws-deck>
Interaction between the page and the app are handled via attributes and events. For more information on this, see the section Configuration of and Communication with Deck
You can start and stop the stream via the active html attribute of the avp-3dws-deck web component. Setting it to true will start a streaming session, setting it to false will stop the running streaming session.
If a client leaves your page, e.g. by closing the browser or switching the page inside a multi page application, the stream will automatically close itself.
Important note for Single Page Applications:
However, if your application is a single page application, the stream will not stop automatically if the component containing the stream is unmounted or destroyed (as long as the client is still within your SPA).
If you do not want to reuse the session once its parent component is unmounted (e.g. by reopening the running stream in another component using the session id), we strongly recommend setting the active property to false when unmounting / destroying the parent component.
Otherwise the stream will continue running in the background and continue consuming resources.
Since the web component and its attributes are not included in the React types for HTML elements and HTML attributes, you might see compile issues when trying to use the component in a react project with typescript. To solve this, you will need to declare the web component as a custom element e.g. in your root component by extending React's IntrinsicElements interface as well as declaring the web components attributes as part of Reacts HTML attributes type (note that the latter is only required for attributes that do not contain a "-"):
type DeckAttributes = HTMLAttributes<HTMLElement> & {
active?: boolean;
"pr-string"?: string;
"camera-flight"?: "disabled" | "enabled";
"config-id": string;
};
declare global {
namespace JSX {
interface IntrinsicElements {
"avp-3dws-deck": DeckAttributes;
}
}
}
Deck is configured via two different resources of config. The first one is a server side JSON configuration file that contains general configuration required to connect to the stream and some additional customization. The second source of configuration are HTML attributes to customize the behavior of the specific instance of the web component. Below, you will find additional information on these configurations.
The stream configuration is a server side json configuration file that contains general configuration for the stream, such as brand, market or stage. Example:
{
"brand": "A",
"service": "3dws",
"market": "DEU",
"streamingStage": "prelive",
"environments": ["ChicagoNight", "Meydan_Dubai_2021"],
"dayEnvironment": "ArtscapeTheatre_Kapstadt_2020",
"nightEnvironment": "Metro_Dubai_2021",
"exteriorCameras": ["MRV1", "MRV4"],
"interiorCameras": ["Interior", "InteriorSide_L0L", "Interior_Rear_View"],
"features": {
"zoom": true,
"cameraFlight": true,
"cameraNavigation": true,
"environments": true,
"interior": true,
"animationSpots": true
}
}
For detailed information on the configuration options available, see the documentation regarding Deck Config.
The deck team provides a couple of test configs that are available for local testing, but are not suitable for production.
See the following list of their IDs:
If you create a custom configuration for your use case, it will have a unique identifier. In either case you will need to provide the config id when using the web component (see below).
The second source of configuration for the deck web component are HTML attributes on the web component element.
While most of these attributes are optional, it is required for you to provide a config-id that corresponds to an existing config on the server side. For details, see Stream Configuration.
For the purposes of tracking, it is recommended to also provide the market. For details see Market Analytics.
Example:
<avp-3dws-deck config-id="audi-test" market="DEU" features='{"zoom": false}' />
For all available HTML attributes to use for customization, see Deck HTML Attributes. Note that some of these HTML attributes can be used to override configurations set via the Stream Configuration.
Generally, there is a selection of UI themes and templates available for different brands and services.
If you are using one of these themes but still want to customize some specific styles, deck exposes a couple of css variables that you can override in order to customize the behavior for your use case. You can do this by adding your customizations as inline styles to your avp-3dws-deck html element.
At this stage, this is mostly useful to override the responsiveness settings of deck, which is implemented to be ideal if the deck web component covers the whole width of the screen by default.
You can adapt the responsiveness behavior of deck by overriding three CSS variables that will be used to define the font-size inside deck, which influences all UI elements and spacing.
These variables are the following:
--deck-fontsize-min: Your minimum desired font-size. Will be used if the preferred font-size would be below this value; default: 11.2px
--deck-fontsize-preferred: The preferred font-size (needs to contain a relative value); default: 5.5px + 0.6vw
--deck-fontsize-max: The maximum font-size. Will be used if the preferred font-size would be above this value; default: 22px
Rule of thumb: if the deck web component covers half of the screen-width in your app, also half the relative part of the --deck-fontsize-preferred variable, thus setting style="--deck-fontsize-preferred: 5.5px + 0.3vw;" on the deck element. On a technical level, these variables will be used as the input for the css clamp function in deck to set the fontsize.
Events are used to enable you to react on certain actions within deck. There is currently two main situations where deck will publish an event:
Informative Events
There are several events informing the integrating page about changes within the app. These events follow the interface CustomEvent All of these events with examples on how to subscribe to them can be found at DeckEvent.
Fatal Error Events
If the app encounters a fatal error during the stream that cannot be handled internally, an ErrorEvent is thrown. This event with an example on how to use it can be found at DeckErrorEvent.
For the purposes of tracking, it is recommended to provide the market as an HTML attribute to Deck in the required ISO alpha-3 format.
If you provide the respective market dynamically for each client, it enables Deck and the streaming backend to provide analytics data on a per-market-basis. As this largely increases the value of the analytics data, we strongly recommend doing this.
If you do not provide the market as an HTML attribute, Deck will instead use the default market defined in the Stream Configuration.
We prepared two pages to demonstrate a possible integration:
curl)Be aware there that are only a limited amount of parallel streams that we can provide for this demo, so if the stream does not start, just try again later.
If you have questions, feedback or feature requests reach out to us via