Troubleshooting

This guide covers the most common issues developers encounter when integrating StreamLayer into iOS applications.

SDK Not Initializing

Symptoms:

• SDK fails to initialize when calling StreamLayer.initialize(apiKey:)
• Initialization succeeds but features don't work
• Console shows "Invalid API key" errors

Solution:

1. Verify your API key is correct in the StreamLayer dashboard
2. Ensure initialization happens in application(_:didFinishLaunchingWithOptions:) before any UI setup
3. Confirm the API key is a string, not accidentally wrapped in extra quotes
4. Check that you're using the correct environment (sandbox vs production)
5. Review the initialization order—StreamLayer must be initialized before creating StreamLayer elements

StreamLayer Element Not Appearing

Symptoms:

• StreamLayer view renders as blank/empty
• View controller displays but no StreamLayer content visible
• Element appears in view hierarchy but has no frame

Solution:

1. Verify the parent view controller is properly added to the view hierarchy
2. Check Auto Layout constraints—element needs explicit width/height or center constraints
3. Confirm the StreamLayer element is added as a subview: parentView.addSubview(streamLayerView)
4. Debug using streamLayerView.frame to ensure it has non-zero dimensions
5. Set clipsToBounds = false on parent views to detect clipping issues

Push Notification Issues

Symptoms:

• Push notifications not received
• UNUserNotificationCenter delegate not called
• Entitlements error during app signing

Solution:

1. Verify Push Notifications capability is enabled in Xcode project settings
2. Check that APNs certificate is valid and uploaded to Apple Developer account
3. Confirm UNUserNotificationCenter.current().requestAuthorization() is called
4. Review provisioning profile includes Push Notifications entitlement
5. Test on a physical device—push notifications don't work in simulator

Audio Session Conflicts

Symptoms:

• Audio playback distorted or silent
• Other apps' audio ducking not working
• Unexpected audio interruptions

Solution:

1. Configure AVAudioSession before initializing StreamLayer:
   Swift

   let audioSession = AVAudioSession.sharedInstance()
   try audioSession.setCategory(.playback, options: .duckOthers)

2. Avoid setting audio category to .soloAmbient if other audio is playing
3. Check for category conflicts with other audio libraries
4. Verify StreamLayer audio routes to speaker, not receiver
5. Test with different audio scenarios (speaker, headphones, car audio)

Build Errors

Symptoms:

• SPM resolution fails with "Unable to resolve package"
• Minimum deployment target mismatch warnings
• Framework not found errors

Solution:

1. For SPM issues: verify the StreamLayer package URL is accessible and correct
2. Check minimum iOS deployment target: StreamLayer requires iOS 16.0 or later
3. Ensure Xcode project deployment target matches or exceeds StreamLayer requirement
4. Clean build folder: Cmd+Shift+K, then rebuild
5. Delete DerivedData: rm -rf ~/Library/Developer/Xcode/DerivedData/

Still Need Help?

If you've tried these solutions and still encounter issues, contact our support team at [email protected] with:

• Detailed error messages and console output
• Xcode version and iOS target version
• Steps to reproduce the issue

Related

• Integration Guide — Full iOS SDK setup and configuration
• Getting Started — iOS SDK overview and quick-start path