SDK mobile

Gli SDK mobile sono l’equivalente del widget web per le tue app: i tuoi clienti ricevono supporto in-app con lo storico completo delle conversazioni e le notifiche push, e i tuoi agenti vedono quelle conversazioni nella stessa Posta in arrivo. Non sono app per gli agenti del tuo team; quelle sono una linea di prodotti separata.

Piattaforme

Piattaforma	Linguaggio e runtime	Distribuzione	Stato
iOS	Swift 5.9+, iOS 15+	Swift Package Manager, CocoaPods	in sviluppo
Android	Kotlin 1.9+, Android 8.0 (API 26)+	Maven Central	in sviluppo
React Native	basato sugli SDK nativi	npm	pianificato (beta)
Flutter	basato sugli SDK nativi	pub.dev	pianificato (beta)

Gli SDK nativi sono il riferimento; i wrapper escono dopo di loro. Le app per smartwatch o TV e gli SDK desktop sono fuori ambito; per il desktop usa il widget web.

Cosa include l’SDK

Messaggi di testo, allegati, messaggi vocali, immagini e video, sessioni anonime e identificate, temi, avatar e branding personalizzati, 40 lingue, l’AI concierge, storico delle conversazioni, badge dei non letti, notifiche push, deep link, click-to-call tramite il tastierino del telefono, coda offline con sincronizzazione in background, sblocco biometrico della chat, supporto per VoiceOver e TalkBack, modalità scura. Dimensione compilata obiettivo: 5 MB o meno per piattaforma.

Le chiamate WebRTC in-app e la condivisione dello schermo da parte del cliente arriveranno in una release successiva. Il cobrowse è solo web: i sistemi operativi mobili non consentono a un SDK di terze parti di osservare o controllare lo schermo.

Superficie dell’SDK

Inizializza una sola volta, presto nel ciclo di vita dell’app:

// iOS
let config = RolChatConfig(
  siteId: "site_abc123",
  apiKey: "pk_live_…",      // public key - safe to ship in the app
  region: .eu,              // eu / us
  theme: RolChatTheme(primaryColor: .blue)
)
RolChat.shared.initialize(config: config)

// Android
val config = RolChatConfig.Builder()
  .siteId("site_abc123")
  .apiKey("pk_live_…")
  .region(Region.EU)
  .theme(RolChatTheme(primaryColor = Color.Blue))
  .build()
RolChat.initialize(context, config)

Identifica l’utente dopo l’accesso e disconnettilo quando esce:

RolChat.shared.identify(userId: "user_12345", email: "alice@example.com", name: "Alice",
                        metadata: ["tier": "gold"])
RolChat.shared.logout()   // on host-app sign-out, or the next user sees this history

Mostra l’interfaccia:

RolChat.shared.openChat()                      // modal
RolChat.shared.openChat(conversationId: id)    // a specific conversation
RolChat.shared.openChatInline(view)            // inside your own layout
RolChat.shared.close()

Callback: rolChatDidOpen, rolChatDidClose, rolChatDidReceiveMessage(_:), rolChatDidFailToSend(_:). L’API pubblica è sicura sul main thread su iOS e sui thread in background su Android; le connessioni si interrompono quando l’app passa in background e riprendono quando torna in primo piano.

Sessioni e identità

• Anonima: un ID di sessione del dispositivo, salvato nel portachiavi o nelle preferenze cifrate, sopravvive agli aggiornamenti dell’app ed è legato al dispositivo, non all’utente. Viene eliminato dopo 90 giorni di inattività.
• Identificata: dopo identify, la sessione viene promossa e unita allo storico anonimo sullo stesso dispositivo quando non c’è ambiguità. La risoluzione dell’identità tra canali segue le regole del grafo delle identità e il consenso.
• Identificazione attendibile: il tuo backend firma un token con i claim dell’utente; l’SDK lo trasmette e RolChat verifica la firma prima di promuovere la sessione. Un identify non firmato funziona, ma con un livello di fiducia inferiore.

La chiave API pubblica nell’app è sicura per progettazione: è limitata al sito e soggetta a limiti di frequenza.

Notifiche push

Piattaforma	Trasporto	Cosa fornisci
iOS	APNs	Una chiave di autenticazione APNs nella dashboard di RolChat
Android	FCM	Il JSON dell’account di servizio FCM

RolChat.shared.setPushToken(deviceToken, type: .apns)
if RolChat.shared.handleNotification(userInfo) { return }   // consumed: a chat message

Il testo delle notifiche viene localizzato lato server nella lingua dell’utente. Le notifiche avanzate supportano avatar, risposta dalla notifica e segna come letto. L’SDK non chiede mai da solo il permesso per le notifiche push; chiama requestPushPermission() quando è opportuno nel tuo onboarding. La disattivazione avviene con setPushEnabled(false) o dalle impostazioni del sistema operativo; entrambe vengono registrate.

Versioni e supporto

Versionamento semantico rigoroso. Sono supportate due versioni major alla volta, con un anno per migrare dopo una release major. Le release minor sono mensili; le correzioni di sicurezza escono subito; le release major vengono annunciate con tre mesi di anticipo. Un SDK deprecato o non supportato registra un avviso all’avvio e la dashboard lo segnala in Integrazioni.

Privacy

Nessun tracciamento oltre a quello che attivi, le schermate di consenso usano i modelli nativi della piattaforma, e le richieste degli interessati ai sensi di GDPR, CCPA e LGPD coprono le sessioni dell’SDK come qualsiasi altro canale. Gli allegati vengono compressi sul dispositivo, caricati su URL firmati e sottoposti a scansione antivirus prima che gli agenti li vedano.