⏱ 18 mins remaining

Flutter

Learn how the Flutter SDK works

Onboarding

Overview

The atPlatform uses secret keys for authenticating an atSign as cryptographically secure replacement for usernames and passwords. To improve developer experience, the atPlatform offers the at_onboarding_flutter package which handles secure management of these secret keys. If you are developing a new atPlatform app, we recommend that you use at_app which can create atPlatform app template that already contains an example of using the at_onboarding_flutter widget.

Once the onboarding widget is opened, the user can click one of the four options:

  1. Upload backup key file - subsequent onboard: person possesses an activated and already onboarded atSign with the .atKeys file)
  2. Generate Free atSign - need new atSign: person requires a new atSign and its .atKeys file.
  3. Scan QR Code - one-time activation: person has an unactivated atSign (no .atKeys file) but possess the QR code containing the cram secret
  4. Activate atSign one-time activation: person has an unactivated atSign (no .atKeys file) but possesses the atSign and access to the email associated with it to provide the OTP.

Installation

The at_onboarding_flutter package provides a widget that can be used to onboard atSigns.

  1. Add the package by running the following command in your terminal:
flutter pub add at_onboarding_flutter
  1. Or add it to your pubspec.yaml manually:

Note: Be sure to check the updated version on pub.dev.

Also run flutter pub get to update your dependencies.

dependencies:
  flutter:
    sdk: flutter
  at_client_mobile: ^3.2.6
  at_utils: ^3.0.11
  at_onboarding_flutter: ^5.0.5

Usage

Simply call the .onboard method whenever you want your app to open the onboarding widget.

AtOnboarding.onboard(
  context: context, // BuildContext
  config: AtOnboardingConfig(
    atClientPreference: AtClientPreference()
      ..rootDomain = AtEnv.rootDomain // access AtEnv from the `at_app_flutter` package
      ..namespace = AtEnv.appNamespace
      ..hiveStoragePath = dir.path
      ..commitLogPath = dir.path
      ..isLocalStoreRequired = true,
    rootEnvironment: AtEnv.rootEnvironment,
    domain: AtEnv.rootDomain,
    appAPIKey: AtEnv.appApiKey,
  ),
);

Notes:

  • dir is a variable from holding data retrieved from the path_provider package: var dir = await getApplicationSupportDirectory();
  • AtEnv comes from at_app_flutter which helps with providing various arguments like accessing the .env file and providing the rootDomain and appNamespace constants.

Example

The example below demonstrates the onboarding widget being opened upon pressing this ElevatedButton widget. Since the .onboard method returns a AtOnboardingResult object, we store it in a variable and use it to determine what to do next. If the onboarding process was successful, we move onto a different page using Navigator, otherwise, we display an error.

ElevatedButton(
  child: const Text('Onboard an @sign'),
  onPressed: () async {
    var dir = await getApplicationSupportDirectory(); // from the `path_provider` package
    AtOnboardingResult onboardingResult = await AtOnboarding.onboard(
      context: context, // BuildContext
      config: AtOnboardingConfig(
        atClientPreference: AtClientPreference()
          ..rootDomain = AtEnv.rootDomain // access AtEnv from the `at_app_flutter` package
          ..namespace = AtEnv.appNamespace
          ..hiveStoragePath = dir.path
          ..commitLogPath = dir.path
          ..isLocalStoreRequired = true,
        rootEnvironment: AtEnv.rootEnvironment,
        domain: AtEnv.rootDomain,
        appAPIKey: AtEnv.appApiKey,
      ),
    );
    switch (onboardingResult.status) {
      case AtOnboardingResultStatus.success:
        Navigator.push(context, MaterialPageRoute(builder: (_) => const HomeScreen()));
        break;
      case AtOnboardingResultStatus.error:
        ScaffoldMessenger.of(context).showSnackBar(
          const SnackBar(
            backgroundColor: Colors.red,
            content: Text('An error has occurred'),
          ),
        );
        break;
      case AtOnboardingResultStatus.cancel:
        break;
    }
  },
),

Parameters

AtOnboarding.onboard

TypeNameDescriptionRequired?Default Value
BuildContextcontextThe context of the widget that is calling the .onboard method.true
AtOnboardingConfigconfigThe configuration object that contains the preferences for the onboarding widget.true
boolisSwitchingAtSignTrue - show the UI for switching a new atsign. false - checks if atSign is already onboarded (if already onboarded, does not show UI).falsefalse
String?atSignThe new atSign name if switching atSigns (isSwitchingAtSign should be true)falsenull

AtOnboardingConfig

The AtOnboardingConfig object is used to configure the onboarding widget. It contains the following properties:

TypeNameDescriptionRequired?Default Value
AtClientPreferenceatClientPreferenceobject used to configure preferences in your atPlatform application such as the namespace, hiveStoragePath, and maxDataSize.true
RootEnvironment (enum)rootEnvironmentThe set of servers your app will be running and talking to atSigns in (testing, staging, production)true
String?domainThe domain of the atDirectoryServer (previously called root server)falseroot.atsign.org
String?appAPIKeyThe API authentication key for getting free atsigns
boolhideReferencesIf true, hides the reference to web pages.falsefalse
boolhideQrScanIf true, hides the QR functionalityfalsefalse

AtOnboardingResult

This object is received when the .onboard method is called. It contains the following properties which can be used in your application:

TypeNameDescription
AtOnboardingResultStatus (enum)statusThe status of the onboarding process.
String?messageThe message returned when the onboarding process fails.
String?errorCodeThe error code when the onboarding process fails.
String?atSignThe atSign that was onboarded successfully.