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";
Operações HTTP
Existem métodos para realizar requisições HTTP.
GET
Ame.http.get(url, [config]);
POST
Ame.http.post(url, [config]);
PUT
Ame.http.put(url, [config]);
DELETE
Ame.http.delete(url, [config]);
Nota:
Chamadas dos métodos http sem o namespace http ainda são suportadas (Exemplo: Ame.get(...) ), mas estão deprecadas e serão removidas em uma versão futura da API.
Métodos para obtenção de informações do usuário
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.
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
});
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.
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
});
askLocation
Obtém dados da localização atual do usuário, é necessário que o usuário conceda o acesso à localização do dispositivo.
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 miniapp
navigation.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 :
let state = {
productSKU: "9999999A",
productColor: "Cinza"
};
Ame.navigation.navigate({path: "/Confirm", state:state});
Replace Path (substitui a view corrente com a nova view na pilha de ações)
Ame.navigation.navigate({path: "/Confirm", state: {productSKU: "9999999A"}, replace: true});
navigation.back
Realiza o retorno da view atual para uma anterior na pilha de navegação
Para voltar um nível:
Ame.navigation.back()
Para voltar vários níveis:
Ame.navigation.back(3)
Notas:
Chamar
Ame.navigation.back()é equivalente a chamarAme.navigation.back(1)Ao chamar
Ame.navigation.backquando a pilha de navegação está vazia, o miniapp será fechadoAo chamar
Ame.navigation.back(n)quando a pilha de navegação tem menos denpáginas, o Miniapp voltará para a primeira página da pilha. Esse, porém, não é o uso projetado desse método. Considere usarAme.navigation.backToTopcaso seja esse o efeito desejado.
navigation.backToTop
Volta para o topo da pilha de navegação.
Ame.navigation.backToTop()
navigate
Deprecado. Utilize Ame.navigation.navigate ao invés de Ame.navigate
navigateBack
Deprecado. Utilize Ame.navigation.back ao invés de Ame.navigateBack
navigateBackToTop
Deprecado. Utilize Ame.navigation.backToTop ao invés de Ame.navigateBackToTop
closeMiniApp
Ame.closeMiniApp().then(() => console.log("Mini-app fechado"));
Métodos de pagamento
startPayment
Permite que o usuário inicie o fechamento de um pedido, lançando a tela de pagamentos do super-app.
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, // o valor tem que ser em centavos, ou seja, 1.99 vira 199
cashbackAmount: 0, // o valor tem que ser em centavos, ou seja, 1.99 vira 199
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
alert
Abre uma janela modal que exibe uma informação e permite o usuário clicar em um botão para fecha-lá.
Ame.alert({title: "Título da modal", description: "Texto da janela", buttonText: "Texto dentro do botão"})
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.
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
pickAddress
Abre uma tela que permite selecionar um endereço e retorna os dados do endereço selecionado.
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'
} */
});
openBarcodeScanner
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
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));
getEnvironment
Ame.getEnvironment()
.then(env => console.log(`Ambiente ${env}`))
.catch(e => console.log("erro ao recuperar o ambiente.", e));
makePhoneCall
Ame.makePhoneCall("21999999999");
openBrowser
Ame.openBrowser({
url: "https://google.com",
openInApp: true // optional - default false
});
openUrlScheme
Ame.openUrlScheme({
url: "tg://resolve?domain=translate_bot",
});
getClipboard
Obtém os dados de texto do clipboard do device
Ame.getClipboard();
setClipboard
Escreve dados de texto do clipboard do device
Ame.setClipboard("novo conteúdo do clipboard");
getDeviceSpecs
Retorna dados a respeito do device que está sendo utilizado
Ame.getDeviceSpecs().then(specs => {});
Dados de retorno
specs = {
"hasBottomGestureBar": true,
//se o telefone tem a barra de navegação inferior, como os iPhones a partir da versão X
"platform": "ios"
// ios / android
}
shareMiniApp
Realiza o compartilhamento de um deeplink que abrirá diretamente o miniApp corrente ao ser clicado. Este método abre a interface de compartilhameto padrão de cada sistema operacional
Ame.shareMiniApp();
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"
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)
})
pickImage
Requisita uma ou mais imagens ao usuário. O usuário podera escolher se quer tirar uma foto na hora ou selecionar imagens de sua galeria de fotos. O método retorna uma promise com um array com os conteúdos das fotos encodados em base64. Caso o processo seja cancelado pelo usuário, a promessa é rejeitada
Ame.pickImage()
.then(response => {
response.map((image, index) => {
console.log("Imagem " + index + " sendo processada")
//image é uma string com o conteúdo da imagem em base64
//Processa a imagem
})
})
.catch(() => {
console.log("Processo de seleção de imagem cancelado pelo usuário")
})
showToast
Método que oferece uma notificação para o usuário, no formato Toast. Usado para exibir mensagens rápidas e temporais no rodapé do aparelho. Utilize o Toast como um recurso para mensagens simples ao usuário.
Ame.showToast({
message: "Mensagem do toast", //message obrigatório
position: "bottom" //valor default
})
O parametro position é uma string com os possíveis valores de: top, bottom ou center.
vibrateDevice
Ame.vibrateDevice({
duration: 400 //valor default
})}
sendGoogleAnalytics
O método oferece o envio de hits ao google analytics, pelo usuário.
- O parâmetro deve ser um objeto com os seguintes atributos version, hitType, trackingId, documentLocation, clientID.
version: É versão do protocolo de avaliação. Atualmente o valor utilizado é'1'. Quando houver alterações, não compatíveis na ordem inversa, ele mudará.
hitType: É o tipo de hit que será enviado ao google analytics. O hitType deve ser um dos seguintes: "pageview", "screenview", "event", "transaction", "item", "social", "exception" ou "timing".
trackingId: Pode ser definido como ID de acompanhamento. Deve ser do formato UA-XXXX-Y. Todos os dados coletados são associados a esse ID.
documentLocation: Esse parâmetro tem como objetivo definir a view que está sendo monitorada.
clientID (opcional): Esse parâmetro tem como objetivo identificar determinado usuário, dispositivo ou instância de navegador de modo anônimo
const urlConfig = {
version: '1',
hitType: 'pageview',
trackingId: 'UA-XXXX-Y',
documentLocation:'/name_view',
clientID:'35009a79-1a05-49d7-b876-2b884d0f825b'
}
Ame.sendGoogleAnalytics(urlConfig)
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:
No endpoint que processa o webhook de pedido, informado durante o
Ame.startPaymentatravés do parâmetrocallbackUrl, armazenar oidcontido na raiz do objeto json vindo no request, para futuro relacionamento entre opedidoda sua plataforma e aordem de pagamentona AMEEnviar o parâmetro
hasOrderDetailscom valortrue, no objeto passado para oAme.startPayment, apenas para os pedidos em que seja necessário existir uma tela de detalhes customizadaCriar uma view nomeada
OrderDetailsno miniapp, e nela, chamar a funçãoAme.getOrderDetailspara obter oiddo pedido Ame e buscar em seu backend as informações do pedido a serem exibidas para o usuário
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.