Introduçã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/Button.html';

  export default {
    components: {
      Button,
    },
  };
</script>
<script>
  export default {
    components: {
      Button: '@mamba/button/Button.html',
    },
  };
</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.

Regras#

  • É 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.
  • 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

Sobre o preenchimento do arquivo README.md 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.

Sobre o preenchimento do arquivo CHANGELOG.md do App:

  • A cada versão enviada para homologação, é necessário especificar as alterações feitas no app. O modelo desse arquivo é livre, desde que tenha declarado as alterações que foram feiras na versão a ser homologada. Um bom exmeplo é o keepachangelog.com

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

Exemplos

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