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:

`typescript
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:
`typescript
config.modules.web = true;
`

- Para uma aplicação mobile:
`typescript
config.modules.web = false;
`

`typescript
export function mingleFactory() {
let config = new Configuration();
config.app_identifier = ;
config.environment = ;
config.server = ;
config.modules.crashr = ;
config.modules.usage_metrics = ;
config.modules.gateway = ;
config.modules.web = ;

return config;
}
`

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

`typescript
@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

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

Adicionar o MingleService no construtor da classe:

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

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

`typescript
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.

`typescript
this._mingleService.isReadyForAuthenticatedRequests();
`

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

`typescript
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):

`typescript
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:

`typescript
let url = 'customers';

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

this._mingleService.gateway
.get(url, {}, params)
.map(response => 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:

`typescript
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:

`typescript
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:

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

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

`typescript
@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.