FAQ & Troubleshooting (Web)
Performance
In case your page uses multiple widget components, insert <script>
tag with combined fwn.js
file instead of requesting each js file individually.
Example:
<script
async
src="//asset.fwcdn3.com/js/fwn.js"
type="text/javascript"
></script>
At Firework, we always strive for perfection regarding providing tools that will not negatively affect web page performance. Here are some examples of how we do that:
Custom web components with Shadow DOM to let the browser decide when and how to render.
Optimized javascript bundle with less than 150kB footprint.
Usage of worldwide CDNs, to provide the best delivery times to users in any geolocation.
AWS Global Accelerator to achieve fastest network path to our API's
Usage of modern performant Javascript APIs like IntersectionObserver or ResizeObserver while providing polyfills for older browsers compatibility.
Leverage client-side Local Storage APIs to cache network calls.
Use of navigator.sendBeacon for low priority tracking requests.
Modern WEBP and H.265 media formats where applicable with fallback for legacy browsers.
Lazy load components for language localization and video playback.
Even though we are actively monitoring end-user performance using custom RUM analytics, here are some tips to minimize Fireworks’ impact while sacrificing some features.
Using
autoplay="false"
feature flag to disable autoplay will minimize the amount of javascript code loaded and omit video file loading.Putting
<script>
tag at the end of the page will prioritize other dynamic content on-page while Firework will be loaded and rendered last. Putting<script>
into<head>
on the other hand will prioritize Firework widgets.
Asynchronous load
In case your page relies on very fast first load, you can inject the async script (fwn-async.js ~1kB). It defer loads the main script until the widget components is visible in viewport.
Please note that this feature only works on browsers that support IntersectionObserver. The individual widget components needs to be placed into your HTML structure where they should be rendered during the server side render.
Display ad ingestion
It is possible to insert a display ad related html between embed feed rows in grid
mode. Any element with attribute slot="grid-row-{index}"
will be transported inside grid to appropriate row. Slotted elements have css property grid-column: 1 / -1
to occupy full row.
Example:
Feed is slow
Feed might appear slow when integrated on javascript heavy websites. In case you want to prioritize feed render before other content, add <script>
part of code snippet to page <head>
.
Try our telemetry console to get some insight to render performance.
Feed is not showing up
Embed feed might be temporary in
sandbox
mode. To make sure, usedebug_fwn=true
as a querystring param in your url to bypass sandbox. For example:https://my-page.com/?&debug_fwn=true
Check for possible syntax errors. In Google Chrome open console panel using shortcuts and search for red flags.
Command+Option+J
for MacOSControl+Shift+J
on Windows
Picture in picture mode is failing
Video player does not work in PIP mode. Returns to full screen instead.
Firework’s Picture in Picture feature uses original page in an iframe. The Content-Security-Policy HTTP header with frame-ancestors and frame-src directive is needed so the page can be iframed by itself using the iframe within the same origin. This can be achieved by CSP HTTP header.
HTTP header value:
Content-Security-Policy: frame-ancestors 'self'; frame-src 'self'
X-Frame-Options: SAMEORIGIN
Please note, x-frame-options is obsolete and should be only used in case you want to support older browsers. Some html meta configuration might
Invalid referrer attribution
In case you see fireworktv.com
or fireworktv.com/embed/amp-iframe
as a referrer urls in your data insights, please follow next advice.
Problem occurs in all embed feed integrations placed into <iframe>
, including <amp-iframe>
which limits Firework code properly read current page url. Solution lies in making sure iframe src includes page_url
attribute with current page url. In case you are wrapping Firework code into iframe on your own, add page_url
attribute with proper location.href
value similar to other attributes in your integration.
Example with <amp-iframe>
, see CURRENT_PAGE_URL
:
Example with custom iframe.html
Video opening in new tab/window
Some integrations which rely on iframes (AMP, Google Ad Manager) won't be able to display full page video by nature of iframe. Widgets inside iframe ignore open_in
attribute and open all videos in new browser tab.
Docked Storyblock scrolling with content
If you find out, that Storyblock's docked player is scrolling with content instead of being fixed in the corner, the problem is that widget is wrapped in DOM element which is using transform
. CSS Transform creates new coordinate system.
To fix this issue, you have two options:
remove CSS transform from ancestor elements
if you can't remove CSS transform, you can try to set
reset_transform="always"
. This will temporarily remove any ancestor transforms when floating or fullscreen player is opened
If none of the above options works for you, you should move widget to place where no ascending elements have CSS transform or use widgets, which are not affected by this behaviour, ie. Pinned Storyblock or Grid/Carousel
Limitations of <iframe> integration
<iframe>
integration, where Firework widget lives inside any kind of HTML iframe, provides a way of separation from main page content and is available in most CMS. However, there are some drawbacks that are hard to overcome:
fullscreen player is not available, video is opened in a new tab on fw.tv (see
open_in
attribute)picture in picture experience is not available
attributing tracking events to a user is not reliable across browser sessions (short lifespan of browser storage)
current page url is not accessible from within the iframe and affects tracking (see the usage of
page_url
attribute)
Double Click / FastClick Issue
If you find that, double click is required on our web components to use it, it could probably be due to a library already in use by the website called Fastclick. It is a library, which was needed to remove a 300ms delay for touch events on legacy mobile browsers. This is no longer needed since 2015 as the browsers got improved and it can cause unexpected issues like this.
To resolve this, the best solution is to remove the Fastclick plugin from the website. Quoting the note on FastClick library page
As of late 2015 most mobile browsers - notably Chrome and Safari - no longer have a 300ms touch delay, so fastclick offers no benefit on newer browsers, and risks introducing bugs into your application. Consider carefully whether you really need to use it.
But if removing Fastclick is not an option, you can resolve this issue by adding class="needsclick" to Firework Widgets.
Floating player size on mobile is too large
The current default size is set up to support IAB video ad units in the floating player. Making it any smaller will cause the ads to not work in floating player.
If you don't want ads in floating player then you will be able to set the size of the player to any specification you want using the following CSS variables.
For the full list of styling variables and attributes refer to this section.
You can have different sized floating players for desktop and mobile using media queries.
Last updated