Floating launcher
The floating launcher in a React Native app, Intercom style, driven by the settings under Customer Support → Floating Launcher.
The floating launcher is a pill in the corner of the screen. Tap it and a sheet slides up with the menu your workspace configured: a live conversation, the knowledge base, a message that becomes a ticket, suggest an improvement, and any links you added.
It is the same feature as the web launcher. The label, colour, position, menu items, and which of the knowledge base and tickets are on all come from Customer Support → Floating Launcher, and the ticket lands on the same support inbox.
Install
The launcher ships in the same package as the chat SDK:
socket.io-client is only needed for the chat side; the launcher makes plain
HTTP calls.
Minimal app
Put SupportLauncher last inside a full-screen parent so the pill floats over
everything. Find the workspace id under Customer Support → Floating
Launcher; a Support Hub widget id works too, as widgetId.
With an email in identity, the workspace creates or links a contact the
first time the launcher loads, and again at most once every six hours. That
is what the web launcher does on page load. Pass storage so the throttle
survives restarts. Add identity.userHash (see Your tickets)
so the identity counts as verified; an unsigned email creates less.
What the sheet shows
Home opens with a brand-coloured header and a greeting, then:
| Card | Appears when | Does |
|---|---|---|
| Send us a message | Live chat is on | Opens the conversation. Takes the top card ahead of the ticket form |
| Send us a message | Live chat is off and tickets are on | Opens the ticket form. The subtitle is the inbox's reply-time promise, from its SLA |
| Search for help | The knowledge base is on | Opens live search over public articles |
| Popular articles | The knowledge base is on and has public articles | The three most-read, then "Find answers" for the full browser |
| More | Any other menu items | Suggest an improvement, and links, which open in the system browser |
Menu items follow the web launcher's rules exactly: a link with no URL is hidden, knowledge base and ticket rows disappear when the feature is off, and a ticket row is added if tickets are on but the workspace never listed one.
With live chat on, two more rules apply. A conversation row is added at the top if the workspace never listed one, and the ticket row is renamed to Email us so two rows do not both read "Send us a message". A label you chose yourself is never rewritten.
The header colour is the launcher colour. The sheet follows the launcher's theme setting, or the phone's appearance when the setting is "auto".
Live chat
Turn it on under Customer Support → Floating Launcher and pick which Support Hub widget the conversation runs on. Until then the sheet behaves exactly as it did before, and nothing in your app changes.
When it is on:
- The top card opens a conversation in the same sheet, answered by your team and, if the widget has it, the AI assistant.
- Past conversations are behind the icon in the conversation header. Opening one shows its full transcript, closed ones included.
- A new conversation can only be started when nothing is still open. While an open conversation exists the option is hidden, and anything that would have created one takes the visitor back to the open thread instead.
- A badge appears on the pill when a reply arrives and you are not looking at the conversation.
The session is dormant until someone opens chat. An app that mounts the launcher at its root opens no websocket for the many visitors who never ask for support. Once opened it stays connected for the rest of the app session, which is what lets the badge appear while the sheet is closed.
There is no push yet, so the badge only works while the app is open. A reply that lands after someone leaves the app is silent until they come back.
Everything the chat screen does is
available here through the same hooks, since the launcher composes the same
provider. You do not need SupportProvider yourself unless you also want a
full-screen chat elsewhere in the app.
Home, Messages and Help
With both a way to write in (chat or tickets) and a knowledge base, the sheet
gets a bar of three tabs at the bottom: Home (greeting, conversation
card, search into Help, popular articles, your own rows), Messages (every
conversation and ticket in one list, newest first, with the two ways to start
one at the top and the unread count) and Help (the knowledge base at full
height). Each tab keeps its own stack, reopening restores the last tab and
screen, and a reply that arrived while the sheet was shut opens it onto
Messages. The bar hides while a composer or form is on screen so the
keyboard has the room, and it is announced as a tab list with the unread
count in the Messages label. A workspace with only one section keeps the
single list. The rule is launcherTabs(config) in the core package.
Your tickets
With tickets on, the sheet has a Your tickets row listing the visitor's tickets with a status, a reference and their own messages.
What it lists depends on identity. With no identity, or an identity without a
signature, it shows the tickets raised from this device, and says so. To show
a person's tickets across every device, sign their email on your server with
the workspace's identity secret and pass it as identity.userHash:
Generate the secret under Customer Support → Floating Launcher → Verified visitor identity. The signature is HMAC-SHA256 of the lower-cased, trimmed email, hex encoded, computed on your server and never in the app; the settings page shows the exact code. A wrong or missing signature just gets the per-device view, and rotating the secret invalidates every signature until your app ships with the new one.
From SDK 0.3.0 the same userHash covers every write the launcher makes, not
only ticket reads: the identify call on load, the live chat session, the
ticket from the message form and the suggestion from the feature-request form
all carry it. The forms attach it only while the email in the form is still
the one you signed. A visitor with a valid hash is verified and gets
today's behaviour. An unverified one can still be matched to a contact by
email (unless the workspace has Require verified identity on, in which
case no contact is created or linked at all), but never changes an existing
contact's name or company, never creates or links an account, and on an
Account-Based chat channel is routed to the fallback pool. The details are
under Identity and sessions.
The ticket screen has a composer. A reply lands in your inbox as an emailed
reply from the same contact would, restarts an idle SLA clock and reopens a
resolved ticket. On the client it is client.replyToTicket(id, text, scope).
Agent replies reach the app the next time the ticket is opened; there is no
live socket for tickets.
Replies reach the app first. When an agent answers a ticket raised from the launcher, the reply is pushed over a socket: an open ticket updates in place, and otherwise the pill and Your tickets show a count and the ticket says New reply. The email goes out only if the person has not looked at the reply within five minutes, and several waiting replies go as one email. Opening the ticket, or replying from it, means no email for those replies. Tickets that arrived by email still email every reply at once.
The socket opens only once the install has raised a ticket, or the identity
carries a userHash, so an app that mounts the launcher at its root opens
nothing for people who never ask for support. It is dropped in the
background and rebuilt on foreground, like the chat socket. There is no push
notification: someone who closes the app relies on the email. With the hooks,
useLauncher() exposes ticketUnread, onTicketReply, markTicketSeen
and noteTicketsExist; the client has markTicketSeen(id, scope).
Screenshots. Pass onPickAttachment and both the message form and the
ticket composer get an attach button. Return a file from whichever picker you
use, or null if the person cancelled:
Images and PDFs only, 5 MB each, five per message. Each file is uploaded as
soon as it is picked, and the ticket or reply then carries the handle. Files
on a message come back with a link that lasts as long as the ticket, safe to
put straight into an Image, and the screen shows images inline. On the client the pieces are
client.uploadTicketAttachment(file, scope), attachments on submitTicket,
and client.replyToTicket(id, { message, attachments }, scope).
Statuses a customer sees are In progress, Waiting on you and Resolved. The assignee, priority, SLA and internal notes are never sent.
Props
| Prop | Default | Meaning |
|---|---|---|
showPill | true | Render the floating pill. Set false to open the sheet from your own control with useLauncher().setOpen(true) |
position | configured position | bottom-right or bottom-left |
pillInset | 20 | Distance from the screen edges |
avatars | none | Team avatars on the message card: [{ initials, color? }]. The public config carries no team, so the app supplies them |
greeting | "Hi there 👋" | Line above "How can we help?" |
logoText | first letter of the label | The tile in the header |
onOpenLink | Linking.openURL | Where link items and "Open in the help centre" go |
renderArticle | plain text | Render an article body yourself, for example with an HTML renderer |
onPickAttachment | none | Async function returning a file or null. Adds an attach button to the message form and the ticket composer; without it there is none |
Articles
Articles come back as the HTML written in the workspace editor. By default the
launcher flattens it to readable text, with headings, paragraphs and bullet
lists preserved, so nothing untrusted is rendered as markup. To show full
formatting, pass renderArticle and hand the HTML to a sanitising renderer
such as react-native-render-html.
Reading an article in the app counts as a read on the help centre, the same as the web launcher.
Using the hooks and client directly
items is the menu after visibility rules. replyTime is the sentence the
message card shows. Every failure is a SupportApiError; see
Lifecycle and limits.
Limits
| Action | Limit |
|---|---|
| Messages (tickets) | 10 per hour, per workspace, per IP address |
| Identify | 60 per minute per IP; the SDK sends one per six hours per email |
| Search | Queries under two characters return nothing without a request |
Launcher or chat?
| Floating launcher | Chat screen | |
|---|---|---|
| Component | SupportLauncher in LauncherProvider | SupportChatScreen in SupportProvider |
| Keyed by | Workspace id, or a widget id | Widget id |
| Live conversation | Yes, when the workspace turns it on | Yes, always |
| Shape | A pill and a sheet over your app | A full screen you navigate to |
| Knowledge base | Browse, search and read | Search |
| Tickets | Yes, "Send us a message" | Email tickets from the hub |
| Configured under | Customer Support → Floating Launcher | Customer Support → Support Hub |
Both can live in one app. They do not share state; identify the user in both if you use both.