LoyJoy in eine Native App integrieren

Sie können jeden LoyJoy-KI-Agenten mit einer WebView in eine native iOS- oder Android-App einbetten. Die WebView lädt die Landingpage-URL des KI-Agenten und rendert die vollständige Chat-Erfahrung innerhalb Ihrer App. Kein SDK, kein nativer Chat-Code, kein App-Store-Update, wenn Sie den KI-Agenten ändern. Sie veröffentlichen den KI-Agenten in LoyJoy, die App zeigt automatisch die neueste Version.

Dieser Leitfaden behandelt die grundlegende Einbettung sowie die Einstellungen, die Sie benötigen, damit Sprache, Datei-Upload und Chat-Verlauf zuverlässig in der WebView funktionieren.

Wann eine WebView verwenden

Eine WebView ist die richtige Wahl, wenn der KI-Agent innerhalb Ihrer App laufen soll: als Support-Tab, als Onboarding-Assistent, als Produktberater oder als Vollbild-Chat. Benutzer bleiben in Ihrer App, der KI-Agent übernimmt Ihr Branding, und Sie behalten die volle Kontrolle darüber, wann und wo der Chat erscheint.

Wenn Sie nur auf den KI-Agenten verlinken müssen, öffnen Sie die Landingpage-URL stattdessen im Systembrowser. Eine WebView ist für ein eingebettetes In-App-Erlebnis gedacht.

Schritt 1: Die KI-Agenten-URL abrufen

Öffnen Sie den Publish-Tab Ihres KI-Agenten und kopieren Sie die Landingpage-URL. Sie hat die Form:

https://cloud.loyjoy.com/sites/YOUR-PROCESS-ID

Sie können URL-Parameter anhängen, um den Chat zu steuern, z. B. ?loyjoy-open=true, um den Chat automatisch zu öffnen, oder Variablen übergeben, um Kontext vorzubefüllen. Die vollständige Liste finden Sie in den Widget-Parametern.

Schritt 2: iOS (WKWebView)

Verwenden Sie WKWebView (die moderne WebView; UIWebView ist veraltet und wird nicht unterstützt).

import WebKit

let config = WKWebViewConfiguration()
// Required for voice agents and inline audio/video
config.allowsInlineMediaPlayback = true
config.mediaTypesRequiringUserActionForPlayback = []

let webView = WKWebView(frame: view.bounds, configuration: config)
view.addSubview(webView)

if let url = URL(string: "https://cloud.loyjoy.com/sites/YOUR-PROCESS-ID") {
    webView.load(URLRequest(url: url))
}

Für das Mikrofon (Sprach-KI-Agenten) und die Kamera (Foto-Snapshot-Modul) fügen Sie Ihrem Info.plist Nutzungsbeschreibungen hinzu, da iOS den Zugriff sonst blockiert und der WebView-Aufruf stillschweigend fehlschlägt:

<key>NSMicrophoneUsageDescription</key>
<string>Allow microphone access to talk to the assistant.</string>
<key>NSCameraUsageDescription</key>
<string>Allow camera access to send photos in the chat.</string>

Auf iOS 15+ gewährt WKWebView die Mikrofon- und Kameraberechtigung automatisch, sobald die Info.plist-Beschreibungen vorhanden sind. localStorage (für Chat-Verlauf und Variablen verwendet) funktioniert in WKWebView ohne weitere Einstellungen.

Schritt 3: Android (WebView)

Android erfordert einige Einstellungen, die standardmäßig deaktiviert sind. Ohne sie startet der Chat nicht, der Verlauf wird nicht gespeichert und Datei-Uploads schlagen fehl.

val webView = WebView(this)
setContentView(webView)

webView.settings.apply {
    javaScriptEnabled = true          // required, off by default
    domStorageEnabled = true          // required for chat history and variables
    mediaPlaybackRequiresUserGesture = false  // required for voice / inline audio
}

// Grant microphone and camera to the LoyJoy page
webView.webChromeClient = object : WebChromeClient() {
    override fun onPermissionRequest(request: PermissionRequest) {
        request.grant(request.resources)
    }
    // onShowFileChooser is also handled here, see Step 4
}

webView.loadUrl("https://cloud.loyjoy.com/sites/YOUR-PROCESS-ID")

Fügen Sie die Laufzeitberechtigungen, die Ihr KI-Agent benötigt, der AndroidManifest.xml hinzu und fordern Sie sie zur Laufzeit an, bevor Sie die WebView laden:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />   <!-- voice agents -->
<uses-permission android:name="android.permission.CAMERA" />          <!-- photo module -->

Schritt 4: Datei-Upload aktivieren (Android)

Wenn Ihr KI-Agent das Foto-Snapshot- oder Datei-Upload-Modul verwendet, benötigt Android einen onShowFileChooser-Handler im WebChromeClient. iOS übernimmt dies nativ, ohne zusätzlichen Code.

private var filePathCallback: ValueCallback<Array<Uri>>? = null

override fun onShowFileChooser(
    webView: WebView,
    callback: ValueCallback<Array<Uri>>,
    params: FileChooserParams
): Boolean {
    filePathCallback = callback
    val intent = params.createIntent()
    startActivityForResult(intent, FILE_CHOOSER_REQUEST)
    return true
}

Leiten Sie das Ergebnis in onActivityResult an filePathCallback weiter.

Schritt 5: Externe Links behandeln

Links im Chat (z. B. ein Button, der eine Produktseite öffnet) sollten im Systembrowser geöffnet werden, nicht die WebView vom Chat wegnavigieren. Fangen Sie die Navigation ab und öffnen Sie externe URLs extern:

iOS — implementieren Sie WKNavigationDelegate.decidePolicyFor und öffnen Sie Links zu anderen Domains mit UIApplication.shared.open.

Android — setzen Sie einen WebViewClient und geben Sie für externe Hosts true aus shouldOverrideUrlLoading zurück, indem Sie sie mit einem ACTION_VIEW-Intent öffnen.

Behalten Sie die Navigation zu cloud.loyjoy.com (und beliebigen eigenen eingebetteten Domains) innerhalb der WebView.

Schritt 6: App-Verhalten vom Chat aus auslösen

Das Event-Modul ermöglicht einem Prozess, ein benutzerdefiniertes JavaScript-Ereignis auszugeben, das der Chat an die Host-Seite weiterleitet. Ihre App kann in der WebView auf dieses Ereignis lauschen und ein eigenes Verhalten auslösen, z. B. eine vorbefüllte Ansicht öffnen: Leiten Sie den Chat zu einer bestimmten Ansicht mit vorausgefüllten Parametern oder öffnen Sie Ihre eigene native App-Ansicht mit den vom Ereignis übertragenen Daten.

Fügen Sie im Prozess ein Event-Modul hinzu und wählen Sie einen Ereignisnamen, z. B. open_claim_form. Registrieren Sie in Ihrer App einen JavaScript-Ereignis-Listener am LoyJoy-Widget (siehe wie Sie auf Ereignisse hören) und reagieren Sie, wenn das Ereignis ausgelöst wird:

document.getElementById('my-widget').addEventListener('event', function (e) {
  if (e.detail.type === 'open_claim_form') {
    // open a pre-filled view, e.g. route the chat to a view with parameters
    // or open your own native app view with the data from the event
  }
})

In einer WebView injizieren Sie diesen Listener mit webView.evaluateJavaScript(...) (iOS) oder webView.evaluateJavascript(...) (Android), sobald die Chat-Seite geladen ist.

Checkliste

Funktion	iOS	Android
Chat laden	WKWebView.load(url)	loadUrl(url) + javaScriptEnabled = true
Chat-Verlauf / Variablen	standardmäßig aktiv	domStorageEnabled = true
Sprach-KI-Agent (Mikrofon)	NSMicrophoneUsageDescription	RECORD_AUDIO + onPermissionRequest.grant
Foto / Kamera-Modul	NSCameraUsageDescription	CAMERA + onPermissionRequest.grant
Inline-Audio / -Video	allowsInlineMediaPlayback = true	mediaPlaybackRequiresUserGesture = false
Datei-Upload	nativ, kein Code	onShowFileChooser
Externe Links	decidePolicyFor	shouldOverrideUrlLoading
App-Verhalten über Event-Modul	evaluateJavaScript	evaluateJavascript

Hinweise

• Consent Manager: Ein Cookie-Banner ist ein Website-Konzept. Innerhalb Ihrer eigenen nativen App decken Sie die datenschutzrelevanten Aspekte des Chats in der Regel in der Datenschutzerklärung Ihrer App ab, statt über einen Web-Consent-Manager. Gleichen Sie die Einstellung zum Chat-Verlauf (Branding-Tab) mit der Datenrichtlinie Ihrer App ab.
• Updates ohne App-Release: Da die WebView immer den veröffentlichten KI-Agenten lädt, können Sie den KI-Agenten in LoyJoy ändern, und die App übernimmt dies innerhalb von ca. 2 Minuten. Kein App-Store-Review nötig.
• Automatisches Öffnen und Parameter: Hängen Sie ?loyjoy-open=true an, um den Chat beim Laden zu öffnen. Übergeben Sie Variablen per URL-Parameter, um Kontext aus Ihrer App in den Chat zu geben.

Sie benötigen Hilfe bei einem bestimmten Framework (React Native, Flutter, Capacitor)? Kontaktieren Sie support@loyjoy.com.