OnboardSync Flutter SDK

A Flutter SDK for integrating OnboardSync - a remote configuration platform for mobile app onboarding flows with A/B testing capabilities.

Features

• 🚀 Simple Integration - Just one method call to show onboarding
• 🎨 Remote Configuration - Update onboarding flows without app updates
• 📊 A/B Testing - Test different onboarding experiences
• 🔄 Automatic Fallback - Graceful handling when offline
• 📱 Cross-Platform - Works on iOS and Android
• 🎯 Smart Targeting - Show onboarding only to new users
• 🔔 Permission Handling - Built-in support for system permissions
• ⭐ App Reviews - Integrated app rating requests

Installation

Add onboardsync to your pubspec.yaml:

dependencies:
  onboardsync: ^0.0.2

Then run:

flutter pub get

Quick Start

1. Import the SDK

import 'package:onboardsync/onboardsync.dart';

2. Show onboarding in your app

// In your main screen's initState or after first frame
OnboardSync.showOnboarding(
  context,
  projectId: '[project_key]',
  secretKey: '[secret_key]',
);

That's it! The SDK handles everything else automatically.

Complete Example

import 'package:flutter/material.dart';
import 'package:onboardsync/onboardsync.dart';

class MyApp extends StatefulWidget {
  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    
    // Show onboarding after first frame renders
    WidgetsBinding.instance.addPostFrameCallback((_) {
      _showOnboarding();
    });
  }

  void _showOnboarding() {
    OnboardSync.showOnboarding(
      context,
      projectId: 'your-project-id',
      secretKey: 'your-secret-key',
      testingEnabled: false, // Set to true during development
      onComplete: (result) {
        // Called when onboarding completes
        print('Onboarding completed!');
        
        // Access form responses if available
        if (result != null && result.hasResponses) {
          for (final response in result.responses) {
            print('${response.questionText}: ${response.answer}');
          }
        }
      },
    );
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body: Center(
          child: Text('Your app content'),
        ),
      ),
    );
  }
}

API Reference

OnboardSync.showOnboarding()

Displays the onboarding flow for your project.

Parameters

Parameter	Type	Required	Description
context	BuildContext	Yes	The build context to display onboarding
projectId	String	Yes	Your OnboardSync project ID
secretKey	String	Yes	Your OnboardSync secret key
testingEnabled	bool	No	If true, shows onboarding every time (default: false)
onComplete	OnboardingCompleteCallback	No	Callback when onboarding completes with form responses

OnboardingResult

Contains all form responses from a completed onboarding flow.

class OnboardingResult {
  final String flowId;                    // The ID of the completed flow
  final List<OnboardingResponse> responses; // All form responses
  
  // Helper methods
  OnboardingResponse? getResponseByQuestion(String questionText);
  List<OnboardingResponse> get textResponses;           // Text input responses only
  List<OnboardingResponse> get singleChoiceResponses;   // Single choice responses only
  List<OnboardingResponse> get multipleChoiceResponses; // Multiple choice responses only
  List<OnboardingResponse> get choiceResponses;         // All choice responses
  bool get hasResponses;                                // Whether any responses exist
  int get responseCount;                                // Number of responses
}

OnboardingResponse

A single question response from the onboarding flow.

class OnboardingResponse {
  final String questionText;    // The question that was asked
  final String questionType;    // 'question_text', 'question_single_choice', or 'question_multiple_choice'
  final dynamic answer;         // The user's answer (String or List<String>)
  final String? screenId;       // The screen ID where this question appeared
  
  // Helper properties
  String? get answerAsString;   // Answer as a single string
  List<String> get answerAsList; // Answer as a list of strings
}

OnboardingCompleteCallback

Callback type for when onboarding completes.

typedef OnboardingCompleteCallback = void Function([OnboardingResult? result]);

Configuration

The SDK automatically:

• ✅ Checks if the user has completed onboarding before
• ✅ Fetches the appropriate onboarding flow based on A/B test allocation
• ✅ Displays the onboarding in a WebView
• ✅ Handles errors with a fallback screen
• ✅ Saves completion status locally
• ✅ Manages system UI (status bar) styling

Permissions

The SDK can handle permission requests triggered from your onboarding flow:

• Camera
• Photos
• Location
• Contacts
• Notifications

These are requested only when your onboarding flow triggers them.

Testing

During development, set testingEnabled: true to show onboarding every time:

OnboardSync.showOnboarding(
  context,
  projectId: '[project_key]',
  secretKey: '[secret_key]',
  testingEnabled: true, // Always show onboarding
);

Error Handling

The SDK includes automatic error handling:

• Network errors show a fallback welcome screen
• Configuration errors are logged and handled gracefully
• Users can still continue using your app even if onboarding fails to load

Platform-Specific Setup

iOS Setup

1. Minimum iOS Version: Ensure your ios/Podfile has:

   platform :ios, '11.0'
   

2. Permissions: Add required permissions to ios/Runner/Info.plist:

   <key>NSCameraUsageDescription</key>
   <string>This app needs camera access for profile photos</string>
   <key>NSPhotoLibraryUsageDescription</key>
   <string>This app needs photo library access to select images</string>
   <key>NSLocationWhenInUseUsageDescription</key>
   <string>This app needs location access to provide personalized experiences</string>
   <key>NSContactsUsageDescription</key>
   <string>This app needs contacts access to help you connect with friends</string>
   

Android Setup

1. Minimum SDK Version: In android/app/build.gradle:

   defaultConfig {
       minSdkVersion 21
   }
   

2. Permissions: Add to android/app/src/main/AndroidManifest.xml:

   <uses-permission android:name="android.permission.INTERNET" />
   <uses-permission android:name="android.permission.CAMERA" />
   <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
   <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
   <uses-permission android:name="android.permission.READ_CONTACTS" />
   

Platform Support

• ✅ iOS 11.0+
• ✅ Android API 21+
• ✅ Flutter 1.17.0+
• ✅ Dart 3.7.0+

Advanced Usage

Custom Completion Handling

OnboardSync.showOnboarding(
  context,
  projectId: '[project_key]',
  secretKey: '[secret_key]',
  onComplete: (result) {
    // Access form responses
    if (result != null && result.hasResponses) {
      // Get a specific response by question text
      final nameResponse = result.getResponseByQuestion("What's your name?");
      if (nameResponse != null) {
        print('User name: ${nameResponse.answerAsString}');
      }
      
      // Iterate through all responses
      for (final response in result.responses) {
        switch (response.questionType) {
          case 'question_text':
            print('Text answer: ${response.answerAsString}');
            break;
          case 'question_single_choice':
            print('Selected: ${response.answerAsString}');
            break;
          case 'question_multiple_choice':
            print('Selected options: ${response.answerAsList}');
            break;
        }
      }
      
      // Get responses by type
      final textResponses = result.textResponses;
      final choiceResponses = result.choiceResponses;
    }
    
    // Navigate to next screen
    Navigator.pushReplacement(
      context,
      MaterialPageRoute(builder: (context) => HomeScreen()),
    );
  },
);

Checking Onboarding Status

While the SDK automatically manages onboarding display, you can manually check the completion status if needed:

import 'package:shared_preferences/shared_preferences.dart';

Future<bool> hasCompletedOnboarding() async {
  final prefs = await SharedPreferences.getInstance();
  return prefs.getBool('onboarding_completed') ?? false;
}

Resetting Onboarding (For Testing)

import 'package:shared_preferences/shared_preferences.dart';

Future<void> resetOnboarding() async {
  final prefs = await SharedPreferences.getInstance();
  await prefs.setBool('onboarding_completed', false);
}

Troubleshooting

Onboarding not showing?

1. Check your project ID and secret key are correct
2. Ensure you have an active internet connection
3. Verify testingEnabled is set appropriately
4. Check debug logs for any error messages

Permissions not working?

Make sure you've added the necessary permission configurations to your app:

iOS - Add to Info.plist:

<key>NSCameraUsageDescription</key>
<string>Your camera usage description</string>
<!-- Add other permissions as needed -->

Android - Add to AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA" />
<!-- Add other permissions as needed -->

Support

• 📧 Email: support@muchadostudio.com
• 📚 Documentation: https://docs.onboardsync.com

License

This SDK is available under the MIT license. See the LICENSE file for more info.