Troubleshooting

Check Flutter SDK is loaded correctly

You can use the PluginScreeb.debug() command in your code.

You will get contextual information in the debugging log about the running user session:

Debug targeting rules

Since the targeting engine built by Screeb runs in the background, you may not understand which rules prevent your survey from being displayed to a user.

You can use the PluginScreeb.debugTargeting() command in your code.

You will get a list of available surveys and the associated targeting rules:

The rules with a green dot 🟢 are the ones that have been validated for this user. The rules with a red dot 🔴 are not validated and may be the reason why your survey is not displayed.

Warning iOS

You won't see debug log on iOS if you didn't launch your app with xcode

SDK not initializing

If the SDK fails to initialize, check the following:

1. Initialize after Flutter binding: Ensure WidgetsFlutterBinding.ensureInitialized() is called before Screeb initialization:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await PluginScreeb.initSdk("<YOUR-CHANNEL-ID>");

  runApp(MyApp());
}

2. Channel ID: Verify your channel ID is correct. You can find it in the Screeb admin console.

3. Network permissions: Ensure platform-specific network permissions are configured.

Android - Add to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

iOS - Add to ios/Runner/Info.plist if making HTTP requests:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

4. Await initialization: Always await the initSdk call before using other Screeb methods:

await PluginScreeb.initSdk("<YOUR-CHANNEL-ID>");
// Now safe to use other Screeb methods

Survey or message not showing

If your survey isn't appearing when expected:

1. Targeting rules: Check targeting rules in the Screeb admin console. Use PluginScreeb.debugTargeting() to see which rules are failing.

2. User identification: Ensure the user is identified before triggering a survey:

await PluginScreeb.setIdentity("<USER-ID>");
// Wait for identity to be set before expecting surveys

3. Initialization check: Verify the SDK is initialized before you expect surveys to display:

await PluginScreeb.initSdk("<YOUR-CHANNEL-ID>");

4. Survey status: Confirm the survey is published and active in the Screeb admin console.

5. Platform channels ready: Ensure the platform channel is initialized before triggering surveys. If calling Screeb methods very early, add a small delay:

await Future.delayed(Duration(milliseconds: 500));
await PluginScreeb.startSurvey("<SURVEY-ID>");

Survey not visible

If a survey isn't appearing:

1. WebView on Android: Ensure hardware acceleration is enabled (usually default). Check android/app/src/main/AndroidManifest.xml:

<application
    android:hardwareAccelerated="true"
    ...>

2. iOS WebView configuration: If using WKWebView features, ensure proper configuration in your Info.plist.

Hot reload not reflecting Screeb changes

Screeb state is maintained in native code, so hot reload won't reflect changes to Screeb initialization or configuration:

1. Full restart required: Use the hot restart button (🔄) or run:

flutter run

2. Clean and rebuild if issues persist:

flutter clean
flutter pub get
flutter run

High memory usage

If you notice increased memory consumption:

1. Avoid multiple initializations: Only call PluginScreeb.initSdk() once, typically in main():

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize only once
  await PluginScreeb.initSdk("<YOUR-CHANNEL-ID>");

  runApp(MyApp());
}

2. Close surveys when done: If you're manually controlling survey display, ensure proper cleanup:

// When navigating away or disposing
await PluginScreeb.closeSdk();

Crashes on app foreground/background

Lifecycle-related crashes can occur if the SDK isn't properly initialized:

1. Initialize in main(): Don't initialize Screeb in widget initState() or build() methods. Always initialize in main():

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await PluginScreeb.initSdk("<YOUR-CHANNEL-ID>");
  runApp(MyApp());
}

2. Handle app lifecycle: Use WidgetsBindingObserver if you need to respond to app lifecycle events:

class _MyAppState extends State<MyApp> with WidgetsBindingObserver {
  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    super.dispose();
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    // Handle lifecycle if needed
  }
}

Anonymous users inflating MTU count

If you're seeing too many anonymous users:

1. Call resetIdentity() on logout: Reset identity when users log out:

Future<void> logout() async {
  await PluginScreeb.resetIdentity();
  // Your logout logic
}

2. Avoid init in test environments: Don't initialize Screeb during tests:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  if (!const bool.fromEnvironment('dart.vm.product')) {
    // Only init in release builds
    await PluginScreeb.initSdk("<YOUR-CHANNEL-ID>");
  }

  runApp(MyApp());
}

Platform channel errors on iOS simulator

Some features may not work correctly on iOS simulator:

1. Use a real device: Features like session replay or certain WebView capabilities require a physical iOS device.

2. Check for platform-specific errors: Wrap platform calls in try-catch:

try {
  await PluginScreeb.startSurvey("<SURVEY-ID>");
} catch (e) {
  print('Screeb error: $e');
}

Build errors after adding Screeb

If you encounter build errors:

Android

1. Kotlin version: Ensure compatible Kotlin version in android/build.gradle:

buildscript {
    ext.kotlin_version = '1.7.10' // or higher
    ...
}

2. Minimum SDK version: Check android/app/build.gradle:

android {
    defaultConfig {
        minSdkVersion 19 // Minimum required
        ...
    }
}

3. Clean and rebuild:

cd android
./gradlew clean
cd ..
flutter pub get
flutter run

iOS

1. CocoaPods version: Ensure you're using CocoaPods 1.10.0 or higher:

pod --version
sudo gem install cocoapods

2. Update pods:

cd ios
pod install --repo-update
cd ..
flutter run

3. Swift version: Ensure your project targets Swift 5.0 or higher in Xcode.

4. Minimum iOS version: Check ios/Podfile:

platform :ios, '12.0' # Minimum required

Method channel errors

If you see MissingPluginException or method channel errors:

1. Stop and restart: Hot reload won't register native plugins. Do a full restart:

flutter run

2. Clean Flutter cache:

flutter clean
flutter pub get

3. Reinstall pods (iOS):

cd ios
rm -rf Pods Podfile.lock
pod install
cd ..

4. Invalidate Android cache:

cd android
./gradlew clean
cd ..