Cuoral Ionic Framework Library - Proactive customer success platform with support ticketing, customer intelligence, screen recording, and engagement tools
npm install cuoral-ionicProactive customer success platform integration for Ionic/Capacitor applications. Cuoral provides support ticketing, customer intelligence, screen recording, and comprehensive customer engagement tools.
✅ Customer Support - Integrated support ticketing system
✅ Customer Intelligence - Track and analyze customer behavior automatically
✅ Native Crash Tracking - Capture native Android & iOS crashes
✅ Screen Recording - Native screen recording for issue reproduction
✅ Modal Display - Full-screen modal with floating chat button
✅ TypeScript Support - Full type definitions included
✅ Simple API - Just pass your public key and optional user info
✅ Zero Configuration - Everything handled automatically
``bash`
npm install cuoral-ionic
After installing, sync your Capacitor project:
`bash`
npx cap sync
The Android plugin automatically declares required permissions. Ensure your AndroidManifest.xml includes:
`xml
`
Note: These permissions are automatically added by Capacitor when you run npx cap sync android. The INTERNET permission is auto-granted by the system. RECORD_AUDIO requires user approval at runtime.
Add to your Info.plist:
`xml`
Note: Screen recording permission is requested automatically by iOS when recording starts. No additional permissions are needed for crash tracking or intelligence features.
The easiest way to integrate Cuoral - displays a floating chat button that opens the widget in a full-screen modal.
`typescript
import { Component, OnInit, OnDestroy } from '@angular/core';
import { Cuoral } from 'cuoral-ionic';
@Component({
selector: 'app-home',
template:
Welcome to Support
,
})
export class HomePage implements OnInit, OnDestroy {
private cuoral: Cuoral;
constructor() {
this.cuoral = new Cuoral({
publicKey: 'your-public-key-here',
email: 'user@example.com', // Optional
firstName: 'John', // Optional
lastName: 'Doe', // Optional
showFloatingButton: true, // Show floating chat button
useModal: true, // Use modal display mode
});
}
ngOnInit() {
this.cuoral.initialize();
}
ngOnDestroy() {
this.cuoral.destroy();
}
// Open modal programmatically
openSupport() {
this.cuoral.openModal();
}
}
`
Features:
- 🎈 Floating blue chat button in bottom-right corner
- 📱 Opens widget in full-screen modal with small margins
- ❌ Close button in top-right
- 🎨 Smooth animations and transitions
- 🖱️ Click backdrop to close
For more control over widget placement:
`typescript
import { Component, OnInit, OnDestroy } from '@angular/core';
import { DomSanitizer, SafeResourceUrl } from '@angular/platform-browser';
import { Cuoral } from 'cuoral-ionic';
@Component({
selector: 'app-support',
template:
,
})
export class SupportPage implements OnInit, OnDestroy {
widgetUrl: SafeResourceUrl;
private cuoral: Cuoral;
constructor(private sanitizer: DomSanitizer) {
this.cuoral = new Cuoral({
publicKey: 'your-public-key-here',
useModal: false, // Disable modal mode
});
const url = this.cuoral.getWidgetUrl();
this.widgetUrl = this.sanitizer.bypassSecurityTrustResourceUrl(url);
}
ngOnInit() {
this.cuoral.initialize();
}
ngOnDestroy() {
this.cuoral.destroy();
}
}
`
To automatically track page views, add router tracking to your app.component.ts (or main app component):
`typescript
import { Component } from '@angular/core';
import { Router, NavigationEnd } from '@angular/router';
import { Cuoral } from 'cuoral-ionic';
@Component({
selector: 'app-root',
templateUrl: 'app.component.html',
})
export class AppComponent {
private cuoral: Cuoral;
constructor(private router: Router) {
this.cuoral = new Cuoral({
publicKey: 'your-public-key-here',
email: 'user@example.com',
firstName: 'John',
lastName: 'Doe',
});
}
async ngOnInit() {
// Initialize Cuoral (intelligence auto-enabled from dashboard)
await this.cuoral.initialize();
// Track all page navigation automatically
this.router.events.subscribe(event => {
if (event instanceof NavigationEnd) {
this.cuoral.trackPageView(event.url);
}
});
}
}
`
That's it! All page views are now automatically tracked. Console errors, network errors, and native crashes are tracked with zero additional setup.
When users log out, properly clear and end the session before destroying the Cuoral instance:
`typescript
async logout() {
// Step 1: Clear and end the session
await this.cuoral.clearSession();
// Step 2: Destroy the Cuoral instance
this.cuoral.destroy();
// Step 3: Your logout logic
// Navigate to login, clear user data, etc.
}
`
When a different user logs in on the same device, create a fresh Cuoral instance:
`typescript
async login(email: string, firstName: string, lastName: string) {
// Create new instance for the new user
this.cuoral = new Cuoral({
publicKey: 'your-public-key-here',
email: email,
firstName: firstName,
lastName: lastName,
});
// Initialize for new user
await this.cuoral.initialize();
}
`
Important Notes:
- clearSession() marks the session as ended on the backenddestroy()
- cleans up local resourcesclearSession()
- Always call before destroy() on logout
- Create a new Cuoral instance for each user login
- Email, first name, and last name are all required for identified users
Cuoral integrates seamlessly with your existing push notification system using webhooks. When an agent sends a message, Cuoral sends a webhook to your backend, allowing you to send push notifications to users when the widget is closed.
How it works:
1. Track widget state in your app (open/closed)
2. Configure webhooks in your Cuoral dashboard
3. Receive webhook when agent sends message
4. Send FCM/APNs push if widget is closed
Example Implementation:
`typescript
export class MyApp {
private isCuoralWidgetOpen = false;
// When user opens support
openSupport() {
this.isCuoralWidgetOpen = true;
this.cuoral.openModal();
}
// When user closes support
closeSupport() {
this.isCuoralWidgetOpen = false;
this.cuoral.closeModal();
}
// Handle incoming push notifications (your existing FCM handler)
async handlePushNotification(message: any) {
if (message.data.type === 'cuoral_message') {
// Don't show notification if widget is already open
if (this.isCuoralWidgetOpen) {
return; // User already sees the message
}
// Show notification to user
await this.showNotification({
title: 'New message from Support',
body: message.data.text,
});
// When user taps notification, open widget
this.openSupport();
}
}
}
`
Setup:
1. Configure your webhook URL in Cuoral Dashboard → Settings → Webhooks
2. Cuoral sends webhooks for all new messages
3. Your backend decides whether to send push based on your app's state
4. User taps notification → your app calls cuoral.openModal()
This approach works with your existing FCM/APNs setup - no additional SDK configuration needed!
`typescript`
interface CuoralOptions {
publicKey: string; // Required: Your Cuoral public key
email?: string; // Optional: User email
firstName?: string; // Optional: User first name
lastName?: string; // Optional: User last name
debug?: boolean; // Optional: Enable debug logging (default: false)
widgetBaseUrl?: string; // Optional: Custom widget URL (default: CDN)
showFloatingButton?: boolean; // Optional: Show floating chat button (default: true)
useModal?: boolean; // Optional: Use modal display mode (default: true)
}
By default, the widget loads from https://js.cuoral.com/mobile.html (production CDN).
Production (Default):
`typescript`
new Cuoral({ publicKey: 'your-key' });
Custom URL (Optional):
If you need to use a custom widget URL for testing or self-hosting:
`typescript`
new Cuoral({
publicKey: 'your-key',
widgetBaseUrl: 'https://your-domain.com/mobile.html',
});
`typescript
// Initialize Cuoral
cuoral.initialize(): void
// Get widget URL for iframe embedding
cuoral.getWidgetUrl(): string
// Open modal programmatically
cuoral.openModal(): void
// Close modal programmatically
cuoral.closeModal(): void
// Check if modal is open
cuoral.isModalOpen(): boolean
// Clean up resources
cuoral.destroy(): void
`
- ✅ Support ticket creation and management
- ✅ Customer intelligence tracking (page views, errors, network failures)
- ✅ Native crash tracking (Android & iOS)
- ✅ Screen recording start/stop
- ✅ File path conversion for video playback
- ✅ Communication between widget and native code
- ✅ Video upload to Cuoral backend
- ✅ State management
- ✅ Permissions handling
Intelligence tracking is automatically enabled/disabled from your Cuoral dashboard. When enabled, the library automatically captures:
- Page Views - Track navigation (requires one-time router setup, see INTELLIGENCE.md)
- Console Errors - JavaScript errors and unhandled exceptions
- Network Errors - Failed API calls (4xx, 5xx responses)
- Native Crashes - Native Android (Java/Kotlin) and iOS (Swift/Objective-C) crashes
For detailed intelligence setup and features, see INTELLIGENCE.md
Check iOS permissions:
- Verify NSMicrophoneUsageDescription is in Info.plist
- System will prompt user automatically on first recording
Enable debug mode:
`typescript`
new Cuoral({
publicKey: 'your-key',
debug: true, // See console logs
});
Modal mode:
- Make sure you called cuoral.initialize()
- Check that is set (default)
- Look for the blue floating button in bottom-right
Iframe mode:
- Verify widgetUrl is properly sanitized with DomSanitizer
- Check browser console for CORS errors
- Ensure iframe has proper dimensions in CSS
iOS Pod Issues:
`bash`
cd ios
pod deintegrate
pod install
cd ..
npx cap sync ios
Clean build:
`bash``
rm -rf node_modules dist
npm install
npx cap sync
- 📧 Email: support@cuoral.com
- 📖 Docs: https://docs.cuoral.com
- 🐛 Issues: https://github.com/cuoral/cuoral-ionic/issues
MIT License - see LICENSE file
---
Built with ❤️ by Cuoral