Installation

Setting up research_package in a Flutter app takes four steps:

1. Add the packages

   flutter pub add research_package
   flutter pub add "flutter_localizations@{sdk: flutter}"

   flutter_localizations holds Flutter's own Material and Cupertino texts for languages other than English. Research Package shows Material dialogs and a Cupertino date picker, which fail in other languages without these texts.

   Note

   In an app that also uses carp_survey_package or cognition_package, the first command resolves research_package 3.2.0, because both packages require version 3. Version 3.2.0 brings the health and permission_handler plugins and their platform setup, as described in Survey Sampling Installation.

2. Initialize Research Package

   In lib/main.dart, call ResearchPackage.ensureInitialized() at the start of main():

   import 'package:flutter/material.dart';
   import 'package:research_package/research_package.dart';
   
   void main() {
     ResearchPackage.ensureInitialized();
     runApp(const MyApp());
   }

   ensureInitialized() registers the model classes that fromJson() needs to load tasks and results from JSON. If a consent flow asks for permissions, also pass a permission requester as permissionRequester. See Permissions.

3. Register the localization delegates

   Add the delegates and the languages your app supports to your MaterialApp:

   import 'package:flutter/material.dart';
   import 'package:flutter_localizations/flutter_localizations.dart';
   import 'package:research_package/research_package.dart';
   
   class MyApp extends StatelessWidget {
     const MyApp({super.key});
   
     @override
     Widget build(BuildContext context) => MaterialApp(
       supportedLocales: const [Locale('en'), Locale('da')],
       localizationsDelegates: [ 
         RPLocalizations.delegate,
         GlobalMaterialLocalizations.delegate,
         GlobalCupertinoLocalizations.delegate,
         GlobalWidgetsLocalizations.delegate,
       ],
       home: const HomePage(),
     );
   }

   RPLocalizations.delegate loads the package's own texts, which exist in Chinese (Simplified), Danish, English, French, Hungarian, Portuguese and Spanish. It then loads your app's translation file for the language and lets it override the package's texts. For any other language, your file must also translate the package's texts, or the screens show their keys.

   Write the list without const: RPLocalizations.delegate is not a constant.

4. Add the translation files

   In assets/lang/, create one file for each language in supportedLocales, named after the language code: en.json and da.json for the app above. A file holds your translations as a JSON object, which may be empty until you add any:

   {}

   Then declare the folder as an asset:

   flutter:
     uses-material-design: true
     assets:
       - assets/lang/

   Warning

   RPLocalizations.delegate requires these files. When the file for the current language is missing, the delegate fails to load, and the app does not show its first screen. An app without translation files uses RPLocalizationsDelegate(loaders: const []) instead, which loads only the package's own texts.

   For the file format, keys and plurals, see Localization.

Add media and sound assets

Instruction steps, image choices and timer steps load files from your app's assets. Add only the ones your tasks use:

The package does not bundle the timer sound into your app. Copy RPTimerStepSound.mp3 from the example app, or use your own sound under that name.

Declare each folder you use:

flutter:
  uses-material-design: true
  assets:
    - assets/lang/
    - assets/images/
    - assets/audio/
    - assets/video/

imagePath, audioPath and videoPath also accept URLs. See Instruction step.

Configure Android and iOS

Research Package asks for no permissions and needs no manifest or Info.plist entries for surveys, consent screens and asset media. Each platform still has a minimum version:

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

Load media from https URLs: by default, both platforms block video and audio over plain http.

A consent flow that sets askPermission asks through your app's permission requester, which brings its own platform setup. See Permissions.

Troubleshooting

Next step