Troubleshooting

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

Widget Not Loading

Widget shows blank/empty space

Symptoms:

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

Common Causes & Solutions:

1. Invalid Widget ID

   // ❌ Wrong
   storiesView.widgetId = 0
   
   // ✅ Correct
   storiesView.widgetId = YOUR_VALID_WIDGET_ID

2. Missing API Key or Account ID

   // ✅ Ensure initialization in Application class
   class MyApplication : Application() {
       override fun onCreate() {
           super.onCreate()
           StorifyMe.instance.initalize(
               accountId = "your-account-id",
               apiKey = "your-api-key"
           )
       }
   }

3. Network Connectivity Issues

   // Add network security config if testing on HTTP
   // In AndroidManifest.xml
   <application
       android:networkSecurityConfig="@xml/network_security_config">

4. Widget Not Published

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

Widget fails to load with error

Check Event Listener:

StorifyMe.instance.eventListener = object : StorifyMeEventListener() {
    override fun onFail(widgetId: Long, error: String) {
        Log.e("StorifyMe", "Widget failed to load: $error")
        // Common errors:
        // - "Widget not found" - Invalid widget ID
        // - "Network error" - Connectivity issues
        // - "Unauthorized" - Invalid API key/account ID
    }
}

Build Issues

Compilation Errors

Missing Dependencies:

// Ensure these are in your app/build.gradle
dependencies {
    implementation 'com.storifyme:android-sdk:<latest-version>'

    // Required dependencies
    implementation 'androidx.recyclerview:recyclerview:1.3.0'
    implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
}

ProGuard/R8 Issues:

# Add to proguard-rules.pro
-keep class com.storifyme.** { *; }
-dontwarn com.storifyme.**

# For Gson (if used internally)
-keepattributes Signature
-keepattributes *Annotation*
-keep class com.google.gson.** { *; }

Java 17 Compatibility:

// In app/build.gradle
android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }
    kotlinOptions {
        jvmTarget = '17'
    }
}

Runtime Crashes

ClassNotFoundException:

// Ensure SDK is properly added to dependencies
// Check if using correct repository
repositories {
    maven { url "https://sdk.storifyme.com/android" } // Production
    // or
    maven { url "https://sdk.dev.storifyme.com/android" } // Development
}

NetworkOnMainThreadException:

// SDK handles network calls automatically
// If you see this error, check if you're calling SDK methods on UI thread
// Most SDK methods are safe to call on main thread

Performance Issues

Slow Loading

Add Custom Logging:

// Add logging to help diagnose performance issues
StorifyMe.instance.eventListener = object : StorifyMeEventListener() {
    override fun onLoad(widgetId: Long, stories: List<StoryWithSeen>) {
        Log.d("StorifyMe", "Widget $widgetId loaded with ${stories.size} stories")
    }

    override fun onFail(widgetId: Long, error: String) {
        Log.e("StorifyMe", "Widget $widgetId failed: $error")
    }
}

Check Network Conditions:

StorifyMe.instance.eventListener = object : StorifyMeEventListener() {
    override fun onLoad(widgetId: Long, stories: List<StoryWithSeen>) {
        Log.d("StorifyMe", "Loaded ${stories.size} stories")
        // Check if stories list is as expected
    }
}

Optimize Poster Settings:

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

Memory Issues

Large Memory Usage:

// Monitor and optimize poster settings
storiesView.setGifPosterEnabled(false) // Reduces memory usage
storiesView.setVideoPosterEnabled(false) // Reduces memory usage

// Clear widget when not needed
override fun onDestroy() {
    storiesView.clear() // If available
    super.onDestroy()
}

Story Opening Issues

Stories not opening when tapped

Check Event Listener Setup:

StorifyMe.instance.eventListener = object : StorifyMeEventListener() {
    override fun onStoryOpen(widgetId: Long, storyId: Long, storyHandle: String) {
        Log.d("StorifyMe", "Story opened: $storyHandle")
    }

    override fun onAction(widgetId: Long, storyId: Long, actionType: String, actionUrl: String) {
        Log.d("StorifyMe", "Action triggered: $actionType - $actionUrl")
    }
}

Activity Context Issues:

// Ensure StoriesView has proper activity context
// If using in Fragment:
class MyFragment : Fragment() {
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        val storiesView = view.findViewById<StoriesView>(R.id.storiesView)
        // Make sure fragment's activity is available
        if (isAdded && activity != null) {
            // Safe to initialize
        }
    }
}

PreviewStoryByHandleLauncher not working

Common Issues:

// ❌ Wrong import
import com.storifyme.PreviewStoryByHandleLauncher

// ✅ Correct import
import com.storify.android_sdk.PreviewStoryByHandleLauncher

// ❌ Wrong usage
PreviewStoryByHandleLauncher.launch(this, "handle")

// ✅ Correct usage
PreviewStoryByHandleLauncher.INSTANCE.launch(this, "handle")

Configuration Issues

Stories not playing audio

Check Audio Configuration:

storiesView.setAudioOptions(
    StoryAudioBehaviour.APPLY_LAST_USER_CHANGE_FOR_ALL_FUTURE_STORIES,
    defaultState = StoryAudioState.UNMUTED // Check this setting
)

Stories always restart

Check Playback Configuration:

// If stories always restart, check this setting
storiesView.setPlaybackOptions(
    StoryPlaybackBehaviour.ALWAYS_RESUME_STORY_WHERE_STOPPED
)

Wrong direction (RTL/LTR)

Check Direction Setting:

val config = StorifyMeWidgetConfig.Builder().apply {
    setDirection(StorifyMeContentDirection.LTR) // or RTL
}.build()

storiesView.config = config

Deep Link Issues

Deep links not working

AndroidManifest.xml Configuration:

<!-- Check autoVerify attribute -->
<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data
        android:scheme="https"
        android:host="your-exact-domain.com" />
</intent-filter>

Test Deep Link Handling:

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    val uri = intent?.data
    Log.d("DeepLink", "Received URI: $uri")

    if (uri != null) {
        // Add logging to debug
        val handle = uri.pathSegments?.getOrNull(0)
        Log.d("DeepLink", "Extracted handle: $handle")
    }
}

Debug Tools

Add Comprehensive Logging

// Only for development builds
if (BuildConfig.DEBUG) {
    StorifyMe.instance.eventListener = object : StorifyMeEventListener() {
        override fun onLoad(widgetId: Long, stories: List<StoryWithSeen>) {
            Log.d("StorifyMe-Debug", "✅ Widget $widgetId loaded: ${stories.size} stories")
        }

        override fun onFail(widgetId: Long, error: String) {
            Log.e("StorifyMe-Debug", "❌ Widget $widgetId failed: $error")
        }

        override fun onStoryOpen(widgetId: Long, storyId: Long, storyHandle: String) {
            Log.d("StorifyMe-Debug", "📖 Story opened: $storyHandle")
        }

        override fun onStoryClose(widgetId: Long, storyId: Long, storyHandle: String) {
            Log.d("StorifyMe-Debug", "📕 Story closed: $storyHandle")
        }
    }
}

Logging Network Requests

// Add logging interceptor to see network requests
// This helps debug API communication issues

Testing with Different Environments

// Switch between development and production
StorifyMe.instance.initalize(
    accountId = "dev-account-id", // Use dev account for testing
    apiKey = "dev-api-key",
    environment = StorifyMeEnvironment.DEVELOPMENT // If available
)

Getting Help

Information to Provide

When reporting issues, please include:

1. SDK Version: Check your build.gradle file
2. Android Version: Device OS version
3. Error Logs: Logcat output with full stack trace
4. Configuration: Your widget configuration code
5. Steps to Reproduce: Detailed steps to reproduce the issue

Useful Debug Commands

# Check if app can access internet
adb shell ping google.com

# View full logcat for StorifyMe
adb logcat | grep -i storifyme

# Check app permissions
adb shell dumpsys package com.your.package | grep permission

# Test deep links
adb shell am start -W -a android.intent.action.VIEW -d "https://yourdomain.com/handle" com.your.package

Common Logcat Filters

# Filter StorifyMe logs
adb logcat -s "StorifyMe"

# Filter network errors
adb logcat | grep -i "network\|connection\|timeout"

# Filter memory issues
adb logcat | grep -i "outofmemory\|gc"

Best Practices for Debugging

1. Always use debug mode during development
2. Check network connectivity before reporting SDK issues
3. Verify widget configuration in StorifyMe Dashboard
4. Test with different devices and Android versions
5. Keep SDK updated to latest version
6. Use proper error handling in event listeners

Performance Monitoring

// Monitor performance metrics
StorifyMe.instance.eventListener = object : StorifyMeEventListener() {
    override fun onLoad(widgetId: Long, stories: List<StoryWithSeen>) {
        val loadTime = System.currentTimeMillis() - startTime
        Log.d("Performance", "Widget loaded in ${loadTime}ms")
    }
}

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