Guide e tutorial

Come aggiungere una chat di assistenza nativa alle tue app iOS e Android

Aggiungi una chat Helpium nativa alle tue app iOS e Android in un pomeriggio: la tua IA risponde subito, il tuo team subentra quando serve e le risposte arrivano come notifiche push.

Maximiliano Monge

Maximiliano Monge

Founder & editor at Helpium. Writing about AI-powered custom...

· 7 min
Come aggiungere una chat di assistenza nativa alle tue app iOS e Android

I tuoi clienti chiedono aiuto dove si trovano già: dentro la tua app. Mandarli su un sito web o a un indirizzo email aggiunge attrito proprio nel momento peggiore. Con gli SDK mobile di Helpium aggiungi una chat di assistenza nativa alle tue app iOS e Android in un pomeriggio. Il tuo agente IA risponde subito, il tuo team subentra quando serve e ogni conversazione finisce nella stessa Posta in arrivo di Helpium della chat web, dell'email e di WhatsApp.

Chat Helpium su iOS, pronta per il primo messaggio
La chat si apre pronta per scrivere, con il tuo messaggio di benvenuto e le risposte immediate.

Cosa ottieni

  • Una chat nativa, non una web view. SwiftUI su iOS, viste native su Android. Sembra parte della tua app.
  • Il tuo agente IA incluso. Le stesse conoscenze, procedure e azioni IA che hai configurato per il web rispondono dentro l'app.
  • Un passaggio pulito. Il cliente tocca “Parla con una persona” e il tuo team risponde dalla Posta in arrivo in tempo reale.
  • Notifiche push. Le risposte degli agenti raggiungono il cliente anche con l'app chiusa.
  • Il tuo brand. Ogni colore, in modalità chiara e scura, e ogni testo, in ogni lingua.

Prima di iniziare: trova le tue chiavi in Helpium

Tutto ciò che serve all'integrazione si trova in una sola pagina del tuo workspace Helpium: Settings → Live Chat. Gli SDK mobile fanno parte del canale Live Chat, quindi le conversazioni della tua app seguono le stesse regole di IA, passaggio a una persona e orari di lavoro della chat del tuo sito.

La widget key si trova in Installation. Identifica il tuo workspace ed è pensata per essere pubblica: va dentro la tua app, proprio come va nell'HTML del tuo sito. Copiala con il pulsante Copy.

Il campo Widget key in Helpium, nelle impostazioni di Live Chat
Settings → Live Chat → Installation: la widget key va nella tua app.

L'identity secret si trova in Customer identification. Clicca su Show o Copy. Questo è privato: conservalo sul tuo server, come variabile d'ambiente, insieme agli altri segreti. Non metterlo mai nell'app, nel controllo di versione o in una pagina web. Chiunque lo avesse potrebbe accedere come uno qualsiasi dei tuoi clienti. Se dovesse trapelare, clicca su Regenerate e aggiorna il tuo server.

Il campo Identity secret in Helpium, nascosto, con i pulsanti Show, Copy e Regenerate
Settings → Live Chat → Customer identification: l'identity secret resta sul tuo server.

Le credenziali push si collegano più in basso nella stessa pagina, in Mobile apps. Ti servono solo per le notifiche, quindi puoi tornarci al passo 4.

La sezione Mobile apps in Helpium con i pulsanti Connect per iOS e Android
Settings → Live Chat → Mobile apps: collega Apple e Firebase per inviare notifiche push.

Passo 1: firma l'identità dei tuoi utenti sul tuo server

Quando un cliente ha effettuato l'accesso alla tua app, il tuo backend dice a Helpium chi è firmando un breve token con l'identity secret. La sua conversazione lo segue su tutti i dispositivi, la chat evita di chiedergli nome ed email e le azioni IA possono operare in sicurezza sul suo account. A Helpium non importa in che linguaggio sia scritto il tuo backend: il token è un JWT standard e ogni linguaggio ha una libreria per gestirlo.

Il token è un JWT firmato con HS256, che usa l'identity secret come chiave. Il suo payload contiene:

  • user_id: il tuo id per l'utente, come stringa. Usa questo o email, meglio ancora entrambi.
  • email: l'email dell'utente.
  • exp: quando scade il token, in secondi Unix. Obbligatorio. Un'ora è più che sufficiente.

JSON

{
  "user_id": "42",
  "email": "jane@example.com",
  "exp": 1767225600
}

Aggiungi un endpoint richiamabile solo dagli utenti autenticati, per esempio GET /api/helpium-token, che costruisce questo token per l'utente corrente e lo restituisce. La tua app lo chiama dopo il login e passa il risultato all'SDK. Ecco la parte di firma in alcuni stack comuni; qualsiasi libreria JWT che supporti HS256 funziona allo stesso modo.

Node.js

// npm install jsonwebtoken
const jwt = require('jsonwebtoken');

const token = jwt.sign(
  { user_id: String(user.id), email: user.email },
  process.env.HELPIUM_IDENTITY_SECRET,
  { algorithm: 'HS256', expiresIn: '1h' }
);

Python

# pip install pyjwt
import os, time, jwt

token = jwt.encode(
    {"user_id": str(user.id), "email": user.email, "exp": int(time.time()) + 3600},
    os.environ["HELPIUM_IDENTITY_SECRET"],
    algorithm="HS256",
)

PHP

// composer require firebase/php-jwt
use Firebase\JWT\JWT;

$token = JWT::encode([
    'user_id' => (string) $user->id,
    'email' => $user->email,
    'exp' => time() + 3600,
], getenv('HELPIUM_IDENTITY_SECRET'), 'HS256');

Ruby

# gem install jwt
require 'jwt'

token = JWT.encode(
  { user_id: user.id.to_s, email: user.email, exp: Time.now.to_i + 3600 },
  ENV.fetch('HELPIUM_IDENTITY_SECRET'),
  'HS256'
)

Java

// io.jsonwebtoken:jjwt-api + jjwt-impl + jjwt-jackson
String token = Jwts.builder()
    .claim("user_id", String.valueOf(user.getId()))
    .claim("email", user.getEmail())
    .expiration(new Date(System.currentTimeMillis() + 3_600_000))
    .signWith(Keys.hmacShaKeyFor(System.getenv("HELPIUM_IDENTITY_SECRET").getBytes(StandardCharsets.UTF_8)), Jwts.SIG.HS256)
    .compact();

Nessun login nella tua app? Salta questo passo. La chat chiede nome ed email prima del primo messaggio.

Passo 2: aggiungi la chat alla tua app iOS

L'SDK iOS è un Swift Package (iOS 15+, nessun'altra dipendenza). In Xcode scegli File → Add Package Dependencies, incolla https://github.com/helpium-io/helpium-sdk e aggiungi il prodotto Helpium. Poi:

Swift

import Helpium

// At launch
Helpium.configure(widgetKey: "YOUR_WIDGET_KEY")

// After login, with the token from your server
Helpium.identify(userJwt: token)

// From your Help button
Helpium.present()

Una conversazione nella chat Helpium per iOS, con risposte dell'IA e di un agente
Risposte dell'IA, un link dal tuo centro assistenza e una risposta del team, raggruppati come in una chat nativa.

La chat si apre direttamente sulla conversazione aperta del cliente. Mentre qualcuno sta scrivendo, il cliente lo vede, insieme allo stato dell'IA mentre cerca un'informazione.

Indicatore di scrittura nella chat Helpium per iOS
Puntini di scrittura mentre l'IA o un agente sta scrivendo.

Passo 3: aggiungi la chat alla tua app Android

L'SDK Android supporta Android 5.0 e successivi e funziona allo stesso modo da Java e Kotlin. Usa le normali viste Android, quindi si adatta a progetti vecchi e nuovi senza aggiungere androidx o Compose. Aggiungi JitPack e la dipendenza:

Gradle

// settings.gradle
maven { url "https://jitpack.io" }

// app/build.gradle
implementation "com.github.helpium-io:helpium-sdk:0.1.0"

Poi, nel tuo codice:

Java

// Application.onCreate()
Helpium.configure(this, "YOUR_WIDGET_KEY");

// After login, with the token from your server
Helpium.identify(token);

// From your Help button
helpButton.setOnClickListener(v -> Helpium.present(this));

Una conversazione nella chat Helpium per Android
La stessa chat su Android, costruita con viste native.

Usi React Native o Expo?

Il pacchetto @helpium/react-native avvolge entrambi gli SDK nativi, così ottieni la stessa chat nativa da JavaScript. Con Expo, usa una development build.

React Native

import { Helpium } from '@helpium/react-native';

Helpium.configure({ widgetKey: 'YOUR_WIDGET_KEY' });
Helpium.identify({ userJwt: token });
Helpium.present();

Passo 4: attiva le notifiche push

Le notifiche push vengono inviate dai tuoi account Apple e Firebase, quindi arrivano dalla tua app e le chiavi restano tue. In Settings → Live Chat → Mobile apps, clicca su Connect accanto a ciascuna piattaforma:

  • iOS: una chiave APNs (.p8) del tuo account Apple Developer, con il suo Key ID, il Team ID e il tuo Bundle ID.
  • Android: il JSON del service account del tuo progetto Firebase.

Poi passa all'SDK il token del dispositivo e i tocchi. L'SDK non registra mai un proprio servizio di notifica, quindi funziona insieme alle notifiche che la tua app già invia.

iOS

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    Helpium.setPushToken(deviceToken)
}

func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse) async {
    Helpium.handlePush(response.notification.request.content.userInfo)
}

Android

@Override
public void onNewToken(@NonNull String token) {
    Helpium.setPushToken(token);
}

// Launcher activity: a notification tapped with the app closed
Helpium.handlePush(this, getIntent().getExtras());

Rendila tua

Per impostazione predefinita la chat usa il colore del brand delle tue impostazioni Live Chat. Ogni colore può anche essere impostato dall'app, separatamente per la modalità chiara e scura, con la possibilità di forzarne una:

Swift

Helpium.setAppearance(HelpiumAppearance(
    light: HelpiumColors(
        primary: "#0ea5e9",
        headerBackground: "#0ea5e9",
        headerText: "#ffffff"
    ),
    dark: HelpiumColors(
        primary: "#a78bfa",
        background: "#0f0d1a",
        surface: "#1c1830"
    )
))

Chat Helpium con un tema azzurro chiaro
Un tema chiaro con intestazione colorata.

Chat Helpium con un tema viola scuro
Un tema scuro, forzato a prescindere dall'impostazione del telefono.

Chat Helpium su Android con un tema verde
Qualsiasi palette funziona anche su Android.

Anche ogni testo è tuo: il saluto, il testo di benvenuto, il segnaposto. Sostituiscili per lingua con le risorse stringa su Android e Localizable.strings su iOS, e aggiungi le lingue che Helpium non include:

XML

<!-- res/values-es/strings.xml -->
<string name="helpium_greeting">¡Hola! ¿Te ayudamos con tu pedido?</string>

Provala prima del rilascio

  1. Dopo aver effettuato l'accesso, apri la chat: saluta il cliente senza chiedergli i suoi dati.
  2. Fai una domanda: l'IA risponde in pochi secondi.
  3. Tocca “Parla con una persona”: la conversazione compare nella tua Posta in arrivo di Helpium.
  4. Rispondi dalla Posta in arrivo: la risposta compare nell'app in tempo reale.
  5. Chiudi l'app e rispondi di nuovo: arriva una notifica push che apre la conversazione.

Prossimi passi

Supporto con IA, senza prezzi da IA

Utenti illimitati. Un prezzo fisso. Servi i clienti con l'IA e con un team umano quando conta.

Continua a leggere