FAQ & Troubleshooting

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.

<script
  async
  type="text/javascript"
  src="//asset.fwcdn3.com/js/fwn-async.js"
></script>

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:

<fw-embed-feed
   channel="your-channel"
   mode="grid"
>
   <div slot="grid-row-1">
     <!-- This is a portal for content in element with attribute slot="grid-row-1" to the first row in grid -->
   </div>
   <div slot="grid-row-2">
     <!-- Any html code here will be transported to 2st row, etc. -->
   </div>
</fw-embed-feed>

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.

pageTelemetry console

Feed is not showing up

Embed feed might be temporary in sandbox mode. To make sure, use debug_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 MacOS Control+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:

<amp-iframe src="https://fireworktv.com/embed/amp-iframe?amp=1&channel=your-channel&open_in=_blank&page_url=CURRENT_PAGE_URL"></amp-iframe>

Example with custom iframe.html

<iframe src="iframe.html">
   /* Content of iframe.html */
   <fw-embed-feed channel="your-channel" page_url="CURRENT_PAGE_URL"></fw-embed-feed>
</iframe>

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.

--fw-player-height
--fw-player-width

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.

PreviousFirework Service Domains NextIntegration Guide

Last updated 17 days ago