ClientSphereDocs

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:

npm install @clientsphere/support-native

socket.io-client is only needed for the chat side; the launcher makes plain HTTP calls.

Minimal app

import AsyncStorage from '@react-native-async-storage/async-storage';
import { LauncherProvider, SupportLauncher } from '@clientsphere/support-native';
 
export function App({ user }) {
  return (
    <LauncherProvider
      baseUrl="https://clientsphere.io"
      companyId="your-workspace-id"
      storage={AsyncStorage}
      identity={user ? { email: user.email, name: user.name } : null}
    >
      <YourNavigator />
      <SupportLauncher />
    </LauncherProvider>
  );
}

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:

CardAppears whenDoes
Send us a messageLive chat is onOpens the conversation. Takes the top card ahead of the ticket form
Send us a messageLive chat is off and tickets are onOpens the ticket form. The subtitle is the inbox's reply-time promise, from its SLA
Search for helpThe knowledge base is onOpens live search over public articles
Popular articlesThe knowledge base is on and has public articlesThe three most-read, then "Find answers" for the full browser
MoreAny other menu itemsSuggest 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:

<LauncherProvider
  identity={{ email: user.email, name: user.name, userHash: user.launcherHash }}
  …
/>

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:

import * as ImagePicker from 'expo-image-picker';
 
<SupportLauncher
  onPickAttachment={async () => {
    const r = await ImagePicker.launchImageLibraryAsync({ quality: 0.8 });
    if (r.canceled) return null;
    const a = r.assets[0];
    return { uri: a.uri, name: a.fileName ?? 'screenshot.jpg', type: a.mimeType ?? 'image/jpeg', size: a.fileSize };
  }}
/>

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

PropDefaultMeaning
showPilltrueRender the floating pill. Set false to open the sheet from your own control with useLauncher().setOpen(true)
positionconfigured positionbottom-right or bottom-left
pillInset20Distance from the screen edges
avatarsnoneTeam 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?"
logoTextfirst letter of the labelThe tile in the header
onOpenLinkLinking.openURLWhere link items and "Open in the help centre" go
renderArticleplain textRender an article body yourself, for example with an HTML renderer
onPickAttachmentnoneAsync 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

const { config, items, replyTime, client, open, setOpen } = useLauncher();
 
const home = await client.kbHome();               // categories and popular articles
const cat = await client.kbCategory(id);
const article = await client.kbArticle(id);
const hits = await client.kbSearch('refunds');
await client.submitTicket({ subject, message, email, name });
await client.submitFeatureRequest({ productCategory, urgency, title, description });

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

ActionLimit
Messages (tickets)10 per hour, per workspace, per IP address
Identify60 per minute per IP; the SDK sends one per six hours per email
SearchQueries under two characters return nothing without a request

Launcher or chat?

Floating launcherChat screen
ComponentSupportLauncher in LauncherProviderSupportChatScreen in SupportProvider
Keyed byWorkspace id, or a widget idWidget id
Live conversationYes, when the workspace turns it onYes, always
ShapeA pill and a sheet over your appA full screen you navigate to
Knowledge baseBrowse, search and readSearch
TicketsYes, "Send us a message"Email tickets from the hub
Configured underCustomer Support → Floating LauncherCustomer Support → Support Hub

Both can live in one app. They do not share state; identify the user in both if you use both.

On this page