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
- 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.
- É necessário o versionamento de todo código-fonte do App (*.js, *.css, *.html, etc.).
- 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.
- 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.
- Caso o aplicativo não consiga ser testado completamente, a liberação do aplicativo será negada no mesmo momento.
- 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
- Liberação de Endpoints: Até 5 dias úteis
- Homologação de App: Até 7 dias úteis
- 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#
Parâmetro | Descrição | Tipo | Exemplo |
---|---|---|---|
appName | Nome do app | string |
Mamba App |
defaultName | Nome único de identificação do app no TMS | string |
Mamba App |
appVersion | Versão do app | number |
2.0.0 |
appDescription | Descrição que será exibida na loja | string |
Starter temp... |
id | Id único do app (4 dígitos) | number |
1234 |
displayedName | Nome do app, exibido na POS e loja | string |
Mamba App |
iconPath | URL do ícone (Mínimo de 50x50, proporção 1:1) | url |
assets/logo.bmp |
autoInitiable | Define se poderá ser iniciado assim que a POS ligar | boolean |
true |
appPasswordProtectionLevel | Define se o app pedirá senha antes de abrir | number |
0 ou 1 |
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:
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