Troubleshooting

This guide helps you diagnose and resolve common issues when integrating the StorifyMe iOS SDK.

Widget Not Loading

Widget shows blank/empty space

Symptoms:

• StorifyMeWidget is visible but shows no content
• No stories appear even after calling load()

Common Causes & Solutions:

1. Invalid Widget ID

   // ❌ Wrong
   storifyMeWidget.setWidgetId(widgetId: 0)
   
   // ✅ Correct
   storifyMeWidget.setWidgetId(widgetId: YOUR_VALID_WIDGET_ID)

2. Missing SDK Initialization

   // ✅ Ensure initialization in AppDelegate or SceneDelegate
   func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
       StorifyMeInstance.shared.initialize(
           accountId: "your-account-id",
           apiKey: "your-api-key"
       )
       return true
   }

3. Network Security Issues

   <!-- In Info.plist, add if testing with HTTP -->
   <key>NSAppTransportSecurity</key>
   <dict>
       <key>NSAllowsArbitraryLoads</key>
       <true/>
   </dict>

4. Widget Not Published

   • Check StorifyMe Dashboard to ensure widget is published
   • Verify widget contains published stories

Widget fails to load with error

Implement Event Handler:

extension ViewController: StorifyMeStoryEventProtocol {
    func onFail(widgetId: Int, error: String) {
        print("StorifyMe Error: \(error)")
        // Common errors:
        // - "Widget not found" - Invalid widget ID
        // - "Network error" - Connectivity issues
        // - "Unauthorized" - Invalid API key/account ID
    }
}

Build Issues

CocoaPods Integration Problems

Pod Installation Issues:

# Clear CocoaPods cache
pod cache clean --all
pod deintegrate
pod install --repo-update

# If using Xcode 15+, you might need:
pod install --verbose

Podfile Configuration:

platform :ios, '12.0'
use_frameworks!

target 'YourApp' do
  pod 'StorifyMe', '~> <latest-version>'

  # If you encounter issues, try:
  # pod 'StorifyMe', :git => 'https://github.com/StorifyMe/sdk-ios.git'
end

# Add this if you have module issues
post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
    end
  end
end

Swift Package Manager Issues

Package Resolution Problems:

// In Package.swift or Xcode Package Manager
.package(url: "https://github.com/StorifyMe/sdk-ios.git", from: "<latest-version>")

Common SPM Errors:

• Clear derived data: Product > Clean Build Folder
• Reset package caches: File > Packages > Reset Package Caches
• Update to latest: File > Packages > Update to Latest Package Versions

Compilation Errors

Missing Frameworks:

// Ensure these frameworks are linked
// UIKit, Foundation, AVFoundation, WebKit
// Usually handled automatically by CocoaPods/SPM

Bitcode Issues (Legacy):

# In Build Settings, set Enable Bitcode to NO if encountering issues
# (Note: Bitcode deprecated in Xcode 14+)

Runtime Issues

App Crashes

StorifyMe Initialization Crash:

// ❌ Wrong - calling before initialization
StorifyMeInstance.shared.openStoryByHandle(handle: "test")

// ✅ Correct - initialize first
StorifyMeInstance.shared.initialize(accountId: "id", apiKey: "key")
StorifyMeInstance.shared.openStoryByHandle(handle: "test")

Memory Crashes:

// Implement proper memory management
override func viewDidDisappear(_ animated: Bool) {
    super.viewDidDisappear(animated)
    // Clear resources if widget provides cleanup method
    storifyMeWidget.cleanup() // If available
}

Thread Safety Issues:

// Always call SDK methods on main thread
DispatchQueue.main.async {
    self.storifyMeWidget.load()
}

Performance Issues

Slow Loading

Add Custom Logging:

// For development builds only
#if DEBUG
extension ViewController: StorifyMeStoryEventProtocol {
    func onLoad(widgetId: Int, storyList: [StorifyMeStory]) {
        print("✅ StorifyMe: Widget \(widgetId) loaded with \(storyList.count) stories")
    }

    func onFail(widgetId: Int, error: String) {
        print("❌ StorifyMe: Widget \(widgetId) failed - \(error)")
    }
}
#endif

Monitor Loading Performance:

extension ViewController: StorifyMeStoryEventProtocol {
    func onLoad(widgetId: Int, storyList: [StorifyMeStory]) {
        let loadTime = Date().timeIntervalSince(startTime)
        print("Widget loaded in \(loadTime) seconds")
    }
}

Optimize for Performance:

// Disable resource-intensive features if needed
storifyMeWidget.setGifPosterEnabled(false)
storifyMeWidget.setVideoPosterEnabled(false)

Memory Issues

High Memory Usage:

// Monitor memory in development
// Use Xcode Instruments to profile memory usage

// Optimize poster settings
storifyMeWidget.setGifPosterEnabled(false) // Reduces memory
storifyMeWidget.setVideoPosterEnabled(false) // Reduces memory

Story Opening Issues

Stories not opening when tapped

Check Event Handler Implementation:

class ViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()

        // ❌ Missing event handler assignment
        storifyMeWidget.setWidgetId(widgetId: WIDGET_ID)

        // ✅ Correct - assign event handler
        storifyMeWidget.eventHandler = self
        storifyMeWidget.setWidgetId(widgetId: WIDGET_ID)
    }
}

extension ViewController: StorifyMeStoryEventProtocol {
    func onStoryOpen(widgetId: Int, storyId: Int, storyHandle: String) {
        print("Story opened: \(storyHandle)")
    }
}

View Controller Hierarchy Issues:

// Ensure widget is added to view hierarchy properly
override func viewDidLoad() {
    super.viewDidLoad()

    view.addSubview(storifyMeWidget)
    storifyMeWidget.translatesAutoresizingMaskIntoConstraints = false
    NSLayoutConstraint.activate([
        storifyMeWidget.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
        storifyMeWidget.leadingAnchor.constraint(equalTo: view.leadingAnchor),
        storifyMeWidget.trailingAnchor.constraint(equalTo: view.trailingAnchor),
        storifyMeWidget.heightAnchor.constraint(equalToConstant: 120)
    ])
}

openStoryByHandle not working

Common Issues:

// ❌ Wrong - not initialized
StorifyMeInstance.shared.openStoryByHandle(handle: "test")

// ✅ Correct - ensure initialization
StorifyMeInstance.shared.initialize(accountId: "id", apiKey: "key")
StorifyMeInstance.shared.openStoryByHandle(handle: "test")

// ❌ Wrong - invalid handle
StorifyMeInstance.shared.openStoryByHandle(handle: "")

// ✅ Correct - valid handle
StorifyMeInstance.shared.openStoryByHandle(handle: "valid-story-handle")

Configuration Issues

Stories not playing audio

Check Audio Configuration:

storifyMeWidget.setWidgetAudioOptions(
    options: StorifyMeStoryAudioOptions(
        behaviour: .applyLastUserChangeForAllFutureStories,
        defaultState: .unmuted // Check this setting
    )
)

iOS Audio Session Issues:

// In some cases, you might need to configure audio session
import AVFoundation

override func viewDidLoad() {
    super.viewDidLoad()

    do {
        try AVAudioSession.sharedInstance().setCategory(.playback, mode: .default)
        try AVAudioSession.sharedInstance().setActive(true)
    } catch {
        print("Audio session error: \(error)")
    }
}

Wrong layout or appearance

Auto Layout Issues:

// Ensure proper constraints
storifyMeWidget.translatesAutoresizingMaskIntoConstraints = false

// Common constraint issues
NSLayoutConstraint.activate([
    storifyMeWidget.heightAnchor.constraint(equalToConstant: 120), // Set explicit height
    storifyMeWidget.widthAnchor.constraint(equalTo: view.widthAnchor)
])

Dark Mode Issues:

// Test in both light and dark mode
// Override if needed:
override func traitCollectionDidChange(_ previousTraitCollection: UITraitCollection?) {
    super.traitCollectionDidChange(previousTraitCollection)

    if traitCollection.userInterfaceStyle != previousTraitCollection?.userInterfaceStyle {
        // Handle appearance changes if needed
        storifyMeWidget.refreshAppearance() // If available
    }
}

Deep Link Issues

Deep links not working

Associated Domains Configuration:

<!-- In YourApp.entitlements -->
<key>com.apple.developer.associated-domains</key>
<array>
    <string>applinks:yourdomain.com</string>
    <!-- Make sure domain matches exactly -->
</array>

URL Handling Issues:

// SceneDelegate
func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
          let url = userActivity.webpageURL else {
        return
    }

    print("Received URL: \(url)") // Add logging
    handleDeepLink(url: url)
}

// AppDelegate (if not using SceneDelegate)
func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    print("Received URL: \(userActivity.webpageURL)") // Add logging
    // Handle URL
    return true
}

SwiftUI Issues

Widget not displaying in SwiftUI

UIViewRepresentable Implementation:

struct StorifyMeView: UIViewRepresentable {
    let widgetId: Int

    func makeUIView(context: Context) -> StorifyMeWidget {
        let widget = StorifyMeWidget()
        widget.eventHandler = context.coordinator
        widget.setWidgetId(widgetId: widgetId)
        widget.load()
        return widget
    }

    func updateUIView(_ uiView: StorifyMeWidget, context: Context) {
        // Update if needed
    }

    func makeCoordinator() -> Coordinator {
        Coordinator()
    }

    class Coordinator: NSObject, StorifyMeStoryEventProtocol {
        func onLoad(widgetId: Int, storyList: [StorifyMeStory]) {
            print("Stories loaded in SwiftUI")
        }
    }
}

Debug Tools

Add Comprehensive Logging

#if DEBUG
extension ViewController: StorifyMeStoryEventProtocol {
    func onLoad(widgetId: Int, storyList: [StorifyMeStory]) {
        print("✅ StorifyMe-Debug: Widget \(widgetId) loaded with \(storyList.count) stories")
    }

    func onFail(widgetId: Int, error: String) {
        print("❌ StorifyMe-Debug: Widget \(widgetId) failed - \(error)")
    }

    func onStoryOpen(widgetId: Int, storyId: Int, storyHandle: String) {
        print("📖 StorifyMe-Debug: Story opened - \(storyHandle)")
    }

    func onStoryClose(widgetId: Int, storyId: Int, storyHandle: String) {
        print("📕 StorifyMe-Debug: Story closed - \(storyHandle)")
    }
}
#endif

Console Logging

// Add comprehensive logging
extension ViewController: StorifyMeStoryEventProtocol {
    func onLoad(widgetId: Int, storyList: [StorifyMeStory]) {
        print("✅ Loaded \(storyList.count) stories for widget \(widgetId)")
    }

    func onFail(widgetId: Int, error: String) {
        print("❌ Failed to load widget \(widgetId): \(error)")
    }

    func onStoryOpen(widgetId: Int, storyId: Int, storyHandle: String) {
        print("📖 Story opened: \(storyHandle)")
    }

    func onStoryClose(widgetId: Int, storyId: Int, storyHandle: String) {
        print("📕 Story closed: \(storyHandle)")
    }
}

Network Debugging

// Monitor network requests (if SDK provides callback)
// Use Xcode Network debugging or Charles Proxy to monitor requests

Testing Tools

Simulator Testing

# Test deep links in simulator
xcrun simctl openurl booted "https://yourdomain.com/story-handle"

Device Testing

1. TestFlight: Use TestFlight builds to test in production-like environment
2. Debug Builds: Use debug builds with detailed logging
3. Network Conditions: Test with poor network conditions

Getting Help

Information to Provide

When reporting issues, include:

1. SDK Version: Check your Podfile.lock or Package.resolved
2. iOS Version: Device OS version
3. Xcode Version: Development environment version
4. Device Model: iPhone/iPad model
5. Integration Method: CocoaPods, SPM, or manual
6. Error Logs: Complete console output
7. Configuration Code: Your widget setup code

Useful Debug Commands

# Check CocoaPods setup
pod --version
pod outdated

# Check Xcode build settings
xcodebuild -showBuildSettings -target YourApp

# Test deep links
xcrun simctl openurl booted "https://yourdomain.com/test-handle"

Xcode Debugging Tools

1. Console: View real-time logs
2. Instruments: Profile memory and performance
3. Network Link Conditioner: Test with poor network
4. Accessibility Inspector: Test accessibility features

Best Practices for Debugging

1. Always test on physical devices
2. Use debug mode during development only
3. Test with different iOS versions
4. Verify network connectivity
5. Check StorifyMe Dashboard configuration
6. Use Xcode Instruments for performance debugging
7. Test in both light and dark mode

Performance Monitoring

// Monitor key metrics
class PerformanceMonitor: StorifyMeStoryEventProtocol {
    private var loadStartTime: Date?

    func startMonitoring() {
        loadStartTime = Date()
    }

    func onLoad(widgetId: Int, storyList: [StorifyMeStory]) {
        if let startTime = loadStartTime {
            let duration = Date().timeIntervalSince(startTime)
            print("Load time: \(duration)s for \(storyList.count) stories")
        }
    }
}

For additional support, refer to the StorifyMe Documentation or contact the support team with the debug information listed above.