@totvs/mingle-client NPM

Mingle

Dependência de versões

@totvs/mingle-client: 1.0.0

@angular: 6.1.7
@rxjs: 6.3.2

O que é?

Uma biblioteca typescript para facilitar a comunicação de aplicações escritas em angular e ionic com o servidor Mingle .

Como usar?

Para começar a usar o Mingle, a primeira coisa a fazer é instalar o pacote necessário para seu funcionamento. Rode o seguinte comando na pasta do seu projeto:

$ npm i --save @totvs/mingle-client

Mingle com Ionic

Para utilizar o Mingle em uma aplicação Ionic é necessário rodar os seguintes comandos para instalar os plugins utilizados:

Ionic Native - Device

$ ionic cordova plugin add cordova-plugin-device
$ npm install --save @ionic-native/device

Ionic Native - Geolocation

$ ionic cordova plugin add cordova-plugin-geolocation --variable GEOLOCATION_USAGE_DESCRIPTION="To locate you"
$ npm install --save @ionic-native/geolocation

Ionic Native - Globalization

$ ionic cordova plugin add cordova-plugin-globalization
$ npm install --save @ionic-native/globalization

Ionic Native - Globalization

$ ionic cordova plugin add cordova.plugins.diagnostic
$ npm install --save @ionic-native/diagnostic

Configuração

No arquivo app.module.ts da aplicação, importar as classes responsáveis pelo módulo e pela configuração do Mingle:

import { Configuration, MingleModule } from '@totvs/mingle-client';

Definir um método para efetuar a configuração e informar ao Mingle o tipo do projeto. Para isso utilize a propriedade modules.web do objeto Configuration:

Para uma aplicação web:

config.modules.web = true;

Para uma aplicação mobile:

config.modules.web = false;

export function mingleFactory() {
  let config = new Configuration();
  config.app_identifier = <APP_ID>;
  config.environment = <DEV | PROD>;
  config.server = <http | https + MINGLE_SERVER_ADDRESS>;
  config.modules.crashr = <true | false>;
  config.modules.usage_metrics = <true | false>;
  config.modules.gateway = <true | false>;
  config.modules.web = <true | false>;
  
  return config;
}

Fazer a importação do MingleModule, passando como parâmetro do forRoot o método que o configura:

@NgModule({
  declarations: [...],
  imports: [
    ...,
    MingleModule.forRoot({
      provide: Configuration,
      useFactory: mingleFactory
    })
  ],
  bootstrap: [IonicApp],
  entryComponents: [...],
  providers: [...]
})
export class AppModule {}

No arquivo app.component.ts, importar as classes MingleService e MingleError

import { MingleService, MingleError } from '@totvs/mingle-client';

Adicionar o MingleService no construtor da classe:

constructor(..., private _mingleService: MingleService, ...)

A primeira coisa a fazer é inicializar o Mingle, e verificar se o usuário já está autenticado:

this._mingleService.init().subscribe(
  (res) => {
    console.log('Mingle inicializado');
    this._mingleService.getUser().subscribe(
      () => {
        if (!this._mingleService.getSessionInfo().user) {
          console.log('Sessão não iniciada');
          this.rootPage = LoginPage;
          // this.route.navigate(['login']); - projeto web
        } else {
          this.rootPage = HomePage;
          // this.route.navigate(['home']); - projeto web
        }
      }
    );
  }
);

Essa chamada irá registrar um evento de APP_INITIATED (Aplicativo inicializado).

Após isso é necessário verificar se as variáveis de autenticação já estão definidas. Uma exception será lançada no caso dos dados não estiverem setados. Sendo necessário realizar o login.

this._mingleService.isReadyForAuthenticatedRequests();

É possível efetuar o login com as credenciais passadas pelo usuário (Usuário/Senha/Alias)

this._mingleService.auth.login(user, password, alias)
  .subscribe(() => {
    console.log('Sign in ok');
    this._navCtrl.setRoot(HomePage);
    // this.route.navigate(['home']); - Projeto web
  },
  (authError) => {
    console.log('Erro de autenticação: Usuário ou senha invalidos!');
  }
);

Em caso de sucesso, um evento de USER_LOGIN será registrado. Caso contrário, um evento de WRONG_CREDENTIALS será gerado.

Para deslogar o usuário do sistema, usar o método logout do mingleService (um evento de USER_LOGOUT será gerado):

this.this._mingleService.auth.logout()
  .subscribe(
    () => {
      this._app.getRootNav().setRoot(LoginPage);
      // this.route.navigate(['login']); - Projeto web
      console.log("Usuário deslogado");
    }
  );

Módulo Gateway

A função do módulo gateway é fazer chamadas REST em um determinado backend previamente cadastrado no Mingle.

Para isso, envie para o mingle a URI do backend:

let url = 'customers';

let params = {
  page: 1,
  pageSize: 10
};

this._mingleService.gateway
  .get(url, {}, params)
  .map(response => <Customer[]>response.body)
  .subscribe(
    (customers) => {
      console.log('Customers: ', customers);
    }
  );

Além do método GET, também estão disponíveis os métodos POST, PUT, PATCH e DELETE.

Módulo Métricas

A função do módulo de métricas do Mingle é registrar quaisquer tipos de dados pertinentes para o app em questão.

Para o registro da métrica, é necessário informar apenas uma descrição:

this._mingleService.registerMetric('CUSTOMERS_VIEWED').subscribe();

Esse código registrará uma métrica informando que determinado usuário visualizou a lista de clientes, por exemplo.

Além do nome da métrica, o app pode passar, opcionalmente, quaisquer dados que façam sentido para sua aplicação, por exemplo:

let customData = {
  device3gEnabled: true,
  deviceWifiEnabled: false
};
this._mingleService.registerMetric('CUSTOMERS_VIEWED', customData).subscribe();

Baixe o código completo do projeto de exemplo em https://github.com/devtotvs/mingle-sample

Interceptor Http

Seu uso é indicado em situações onde não utiliza o método de Gateway do Mingle.

O Mingle também disponibiliza uma classe chamada MingleHttpInterceptor que funciona como um interceptador de requisições.

O objetivo desse interceptador é que a qualquer chamada http feita pelo app usando apenas o recurso, por exemplo: /api/customers, automaticamente será adicionado na requisição a url do Mingle, e os headers de Authorization (token), Content-Type e tenantId.

Para usar o MingleHttpInterceptor, basta configuar no app.module.ts:

Importar o interceptor do Mingle e a classe HTTP_INTERCEPTORS do angular:

import { MingleHttpInterceptor } from '@totvs/mingle-client';
import { HTTP_INTERCEPTORS } from '@angular/common/http';

Adicionar o interceptor na seção providers do NgModule:

@NgModule({
  declarations: [
    ...
  ],
  imports: [
    ...
  ],
  bootstrap: [IonicApp],
  entryComponents: [
    ...
  ],
  providers: [
    ...,
    { provide: HTTP_INTERCEPTORS, useClass: MingleHttpInterceptor, multi: true }
  ]

Depois dessas configurações, o mingle estará pronto para utilizar o interceptor automaticamente.