Skip to content
Swingback, home

Add the widget

Troubleshooting

What to check when the widget doesn't sign your users in, doesn't show, or reports an error. Each problem starts with what you see, then gives its causes and their fixes.

Start with the widget's error code, if it reported one. The SDKs report it in their error event (JavaScript, React, iOS, React Native, Android), and a frame you embed yourself posts an error message. Errors lists every code.

Sign-in#

The widget shows nobody signed in#

People can read the widget, but when they write, it asks them to sign in to your product, or to continue as a guest. If the widget reported an error, find its code below. Without an error, the widget received no token:

  • Your endpoint said nobody is signed in. On the web, the SDKs read { "token": null }, a JSON answer without a token field (such as { "jwt": "…" }), a 401 and a 403 as nobody. With a token function (in an app, or token on the web), it returned null. Check that the endpoint finds your user's session: from the page's cookies on the web, or from the credential your app sends in a mobile app (Hand tokens to the SDKs).
  • Your endpoint is on another origin than your page. On the web, the SDKs send cookies with the token request only to your page's own origin. An endpoint at https://api.example.com, called from a page on https://app.example.com, receives no cookies and sees nobody (without CORS headers that allow your page, the SDK reports token_unavailable instead). Serve the endpoint under your page's origin, such as /feedback-token, or pass a token function that fetches it the way your page calls your API.
  • The SDK has no way to get a token. Without data-token-url on the script tag (or tokenUrl or token in the npm packages), the widget never asks (Script tag options).
  • Your own frame received no token. Your page posts identify after the frame's ready (Sign your user in). If it does and nothing happens, see The frame ignores your page's messages.

To see what your endpoint returns, paste its token into Check a token under Settings → Sign-in (Check a token). It lists every reason the widget would refuse the token, and names the customer it would sign in.

The widget still shows the previous user#

Your app signed someone in or out without a page load, and didn't tell the widget:

  • With an SDK, call identify() after a sign-in and logout() after a sign-out. See your SDK's page: JavaScript, React, iOS, Android or React Native.
  • On the web, a widget embedded in a page doesn't hear those calls, which reach the panel only. Call them on the object embed() returned (Put the widget in your page), or give React's FeedbackWidget a key that changes with your user (A widget in a page).
  • With your own frame, post identify with the new user's token, or with null for nobody, or post logout (When nobody is signed in).

The widget reports invalid_identity_token#

Swingback refused the token. Paste one into Check a token to see why. The usual causes:

  • It expired, or lives too long. exp has passed, or is more than an hour after iat. Sign a new token for each request, valid for a few minutes (The token).
  • Your server's clock is off. Swingback allows 60 seconds of difference between its clock and the token's iat, exp and nbf. Keep your server's clock in sync.
  • It names another workspace or audience. iss must be your workspace's id, ws_…, and aud must be swingback, or an array that contains it.
  • It was signed with the wrong key. The kid header names one of your live secrets, idsec_…, and the token is signed with that secret, si_ prefix included, using HS256. A revoked secret's tokens stop working at once (Identity secrets).
  • A company has no id. Each entry in companies needs an id of at most 255 characters.
  • It's your auth provider's token. See Your auth provider's tokens are refused.

The widget reports another sign-in error#

  • token_unavailable: the SDK couldn't get a token, so it sent none. On the web, your endpoint failed, returned a status other than 2xx, 401 or 403, returned a body that isn't JSON, or returned a token that isn't a string. It must return { "token": "…" }, or { "token": null } for nobody. With a token function, it threw, or returned something that isn't a token: return null for nobody rather than throwing. A token is a non-empty string of at most 16 KB.
  • end_user_conflict: the token's email belongs to another customer, with another id. Swingback finds a customer by sub first, then by email (What a token does). Send the same sub for a person in every token. If two of your accounts share an email, leave email out of one's tokens.
  • validation_failed: the token's email, name, avatar_url or companies aren't valid. Check them against the profile claims.
  • rate_limited: more than 120 sign-ins from one address in 15 minutes. Sign in once per page load, and call identify() only when your user changes. For your auth provider's anonymous users, it also means more new ones than their limits allow.
  • forbidden: the sign-in didn't come through the widget's own page. Trying again won't help.
  • unavailable: Swingback or your auth provider didn't respond. Try again later. If your provider can't be reached when Swingback reads its keys again, the keys it already has keep working.

Your auth provider's tokens are refused#

Under Settings → Sign-in, in Your auth provider, check that the values match your tokens (Sign in with your auth provider):

  • Firebase: the Project id is your Firebase project's, and your app passes the ID token from user.getIdToken().
  • Supabase: the Project URL is your project's, and the project signs its tokens with JWT signing keys rather than its legacy JWT secret. Swingback refuses to save a project that has no signing key.
  • Clerk: the Frontend API URL is your tokens' issuer.
  • Auth0: the Domain is your Auth0 domain, and the Audience matches what your app passes: your application's client id for an ID token, or your API's identifier for an access token for that API.
  • Other (OpenID Connect): the Issuer is your provider's, the Audience is your application's client id, and your app passes an ID token for that application.

A token that lives longer than a day is refused. After your provider starts signing with a new key, its tokens can be refused for up to a minute: Swingback reads the keys again when a token names one it doesn't know, at most once a minute (Your provider's keys). An anonymous user's token signs nobody in where your portal doesn't allow guests (Anonymous users).

Signed in, without a name or an email#

  • Email: Swingback keeps a provider's email only where the token says your provider verified it (email_verified). Supabase's tokens never say this, so they bring no email. To send one, sign your own tokens (Sign tokens in a function).
  • Name: Clerk's session token names the user by their id alone. Add "name":"{{user.full_name}}" to it in Clerk's dashboard, under Sessions → Customize session token.

Single sign-on sends people back to the sign-in page#

The portal refused the token your sign-in page added to return_to (Single sign-on for the portal):

  • The token has no jti, or one the portal has already seen. Single sign-on accepts each token once: sign a new token, with a new jti, for each redirect.
  • The token fails another check. Paste it into Check a token, which lists every reason.

If people land on Finish signing in instead, and must confirm, the portal didn't find the state it started with: your page changed return_to, or signing in took more than 10 minutes, or ended in another browser. Redirect to return_to unchanged, with only the token parameter added, within 10 minutes: otherwise what they wrote as guests doesn't become theirs.

The widget doesn't show#

The frame is blank, or the browser refuses it#

  • Your site isn't in the allowed origins. When Settings → Widget lists allowed origins, browsers refuse to show the widget on any other site, and the browser's console names the frame-ancestors policy. Add your page's origin: scheme, host and port, such as https://app.example.com. https://*.example.com doesn't cover example.com itself. A change takes effect within 30 seconds (Settings).
  • Your page's Content Security Policy blocks it. Allow your portal's address in frame-src, and for the script tag in script-src and connect-src too (Content Security Policy).
  • Your frame's src isn't a widget address. Only the widget's pages can be framed: point the frame at an address under /widget, such as https://acme.w.swingback.dev/widget (Embed the frame yourself).

The frame ignores your page's messages#

For a frame you embed yourself (Messages):

  • Your page posted before the frame was ready. Add your listener before the frame, and post identify when the frame posts ready. A frame that loads again posts ready again.
  • The target origin isn't your portal's. Post to your portal's origin exactly, such as https://acme.w.swingback.dev: the browser drops a message meant for another origin.
  • Your portal's address changed. After an owner changes the slug or a custom domain goes live, the frame follows to the new address, and messages posted to the old one are dropped. Copy your own frame again from Settings → Widget, and update the origin your page posts messages to (Embed the frame yourself).
  • Your page is itself in a frame. Without allowed origins, the widget accepts messages only from the top page of the tab. List your page's origin under Allowed origins, with the origin of every page that frames it: browsers check each one, up to the top of the tab. The widget then accepts your page's messages.
  • The message has no source: "swingback". The widget ignores any message without it.
  • The token isn't a token. The widget ignores an identify whose token isn't null or a non-empty string of at most 16 KB. It ignores undefined too, which an answer without a token field gives: post null for nobody.

The button doesn't appear#

  • The script tag leaves it out. With data-launcher="false", your own control opens the widget. With data-manual, nothing starts until your code calls Swingback.init() (Script tag options).
  • Your page's Content Security Policy blocks the script. Allow your portal's address in script-src, and in connect-src for the button's settings (Content Security Policy).

window.Swingback is undefined#

The script tag loads async, so your own code can run before it. Give the tag an id, and wait for its load event when window.Swingback isn't defined yet (Control it from your code). With data-manual, Swingback.on() does nothing until Swingback.init() has run.

Browsers and devices#

Safari offers to continue on your portal#

Safari before 26.2 doesn't keep the cookies of a frame from another site, so the widget can't keep anyone signed in there. It says so, and offers to continue on your portal in a new tab. There's nothing to change on your page: later versions of Safari and app web views aren't affected (Good to know).

The Android SDK reports webview_unsupported#

The device's WebView is older than version 82, from 2020. The widget still shows, but it can't sign anyone in, so people read, or write as guests where your portal allows them. Once the device's WebView is updated, the SDK signs people in again (Events).

The widget doesn't load in a macOS app#

A sandboxed macOS app needs the Outgoing Connections (Client) capability to reach your portal (Good to know).

A settings change doesn't show#

  • Allowed origins take effect within 30 seconds.
  • Sections and the accent color change the next time the widget loads.
  • The script tag's button (its color and side) can take up to 5 minutes to change, since browsers keep its settings that long.
  • The mobile SDKs read the widget's settings once each time your app starts.

Search pages, sections and code: a setting, an event, a method.