cdn.woku.app) that captures woku ratings (1 to 5) or NPS
scores (0 to 10) directly from your website. You embed it with a
lightweight <script> loader (~2.5 KB gzip) that injects an
<iframe> when a trigger fires; you do not need to load any CSS or
frameworks on your page.
All of the widget’s styles live inside the
<iframe>, in an isolated
document. There is no risk of them clashing with your site’s styles, nor
of your JavaScript interfering with the widget’s.How it works
- Your page loads the loader from
cdn.woku.app. - You call
WokuWidget.init(config)with your configuration. - The loader evaluates the triggers (time, scroll, exit, event,
click) and, when the first one fires, injects an
<iframe>that points to the hosted micro-app. - The micro-app renders the mode based on
captureType(wokushows 1-5 stars;npsa 0-10 scale;cesandcsata 1-5 scale with the tool’s question), captures the feedback, and sends it to the woku API. - The loader emits events (
open,submit,close,skip) that you can listen to withWokuWidget.on(...).
Installation
1
Get your publishable key
In the admin application, go to Company → Integrations and copy
the publishable key (
pk_...). It is safe to embed in your
site’s public HTML.2
Paste the loader into your site
Place this snippet before
</body> on the pages where you want to
show the widget.3
Verify
Open your site and wait for the trigger to fire (in the example, 5
seconds). The widget will appear as a modal.
Authentication: publishable key
The widget authenticates with your company’s publishable key, sending it in thex-woku-key header of every capture. Unlike the secret key
(used by server-side integrations), the publishable key:
- Starts with the
pk_prefix (e.g.pk_live_...). - Is safe to embed in public HTML.
- Only has capture permission (it does not read or manage resources).
Configuration
The object you pass toWokuWidget.init(...) accepts these fields:
Capture type: woku, NPS, CES and CSAT
- woku (1-5 stars)
- NPS (0-10)
- CES and CSAT (1-5)
Captures a rating of 1 to 5 stars associated with a In
wokuId.woku mode the user sees 1-5 stars and, optionally, leaves a
comment as text or audio.Language (i18n)
The widget includes two languages: Spanish (es, default) and
English (en). The language is resolved in this order:
- The
langfield of the configuration. - The browser language (
navigator.language). - Fallback to
es.
- Spanish
- English
- Auto-detection
Triggers
Each trigger defines when the widget appears and how it is presented (behavior). You can combine several; the first one that is
met fires.
Presentation modes (
behavior): modal (centered window with overlay),
banner (fixed bar), side-tab (side tab), and fullscreen (full
screen).
Theme
Customize the widget’s appearance. The values are applied as CSS custom properties inside the iframe (exceptzIndex, which controls the overlay
on your page):
Programmatic API
The loader exposeswindow.WokuWidget:
open fires whenever the panel opens, by a click or by itself (modal,
fullscreen or startOpen), and again when the person rates again. After submit, the thank-you step stays on
screen for 10 seconds before the widget folds away. A person identified by
email or dispatchToken is not offered to rate again, so their answer is
not duplicated.
CSP requirements
If your site uses Content-Security-Policy, you must allow the CDN origin both for the loader script and for the micro-app iframe:The loader is loaded as an external
<script src="..."> and does not
use eval or inline scripts, so you do not need to configure a nonce
or unsafe-inline.allow="microphone").
If your site sends a Permissions-Policy header, it must also delegate it to
the widget origin, for example microphone=(self "https://cdn.woku.app").
Without it, text still works and audio is unavailable.
Troubleshooting
The widget does not appear
The widget does not appear
- Confirm that some trigger is met (for example, wait out the
seconds of a
timetrigger). - Check the browser console: CSP errors indicate that you are missing
permission to allow
cdn.woku.appinscript-srcorframe-src. - Verify that
companyIdandpublishableKeyare correct.
401 error when sending feedback
401 error when sending feedback
The
publishableKey is invalid or does not correspond to the
companyId. Copy it again from Company → Integrations.Nothing loads in woku mode
Nothing loads in woku mode
wokuId is missing, which is required when
captureType === 'woku'.The iframe looks cut off on mobile
The iframe looks cut off on mobile
The widget adjusts its height automatically via
postMessage. If
your site applies overflow: hidden or a transform to the
<body>, it may interfere with the overlay. Use
behavior: 'fullscreen' as an alternative.Capture provenance
Since version0.3.0 (npm and CDN), WokuWidget.init accepts collectionKind and
flowId. New Woku/NPS captures default to standalone. An external
Flow must send collectionKind: 'flow' and its actual ID. The loader,
postMessage, configuration and text/audio bodies preserve the context,
including NPS creation and later comments. Changing provenance starts a new
evaluation so comments cannot attach to a different response.
A Flow response does not activate follow-up, even for a single-step or
incomplete Flow; it may create its normal ticket. An individual Journey
instrument stays standalone if it does not belong to a Flow. The widget still
captures Woku/NPS and does not show support conversations.