API de interação com o Super-APP AME
Toolset de interação com a camada de Super App
Para instalar no mini-app (enquanto estamos sem publicar com um nome definitivo):
npm i ame-super-app-client -s
Para atualizar no mini-app:
npm up ame-super-app-client
Caso o a api não seja atualizada pelas as vias normais...
rm -rf ./node_modules/ame-super-app-client
npm install
Para utilizar no mini-app é necessário importar a API:
import Ame from "ame-super-app-client";
Métodos da API
Operações HTTP
Existem métodos para realizar requisições HTTP.
Método GET
import Ame from "ame-super-app-client";
Ame.get(url, [config]);
Método POST
import Ame from "ame-super-app-client";
Ame.post(url, [config]);
Método PUT
import Ame from "ame-super-app-client";
Ame.put(url, [config]);
Método DELETE
import Ame from "ame-super-app-client";
Ame.delete(url, [config]);
Métodos para obtenção de informações do usuário
Método askUserData
Permite requisitar os dados do usuário. Caso o usuário aceite, a função retorna um objeto com os dados do usuário. Caso o usuário não aceite, a função lança uma excessão.
import Ame from "ame-super-app-client";
Ame.askUserData()
.then(user => {
// usuario deu permissao para ler os dados
console.log(user);
/* Exemplo de saída desse console.log:
{
"phone": "21994291123",
"documentType": "CPF",
"documentNumber": "55410786360",
"email": "johndoe@domain.com",
"name": "John Doe",
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
} */
})
.catch(err => {
// usuario negou acesso aos dados
});
Método askDefaultAddress
Permite requisitar o endereço padrão cadastrado no super-app. Caso o usuário aceite, a função retorna um objeto com os dados do endereço. Caso o usuário não aceite, a função lança uma excessão.
import Ame from "ame-super-app-client";
Ame.askDefaultAddress()
.then(address => {
// usuario deu permissao para ler os dados (nome, cpf, email, etc.)
console.log(address);
/* Exemplo de saída desse console.log:
{
"address": "Rua São Clemente",
"number": "258",
"district": "Botafogo",
"state": "RJ",
"city": "Rio de Janeiro",
"zipCode": "22260-004",
"countryCode": "BRA",
"additionalInfo": "4º andar"
} */
})
.catch(err => {
// usuario negou acesso aos dados
});
Método askLocation
Obtém dados da localização atual do usuário, é necessário que o usuário conceda o acesso à localização do dispositivo.
import Ame from "ame-super-app-client";
Ame.askLocation().then(location => {
console.log(location)
/* Exemplo de saída desse console.log:
{
mocked: false,
timestamp: 1567520589000,
coords: {
speed: 0,
heading: 0,
accuracy: 20,
altitude: 5,
longitude: -122.08400000000002,
latitude: 37.421998333333335
}
} */
});
Métodos de navegação
Os métodos listados abaixo estão relacionados à navegação entre as diferentes "views" do app
Método navigate
Permite navegar entre as diferentes "views" do miniapp, conforme definidas no diretório src/views
, passando-se parâmetros quaisquer entre elas. Então, no caso de uma estrutura de arquivos do miniapp que possui as views Index
e Confirm
(ou seja, os arquivos Index.js
, Index.jsx
, Confirm.js
e Confirm.jsx
) , pode ser usado no arquivo Index.js
:
import Ame from "ame-super-app-client";
state = {
productName: "Celular",
productColor: "Cinza"
};
Ame.navigate("/Confirm", state);
Método navigateBack
Realiza o retorno da view atual para a anterior na stack de navegação
import Ame from "ame-super-app-client";
Ame.navigateBack()
Método closeMiniApp
import Ame from "ame-super-app-client";
Ame.closeMiniApp().then(() => console.log("Mini-app fechado"));
Métodos de pagamento
Método startPayment
Permite que o usuário inicie o fechamento de um pedido, lançando a tela de pagamentos do super-app.
import Ame from "ame-super-app-client";
let item = { name: "my product", price: 1.99 };
// o valor tem que ser em centavos, ou seja, 1.99 vira 199
let itemPrice = parseInt(item.price * 100, 10);
let paymentOrder = {
title: "Titulo",
description: "Descricao",
walletToken: "999999-99999999-99999999-99999999", //opcional, somente para miniapps multi wallet
amount: itemPrice,
cashbackAmountValue: 0,
customPayload: {
cartId: "12345" /* Dados customizados para fechar o pedido apos pagamento */
},
hasOrderDetails: false // opcional, somente para miniapps com suporte a ver detalhes de pedido. Ler mais na seção "Exibição de detalhes do pedido"
callbackUrl:
"https://yourdomain.com/api/checkout" /* URL para a API da Ame enviar os dados de pagamento */,
items: [
{
description: item.name,
quantity: 1,
amount: itemPrice
}
]
};
// abre a tela de pagamento da Ame
Ame.startPayment(paymentOrder)
Ao realizar um pagamento, a URL informada em callbackUrl será requisitada passando o corpo abaixo:
{
"id": "1b8bb06b-b217-460a-9a41-72279a0f8123",
"date": [2019, 8, 4, 20, 28, 6, 658839000],
"operationType": "DEBIT",
"name": "Compra on-line",
"title": "Titulo",
"description": "Descricao",
"status": "AUTHORIZED",
"type": "PAYMENT",
"currency": "BRL",
"cashType": "CARD",
"amount": 199,
"amountRefunded": 0,
"splits": [
{
"id": "4b109db8-08eb-4404-9fb0-4bbcfae0a123",
"date": [2019, 8, 4, 20, 28, 6, 658868000],
"status": "AUTHORIZED",
"cashType": "CARD",
"amount": 199,
"installments": 1,
"cardMasked": "409602######6243",
"cardBrand": "VISA"
}
],
"attributes": {
"payOnce": true,
"transactionChangedCallbackUrl": "https://yourdomain.com/api/checkout",
"items": [
{
"description": "my product",
"amount": 199,
"quantity": 1
}
],
"customPayload": {
"cartId": "12345"
},
"orderId": "3aa8e856-f54b-4caa-aa17-97eb62d25123"
},
"operationReference": null,
"peer": null
}
Métodos de alerta
Métodos para exibir uma janela modal ao usuário, seja para exibir informação para ele, ou para pedir confirmação antes de executar operações importantes
Método alert
Abre uma janela modal que exibe uma informação e permite o usuário clicar em um botão para fecha-lá.
import Ame from "ame-super-app-client";
Ame.alert({title: "Título da modal", description: "Texto da janela", buttonText: "Texto dentro do botão"})
Método confirm
Abre uma janela modal que exibe uma informação e permite o usuário clicar em um botão para confirmar ou em um botão para cancelar a ação.
import Ame from "ame-super-app-client";
Ame.confirm({title: "Título da modal", description: "Texto da janela", buttonText: "Texto dentro do botão"})
Ame.confirm({
title: "Título da modal",
description: "texto a ser exibido",
confirmText: "Texto do botão de confirmar",
cancelText: "Texto do botão de cancelar"
})
.then(() => { /* Código a ser executado ao confirmar */ })
.catch(() => { /* Código a ser executado ao cancelar */ })
Demais métodos
Métodos que não se encaixam em nenhuma outra categoria
Método pickAddress
Abre uma tela que permite selecionar um endereço e retorna os dados do endereço selecionado.
import Ame from "ame-super-app-client";
Ame.pickAddress().then(address => {
console.log(address)
/* Exemplo de saída desse console.log:
{
countryCode: 'BRA',
additionalInfo: '',
zipCode: '12345-678',
main: 'true',
state: 'RJ',
city: 'Rio de Janeiro',
district: 'Centro',
number: '1',
address: 'Beco Diagonal',
customerId: '85b6e3c8-85b6e3c8-85b6e3c8-85b6e3c8-85b6e3c8'
} */
});
Método openBarcodeScanner
import Ame from "ame-super-app-client";
Ame.openBarcodeScanner()
.then(barcodeData => {
//{data: "4123412341234", type: "ean13"}
})
.catch(e => console.log("erro ao executar a leitura de código de barras", e));
Abrir QR Code trocando textos das telas
import Ame from "ame-super-app-client";
const barCodeOptions = {
screens: {
// Tela do leitor de código de barras
reader: {
// Texto que fica acima do leitor de código de barras
text: 'Posicione o leitor em cima do código de barras ou do QR Code',
// Texto do botão para informar o código de barras
button: 'Digite código de barras',
},
// Tela para informar o código
input: {
// Título acima do campo de código de barras
title: 'Por favor informe o código:',
// Label do campo de código de barras
label: 'Código',
// Texto do botão para enviar o código de barras
button: 'Pagar',
description: [
{
label: 'Favorecido:',
value: 'Estacionamento Novo Shopping',
},
],
},
}
};
Ame.openBarcodeScanner(barCodeOptions).then(barcodeData => {
//{data: "4123412341234", type: "ean13"}
}).catch(e => console.log("erro ao executar a leitura de código de barras", e));
Método getEnvironment
import Ame from "ame-super-app-client";
Ame.getEnvironment()
.then(env => console.log(`Ambiente ${env}`))
.catch(e => console.log("erro ao recuperar o ambiente.", e));
Método makePhoneCall
import Ame from "ame-super-app-client";
Ame.makePhoneCall("21999999999");
Método openBrowser
import Ame from "ame-super-app-client";
Ame.openBrowser({url: "https://google.com"});
Método pickAddress
Abre uma tela que permite selecionar um endereço e retorna os dados do endereço selecionado.
import Ame from "ame-super-app-client";
Ame.pickAddress().then(address => {
console.log(address)
/* Exemplo de saída desse console.log:
{
countryCode: 'BRA',
additionalInfo: '',
zipCode: '12345-678',
main: 'true',
state: 'RJ',
city: 'Rio de Janeiro',
district: 'Centro',
number: '1',
address: 'Beco Diagonal',
customerId: '85b6e3c8-85b6e3c8-85b6e3c8-85b6e3c8-85b6e3c8'
} */
});
Método getOrderDetails
Obtém informações sobre um pagamento. Esse método deve ser utilizado apenas na view OrderDetails
, e é utilizado para exibir informações específicas sobre um pedido. Mais detalhes na seção "Exibição de detalhes do pedido"
import Ame from "ame-super-app-client";
Ame.getOrderDetails()
.then(orderDetails => {
console.log(orderDetails)
/* Exemplo de saída desse console.log:
{
orderId: "1b8bb06b-b217-460a-9a41-72279a0f8123"
} */
})
.catch(response => {
console.log("Erro ao recuperar detalhes do pedido: ", response)
})
Exibição de detalhes do pedido
Dependendo do pedido feito no MiniApp, pode ser necessário que o usuário verifique informações sobre o pedido. Por exemplo, caso esteja fazendo uma entrega de uma encomenda, é interessante que o usuário tenha a oportunidade de rastrear o pedido. Ou, pode ser importante que, em uma outra situação, o usuário tenha acesso a um QR Code após a compra.
É necessário seguir alguns passos para ter suporte à exibição de detalhes do pedido
- Na
callbackUrl
passada noAme.startPayment
do pedido, fazer com que essa url registre as informações do pedido Ame (em particular, oid
da raiz do objeto*) e as associe com as informações do pedido no seu backend
* Esse id
é o primeiro id no objeto de exemplo da documentação do Ame.startPayment
. É importante notar que não é o id
dentro de splits
, e nem o orderId
dentro de attributes
Passar o parâmetro
hasOrderDetails
com valortrue
no objeto passado para oAme.startPayment
Criar uma view nomeada
OrderDetails
no miniapp, e nela, chamar a funçãoAme.getOrderDetails
para obter oid
do pedido Ame e buscar em seu backend as informações do pedido a serem exibidas para o usuário
Note que não deve haver navegação normal (através de Ame.navigate
) levando à view OrderDetails
, pois ela não ira funcionar se não for acessada através do detalhamento de pedido do App da Ame
Testando os detalhes de pedido
Antes de publicar o miniapp, é possível testar a funcionalidade de exibição dos detalhes do pedido usando a cli ame-app-tools
. Mais informações sobre como utilizá-la na documentação da mesma.