Introdução editar esta seção

O Mamba SDK permite o desenvolvimento de aplicativos para o POS da Stone, habilitando uma experiência para o usuário que vai além de apenas pagamento. O Mamba é um sistema desenvolvido pelo time da Stone com suporte para POS. O Mamba SDK faz a abstração das funções do POS, facilitando o desenvolvimento de aplicativos em linguagem Web e, dessa maneira, simplificamos a inserção de aplicativos nos POS.

É necessário ter o Node.js instalado e ter alguma familiaridade com a linha de comando

Antes de começar a usar o Mamba SDK, recomendamos ter uma boa base de conhecimento de JavaScript ES2015.

O Mamba SDK utiliza o Svelte como framework UI, isso quer dizer que não temos um Virtual DOM como no React, Angular, Vue, entre outros. Portanto, os componentes são compilados para um JavaScript ideal durante o build.

Entendendo um componente em Mamba SDK#

Um componente é um arquivo html muito semelhante ao Vue.js. Ou seja, ele é um bloco de código autossuficiente e reutilizável que encapsula marcações, estilos e comportamentos que estão juntos.

Começando

1. Crie um novo projeto#

Utilizando a CLI

# Instale a CLI globalmente
npm i -g @mamba/cli

# Crie um novo aplicativo em 'my-mamba-app'
mamba new app my-mamba-app

? Name: My Mamba App
? Version: 0.0.1
? Description: My new Mamba app

# Entre no diretório do App.
cd my-mamba-app

Manualmente

Para iniciar, execute o seguinte comando:

git clone https://github.com/stone-payments/pos-mamba-app-template.git <my-app>
cd <my-app>

Depois é necessário instalar as dependências do projeto. É recomendado que seja utilizado o NPM para gerenciamento de dependências determinísticas, mas o npm install também pode ser utilizado.

npm install  # Instala dependências do projeto (ou `npm i`)

Desenvolvendo

Depois de concluir a etapa de instalação, você está pronto para iniciar o projeto!

npm run start # Inicie o ambiente de desenvolvimento

Usando alguns componentes da SDK#

Para componentes Web, instale o componente/pacote que deseja usar no projeto:

npm install @mamba/button # Componente do botão


# Se quiser usar o dialog por exemplo:

npm install @mamba/dialog

Para importar o componente instalado, basta seguir uma das formas abaixo:

<script>
  import Button from '@mamba/button';

  export default {
	components: { Button }
  }

<script>
  export default {
	components: {
	  Button: '@mamba/button'
	}
  }
</script>

Para módulos da API nativa:#

npm install @mamba/pos

Agora é só importar o módulo desejado, sempre desconstruindo objeto do pacote @mamba/native:

import System from '@mamba/pos/system.js'

Finalizando

Testando no Simulador Virtual#

Todos os apps da SDK, a partir da versão 2.0, possuem acoplado um simulador virtual da POS para agilizar o desenvolvimento. Basta rodar npm run start e depois acessar http://localhost:8080/ no seu navegador e o app se encontrará lá. Simples e rápido.

Build#

Antes de enviar sua aplicação para testar no POS é necessário realizar o build desta. Para isso, em seu terminal execute:

# Utilizando a CLI
mamba app build

# Manualmente
npm run build

Deploy#

Para testar suas aplicações em seu POS você deve primeiro ter o Aplicativo de Developer instalado e antes ter realizado o build da sua aplicação. Após, digite no terminal do seu computador:

npm run serve

Após o servidor iniciar, abra o aplicativo de developer em seu POS e digite o IP local da máquina. Após alguns segundos o seu app será automaticamente baixado e aparecerá na lista de aplicativos instalados do Aplicativo de Developer.

Compatibilidade#

O Mamba SDK foi desenvolvido para o WebKit 534.48.3 que é equivalente ao Safari 5.1.

Homologação

Antes de publicar seu Aplicativo em nossa loja e poder disponiza-lo para seus usuários este deverá passar pelo um processo de Homologação e tudo deverá estar de acordo com As Regras do Jogo.

Regras do Jogo

1. Sobre o preenchimento do arquivo README do App:
   • É preciso disponibilizar uma descrição básica da intenção de uso do App, na seção Objetivo
   • Precisamos que seja descrito o fluxo de funcionamento do App na seção Fluxo da Aplicação, com detalhes como usar o aplicativo, para ajudar no processo de homologação e fazer a liberação ser mais ágil.
   • Todas as dependências do App, bem como a disponibilização das instruções de build, precisam ser sinalizadas na seção Dependências.
   • Se o App utilizar comunicação por rede, é preciso listar com antecedência hosts e/ou IPs utilizados, na seção Endpoints. Cada alteração nos endpoints requer cadastro no proxy de aplicação e pode demorar até 5 dias úteis.
   • Precisamos que sejam fornecidos usuários e/ou chaves de testes, acesso temporário, entre outros, para testes das funcionalidades do APP durante o processo de Homologação. Devem ser listados, assim como qualquer passo necessário ao processo de Homologação, na seção Instruções para Homologação.
2. É necessário o versionamento de todo código-fonte do App (*.js, *.css, *.html, etc.).
3. Para que a homologação aconteça, deve ser exposto um ambiente de teste, assim como todos os dados de acesso com usuário e senha.
4. Não será possível fazer qualquer tipo de configuração ou instalação de softwares terceiros no ambiente de homologação, a homologação será realizada apenas com o aplicativo e nada mais.
5. Caso o aplicativo não consiga ser testado completamente, a liberação do aplicativo será negada no mesmo momento.
6. A estrutura de arquivos e de configuração do build deve ser compatível com as mais atuais alterações do repositório https://posgitlab.stone.com.br/stone-payments/pos-mamba-3rdparty-template

Tempo de Atendimento

1. Liberação de Endpoints: Até 5 dias úteis
2. Homologação de App: Até 7 dias úteis
3. Publicação na Loja: Até 2 dias úteis

Estrutura de diretórios

A estrutura de diretórios de nível superior se parece com o diagrama a seguir:

Mamba Web
├─ packages ······· Pacotes públicos
├─ tools ·········· Ferramentas de projeto, utilitários para construção e teste
└─ package.json ··· Configuração do projeto

Pacotes#

O diretório packages é onde todos os módulos do Mamba são mantidos. Cada subdiretório possui seu pacote NPM. Portanto, é possível instalar cada pacote separadamente no modelo em que está trabalhando.

Pode parecer algo como:

└─ packages
  ├─ components ··· Componentes Web feito em Svelte
  ├─ native ······· Pacotes nativos para controlar POS
  ├─ store ········ Armazenamento do tipo Redux para vincular aos componentes
  └─ styles ······· Pacote de estilos Mamba

Estrutura por pacote#

A estrutura para cada pacote (módulo) se parece com isso:

└─ packages
  └─ components
	└─ AppBar
	  ├─ dist ··········· Arquivos gerados automaticamente
	  ├─ example ········ Exemplos específicos do pacote
	  ├─ node_modules ··· Dependências NPM
	  ├─ src ············ Código fonte do pacote
	  ├─ CHANGELOG.md ··· Todo o histórico de alterações do pacote
	  ├─ README.md ······ Documentação de pacote com remarcação avançada
	  ├─ index.js ······· Ponto de entrada do pacote
	  ├─ LICENSE ········ Licença pacote
	  ├─ .gitignore······ Gitignore do pacote
	  └─ package.json ··· Configuração do NPM / Pacote

example(s)

A pasta example é onde todos os exemplos específicos de cada pacote estão localizados.

└─ packages
  └─ components
	└─ AppBar
	  └─ example
		├─ App.html
		└─ AnotherDemo.html

Manifest

O manifest.xml é o arquivo que contém todas as instruções do app para a publicação do seu app. O manifest é gerado automaticamente a partir do package.json, portanto, verifique se seu package.json está configurado corretamente antes de enviá-lo para homologação.

package.json

{
  "name": "my-mamba-app",
  "version": "0.0.1",
  "description": "Starter template for Mamba Applications.",
  "mamba": {
	"id": 99,
	"appName": "My Mamba App",
	"iconPath": "assets/logo.bmp",
	"appCreationDate": "2017-07-17T13:32:00",
	"appKey": "11-11-11-11",
	"autoInitiable": true,
	"appPasswordProtectionLevel": "1",
  }
}

manifest.xml

<MambaClass Type="Manifest" Version="1.0">
  <Member Name="appName">My Mamba App</Member>
  <Member Name="defaultName">my-mamba-app</Member>
  <Member Name="displayedName">My Mamba App</Member>
  <Member Name="appVersion">0.0.1</Member>
  <Member Name="appDescription">Starter template for Mamba Applications.</Member>
  <Member Name="appLastModificationDate">2019-10-22T15:28:57</Member>
  <Member Name="listInMainMenu">true</Member>
  <Member Name="appTechnology">1</Member>
  <Member Name="appType">0</Member>
  <Member Name="appPasswordProtectionLevel">0</Member>
  <Member Name="runOnUserSelection">index.html</Member>
  <Member Name="id">99</Member>
  <Member Name="iconPath">assets/logo.bmp</Member>
  <Member Name="appCreationDate">2017-07-17T13:32:00</Member>
  <Member Name="appKey">11-11-11-11</Member>
</MambaClass>

Parâmetros#

Migração 1.0 para 2.0

Um passo muito importante na transição da SDK 1.0 para a 2.0 é a Refatoração dos aplicativos. Isso deve ocorrer porque mudamos o motor utilizado por trás da nossa nova SDK, agora quem é responsável por isso é o Svelte. Desse modo, não será possível portar o código das aplicações após a atualização da SDK.

Apesar dessa tarefa parecer ser um pouco trabalhosa, os dois Frameworks são bem parecidos e para ajudá-los nessa transição nosso time de Developers preparou este guia.

Componentes

Os componentes fazem parte do núcleo central de qualquer aplicação, sejam elas produzidas utilizando a SDK 1.0 ou 2.0. Sendo assim, resolvemos começar nosso guia de migração por estes elementos.

Na nossa antiga SDK, um componente seguia a seguinte estrutura:

export default {
  template,
  components: {
	MyComponent
	// declaração dos componentes customizados que estão sendo utilizados no *.html
  },
  props: {
	// propriedades padrão do componente. Podem ser injetadas através da instância do componente.
	myProp: 1,
	myOtherProp: 'other'
  },
  state () {
	return {
	  // variáveis de estado inicial do componente
	  stateVariable: 15,
	  otherStateVariable: true
	}
  },
  onCreate () {
	// callback executada quando o elemento HTML do componente está pronto pra uso
  },
  onUpdate() {
	// callback executada quando o estado do componente precisa ser atualizado
	// use esta callback para atualizar o DOM
	console.log('Algo Mudou Aqui');
  },
  onDestroy() {
	// callback executada antes de o componente ser destruído
	console.log('Elemento Removido');
  },
  onMount() {
	// callback executada antes de o componente aparecer na tela
	console.log('Elemento Inserido no DOM');
  },
  onUnmount() {
	// callback executada antes de o componente ser removido da tela
  },
  methods: {
	// métodos do componente. Serão injetados na instância do componente.
	myMethod () {
	  console.log('esse método é público e faz parte da API do componente')
	}
  }
}

Em Svelte, eles parecem bastante:

export default {
  components: {
		MyComposverl
  },
  data() {
	return {
	  myProp: 1,
	  myOtherProp: 'other',
	}
  },
  oncreate() {
	console.log('Elemento Inserido no DOM');
  },
  onupdate() {
	console.log('Algo Mudou Aqui');
  },
  ondestroy() {
	console.log('Elemento Removido');
  },
  onstate({ changed, current, previou }) {
	// executado sempre que alguma alteração acontece
  },
  methods:{
	 myMethod () {
	  console.log('esse método é público e faz parte da API do componente')
	}   
  }
}

Outra parte importante é atribuição de valores às propriedades (props/data) do componente. Antigamente um valor podia ser acessado diretamente da seguinte forma:

// SDK 1.0

let myVar = this.myProp;
console.log(myVar); // 1
this.myProp = 2
console.log(this.myProp) // 2

Agora isso é feito da seguinte maneira:

//SDK 2.0

let myVarSvelte = this.get().myProp;
console.log(myVarSvelte);
this.set({myProp: 2});
console.log(this.get().myProp); // 2

Por fim, uma última modificação que também é importante são as refs, que facilitam o acesso a componentes e elementos do DOM. Antigamente, no HTML tínhamos:

<!-- SDK 1.0 -->
<MyComponent ref="myComponentRef"></MyComponent>

<!-- SDK 2.0 -->
<MyComponent ref:myComponentRef></MyComponent>

E para acessá-las:

// SDK 1.0
let myText = "Texto de Exemplo."
this.$refs.myComponentRef.innerText = myText;

// SDK 2.0
this.refs.myComponentRef.innerText = myText;

Aproveitando que falamos de refs e manipulação de elementos no DOM, é interessante também introduzi-los a linguagem de template do Svelte. Como vimos no exemplo acima, na versão 1.0 era necessário criar uma referência para inserir uma variável do JavaScript dentro de um elemento no DOM. Isso atualmente pode ser feito de modo muito mais fácil (desde que essa variável esteja na propriedade data():

<p>{myText}</p>

export default {
  components: {

  },
  data() {
	return {
	  myText: "Texto de Exemplo.",
	}
  },
}

O mais interessante é que dessa maneira a propriedade do componente se conecta two way data binding, ou seja caso a propriedade myText se altere, o texto dentro de <p> se altera no mesmo momento. Isso facilita muito, não? Além desta funcionalidade, a linguagem de template do Svelte possui diversas outras funcionalidades como: iterações, slots e propriedades computadas, sendo assim recomendamos fortemente que se acesse o guia de introdução deles clicando aqui

Para finalizar, aposto que mesmo após essa explicação, você ainda deve estar se perguntando sobre os componentes visuais de nossa SDK. Eles também sofreram modificações, começando pelo nome que não possui mais as iniciais Mb, a inclusão de novos componentes e a remoção de alguns que achamos que não fariam mais sentido existir. Para a lista completa dos componentes e suas utilizações acesse aqui.

Páginas

Outra parte importante durante o desenvolvimento de aplicações é a construção de páginas. Basicamente, uma página é uma coleção de componentes que juntos trabalham para compor um cenário, seja uma tela de login, cadastro ou de confirmação de compra. Na SDK 1.0, as páginas eram organizadas da seguinte maneira:

└─ pos-mamba-websdk-template
  └─ src
	└─ pages
	  └─ yourpage
		├─ index.js
		├─ yourpage.html
		└─ yourpage.scss

Agora, as páginas também são componentes Svelte e podem ter num único arquivo seu JS, CSS e HTML. Além disso, elas estão localizadas dentro da pasta routes, lembrando que essa organização diretório é um padrão de projeto nosso e pode ser alterado de acordo com suas necessidades.

└─ pos-mamba-websdk-template
  └─ src
	└─ routes
	  └─ yourpage.html

Como exemplo, temos:

// yourpage.html

<div class="my-page-style">
  <AppBarTitle label="My Page"/>
  <MyComponent>
  </MyComponent>
  <Button on:click="myPageMethod()">Click</Button>
</div>

<script>
  import { AppBarTitle } from '@mambasdk/appbar';

  export default {
	components: {
	  AppBarTitle,
	  Button: '@mambasdk/button',
	},
	data() {
	  return {
		MyData: null,
	  };
	},
	methods: {
	  myPageMethod() {
		console.log('Method Triggered')
	  },
	},
  };
</script>

<style>
  .my-page-style {
	padding: 15px;
	background-color: #fff;
	font-size: 18px;
	text-align: center;
  }
</style>

Rotas

Por fim, temos as rotas. Como sabemos, as rotas são a forma de conexão entre uma página e outra. Em nossa SDK 1.0 esse elemento era especificado da seguinte maneira:

// pos-mamba-websdk-template/src/router/index.js

import { MbRouter } from 'mamba-websdk'

import Example from '../pages/example'

export default new MbRouter({
  routes: [
	{
	  path: '/',
	  component: Example
	}, 
  ]
})

Agora, deve-se especificar as rotas diretamente no arquivo routes.js, dessa forma:

//  pos-mamba-app-template/src/routes.js
import Example from '../routes/Example.html'

export default {
  '/': Example,
}

Como pode ser visto, para a administração das rotas foi utilizado o svelte-page, caso deseje saber mais sobre como ele funciona clique aqui.

Considerações Finais

Acredito que podemos agora dizer que não é tão difícil adaptar um aplicativo feito na primeira versão da SDK para a mais atual, não é? Mas, ainda assim, deixaremos aqui um repertório de links que podem ajudá-lo:

• Documentação do Svelte
• Documentação Svelte-Page
• Canal do Discord do Svelte
• Documentação SDK 1.0

Caso tenha alguma dúvida sinta-se à vontade para nos procurar em nosso canal do Slack ou entrar em contato com nosso Time de Integrações