senior_platform_authentication_ui 4.1.0

A package that make it easy to implement the Senior X authentication for Flutter. Built to be used with the bloc state management package.

Senior Platform Authentication Ui

O objetivo deste projeto é prover uma experiência única de autenticação com aplicativos integrados a Senior X. Este pacote utilizar o pacote em dart senior_platform_authentication que fornece uma integração já implementada ao backend de autenticação do Senior X.

Sendo assim, para manter a integridade da experiência de autenticação, é importante que aplicativos que necessitem de autenticação com a plataforma Senior-X tenham dependência deste pacote. Caso seja necessário alguma adaptação ou customização maior no fluxo de autenticação, pode-se utilizar o pacote senior_platform_authentication e implementar as regras de forma manual ou contribuir com este pacote para adicionar os casos de usos necessários.

Arquitetura

A arquitetura foi baseada no Clean Architecture, entretanto com algumas adaptações para o escopo do projeto após análise técnica da equipe responsável pelo desenvolvimento incicial deste projeto.

Como utilizar

Adicione o pacote no pubspec.yaml e execute flutter pub get:

dependencies:
  senior_platform_authentication_ui: ^1.0.1

Verifique qual a última versão disponível no pub.dev

Importe o pacote senior_platform_authentication_ui.

import 'package:senior_platform_authentication_ui/senior_platform_authentication_ui.dart';

É obrigatório que a classe principal seja inicializada na main thread de sua aplicação.

SeniorAuthentication.initialize();

Também podemos inicializar escolhendo o ambiente para o qual as requisições irão ser direcionadas:

SeniorAuthentication.initialize(
  platformEnvironment: PlatformEnvironment.homolog,
);

Além disso, existem outras configurações disponíveis no método initialize, veja:

Parâmetro	Valor default	Descrição
platformEnvironment	PlatformEnvironment.production	Ambiente em que as requisições serão direcionadas.
enableLoginOffline	false	Habilita ou desabilita o login offline. Tem efeito somente quando utilizado em conjunto com o package senior-platform-authentication-ui.
automaticLogon	true	Define se o login deve ser feito de forma automática. Tem efeito somente quando utilizado em conjunto com o package senior-platform-authentication-ui e quando enableLoginOffline estiver habilitado.
includePhoto	false	Habilita ou desabilita a inclusão da photo do usuário nas chamadas de getUser.
baseUrl	''	Deve ser usado apenas quando platformEnvironment possuir o valor PlatformEnvironment.custom. Define a baseUrl de forma customizada.
frontendUrl	''	Deve ser usado apenas quando platformEnvironment possuir o valor PlatformEnvironment.custom. Define a frontendUrl de forma customizada.

Coloque um BlocProvider na raiz da aplicação Flutter. Deste modo, poderá ter acesso ao estado da autenticação a qualquer momento do ciclo de vida de seu aplicativo.

**Obs: É extremamente recomendável colocar o componente base do Senior Design System no primeiro nível e logo abaixo dele o BlocProvider. O pacote senior_platform_authentication_ui foi construído com dependência do Design System da Senior.

class ExampleApp extends StatelessWidget {
  const ExampleApp({super.key});

  @override
  Widget build(BuildContext context) {
    return SeniorDesignSystem(
      child: BlocProvider(
        create: (context) =>
            AuthenticationBloc()..add(CheckAuthenticationRequested()),
        child: const AppView(),
      ),
    );
  }
}

É importante ressaltar que o AuthenticationBloc funciona como um singleton.

Recomendamos utilizar a seguinte abordagem para controle de rotas conforme o status da autenticação:

class AppView extends StatefulWidget {
  const AppView({super.key});

  @override
  State<AppView> createState() => _AppViewState();
}

class _AppViewState extends State<AppView> {
  final _navigatorKey = GlobalKey<NavigatorState>();

  NavigatorState get _navigator => _navigatorKey.currentState!;

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: _navigatorKey,
      builder: (context, child) {
        return BlocListener<AuthenticationBloc, AuthenticationState>(
          listener: (context, state) {
            switch (state.status) {
              case AuthenticationStatus.authenticated:
                _navigator.pushAndRemoveUntil<void>(
                  MaterialPageRoute<void>(builder: (_) => const HomeScreen()),
                  (route) => false,
                );
                break;
              case AuthenticationStatus.unauthenticated:
                _navigator.pushAndRemoveUntil<void>(
                  MaterialPageRoute<void>(
                    builder: (_) => const LoginScreen(),
                  ),
                  (route) => false,
                );
                break;
              case AuthenticationStatus.unknown:
                break;
            }
          },
          child: child,
        );
      },
      onGenerateRoute: (_) => SplashScreen.route(),
    );
  }
}

Como contribuir

Para contribuir, basta abrir um Merge Request para algum dos mantedores do projeto seguindos as boas práticas acordadas nas seções abaixo.

Cobertura de testes

Entendemos que para manter a qualidade e integridade do código, é exigido uma cobertura de testes de pelo menos 80% para o que foi desenvolvido. Nossa sugestão é utilizar as extensões Coverage Gutters e Flutter Coverage para desenvolvimento dos testes.

Formatação de código

Já está incluído um arquivo de configuração com as configurações de identação do projeto, por padrão utilizamos o reocmendável do SDK (80). Por favor, não modificar e seguir este padrão.

Modificando arquivos .arb (Internacionalização)

No momento que este package está sendo publicado, existe um problema de referência do Flutter em encontrar os arquivos gerados pelo flutter gen-l10n em projetos que são do tipo package. Dessa forma, precisamos gerar os arquivos do flutter gen-l10n sobrescrevendo o caminho de output dos arquivos gerados.

Sendo assim, para sincronizar as traduções do l10n, deve-se utilizar o seguinte comando após modificar arquivos .arb:

flutter gen-l10n

Os arquivos gerados app_localizations_en.dart, app_localizations_es.dart, app_localizations_pt.dart e app_localizations.dart devem ser regerados e versionados através do comando acima, sempre que um arquivo .arb de tradução for modificado.

Armazenar dados locais

Utilizamos o package flutter_secure_storage para armazenamento de dados locais. Existem hoje dois local datasources para armazenagem, o SecureStorageDatasource e o PreferencesStorageDatasource. O primeiro possui como objetivo armazenar apenas dados referentes a autenticação, como token, expiração e usuário por exemplo. O segundo serve para armazenar preferencias do usuário, como por exemplo se a mensagem do onboarding do SAML está habilitada.

Caso seja necessário armazenar mais dados no futuro, cabe ao desenvolvedor avaliar o contexto se é algo de preferências do usuário, utilizar o PreferencesStorageDatasource. Caso seja relacionado a algum dado sensível da autenticação, utilizar o SecureStorageDatasource.