Documentation Index
Fetch the complete documentation index at: https://learn.social.plus/llms.txt
Use this file to discover all available pages before exploring further.
Troubleshooting Overview
This guide provides solutions to common issues encountered when using the social.plus Video SDK. Whether you’re experiencing streaming problems, playback issues, or integration challenges, you’ll find help here.
Quick Diagnostic Steps
1. Check SDK Version
Ensure you’re using the latest version of the social.plus Video SDK:
npm list @social-plus/video-sdk
Update to the latest version:
npm update @social-plus/video-sdk
2. Verify API Key
Confirm your API key is valid and has the correct permissions:
import { SocialPlusVideo } from '@social-plus/video-sdk';
const sdk = new SocialPlusVideo({
apiKey: 'your-api-key',
environment: 'production' // or 'sandbox'
});
// Test API key validity
try {
await sdk.validateApiKey();
console.log('API key is valid');
} catch (error) {
console.error('API key validation failed:', error);
}
3. Check Network Connectivity
Test your network connection and firewall settings:
// Test network connectivity
const networkStatus = await sdk.testNetworkConnectivity();
console.log('Network status:', networkStatus);
// Check required ports and protocols
const portsStatus = await sdk.testRequiredPorts();
console.log('Ports status:', portsStatus);
Common Issues and Solutions
Installation Issues
Issue: Package Installation Fails
npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
Solution:
# Clear npm cache
npm cache clean --force
# Install with legacy peer deps
npm install @social-plus/video-sdk --legacy-peer-deps
# Or use yarn
yarn add @social-plus/video-sdk
Issue: TypeScript Declaration Files Missing
Cannot find declaration file for module '@social-plus/video-sdk'
Solution:
# Install type definitions
npm install @types/social-plus-video-sdk
# Or add to tsconfig.json
{
"compilerOptions": {
"skipLibCheck": true
}
}
Authentication Issues
Issue: API Key Rejected
Error: Invalid API key or insufficient permissions
Solutions:
- Verify API key format and characters
- Check API key permissions in dashboard
- Ensure correct environment (production vs sandbox)
- Regenerate API key if compromised
// Debug API key issues
const debugInfo = await sdk.getDebugInfo();
console.log('Debug info:', debugInfo);
Issue: Token Expired
Error: Authentication token has expired
Solution:
// Implement token refresh
sdk.on('tokenExpired', async () => {
try {
const newToken = await refreshAuthToken();
await sdk.setAuthToken(newToken);
} catch (error) {
console.error('Token refresh failed:', error);
// Redirect to login
}
});
Streaming Issues
Issue: Cannot Start Stream
Error: Failed to initialize camera or microphone
Solutions:
- Check browser permissions
- Verify camera/microphone availability
- Test on different devices
// Check media permissions
const permissions = await sdk.checkMediaPermissions();
console.log('Media permissions:', permissions);
if (!permissions.camera) {
await sdk.requestCameraPermission();
}
if (!permissions.microphone) {
await sdk.requestMicrophonePermission();
}
Issue: Poor Stream Quality
Low bitrate, dropped frames, or pixelated video
Solutions:
- Check upload bandwidth
- Adjust stream settings
- Optimize encoding parameters
// Optimize stream settings
await broadcaster.configureStream({
resolution: '720p', // Reduce from 1080p
bitrate: 3000, // Adjust based on bandwidth
fps: 30, // Reduce from 60fps
keyFrameInterval: 2
});
// Enable adaptive streaming
await broadcaster.enableAdaptiveStreaming({
minBitrate: 500,
maxBitrate: 5000,
adaptation: 'aggressive'
});
Playback Issues
Issue: Video Won’t Play
Error: Unable to load video stream
Solutions:
- Check stream availability
- Verify network connection
- Test different quality settings
// Diagnose playback issues
const playbackDiagnostics = await player.runDiagnostics();
console.log('Playback diagnostics:', playbackDiagnostics);
// Try different quality
await player.setQuality('480p');
// Enable debug mode
player.enableDebugMode(true);
Issue: Audio/Video Sync Issues
Audio and video are out of sync
Solutions:
// Adjust audio delay
await player.setAudioVideoSync({
audioDelay: 100, // milliseconds
autoSync: true
});
// Reset stream
await player.resetStream();
Web Browser Issues
Issue: WebRTC Not Supported
// Check WebRTC support
if (!sdk.isWebRTCSupported()) {
console.warn('WebRTC not supported, falling back to HLS');
await player.configurePlayback({
protocol: 'hls',
fallback: true
});
}
Issue: CORS Errors
Access to XMLHttpRequest blocked by CORS policy
Solution:
Configure your server to allow cross-origin requests or use our CDN:
const sdk = new SocialPlusVideo({
apiKey: 'your-api-key',
useCDN: true, // Use social.plus CDN to avoid CORS
corsProxy: 'https://your-cors-proxy.com'
});
Mobile App Issues
Issue: iOS Background Streaming
Stream stops when app goes to background
Solution:
// Configure background modes
await sdk.configureBackgroundMode({
enabled: true,
audioOnly: true, // Continue audio in background
notification: {
title: 'Live Stream Active',
text: 'Streaming in background'
}
});
Issue: Android Permissions
Solution:
// Request permissions properly
const permissions = await sdk.requestPermissions([
'camera',
'microphone',
'storage'
]);
if (!permissions.camera) {
// Show permission explanation
showPermissionDialog();
}
Memory Management
Issue: Memory Leaks
// Proper cleanup
class StreamComponent {
async componentWillUnmount() {
// Clean up resources
await this.player.destroy();
await this.broadcaster.stop();
// Remove event listeners
this.sdk.removeAllListeners();
}
}
Network Optimization
Issue: High Bandwidth Usage
// Optimize for mobile networks
await sdk.configureNetworkOptimization({
dataSaver: true,
adaptiveBitrate: true,
preload: 'none',
maxBandwidth: 2000000 // 2 Mbps limit
});
Enable Debug Logging
// Enable comprehensive logging
sdk.enableDebugLogging({
level: 'verbose', // 'error', 'warn', 'info', 'debug', 'verbose'
categories: ['streaming', 'playback', 'network', 'auth'],
output: 'console' // 'console', 'file', 'remote'
});
Network Diagnostics
// Run network diagnostics
const networkDiag = await sdk.runNetworkDiagnostics();
console.log('Network diagnostics:', networkDiag);
// Test specific endpoints
const endpointTest = await sdk.testEndpoints([
'streaming',
'chat',
'analytics'
]);
// Monitor SDK performance
sdk.on('performanceMetrics', (metrics) => {
console.log('Performance metrics:', {
fps: metrics.fps,
bitrate: metrics.bitrate,
latency: metrics.latency,
memoryUsage: metrics.memoryUsage
});
});
Error Reporting
Automatic Error Reporting
// Enable automatic error reporting
sdk.configureErrorReporting({
enabled: true,
includeUserAgent: true,
includeNetworkInfo: true,
customData: {
userId: 'user-123',
sessionId: 'session-456'
}
});
Manual Error Reporting
// Report custom errors
try {
await someSDKOperation();
} catch (error) {
await sdk.reportError(error, {
context: 'custom-operation',
severity: 'high',
tags: ['streaming', 'user-action']
});
}
Getting Help
Support Resources
- Documentation: Check our comprehensive docs
- GitHub Issues: Report bugs and feature requests
- Community Forum: Ask questions and share solutions
- Support Tickets: For urgent issues or enterprise support
When reporting issues, please include:
// Collect debug information
const debugInfo = await sdk.collectDebugInfo();
console.log('Debug info to include in support request:', debugInfo);
This includes:
- SDK version
- Platform information
- Browser/device details
- Network conditions
- Error logs
- Performance metrics
Next Steps