AME-SUPER-APP-CLIENT
API para desenvolvimento de mini-apps Ame
Usando a API
Para utilizar essa API no seu mini-app é necessário apenas importá-la nos arquivos .js
que irão chamar métodos dela:
import Ame from "ame-super-app-client";
Não é necessário instalar o pacote npm.
Compatibilidade com diferentes versões do runtime SDK
Em cada método da API é possível encontrar o Histórico de alterações, que exibe a compatibilidade dos métodos disponíveis na API com o Runtime SDK. À medida que novas versões da API são lançadas, alguns comportamentos podem mudar.
É importante verificar se a versão mais recente do método na API é suportado pela versão do Runtime SDK, para isto, utilize o método Ame.checkRuntimeSupportFor passando como parâmetro o valor indicado na coluna runtime SDK do Histórico de alterações como uma string do método que deseja utilizar.
if(await Ame.checkRuntimeSupportFor("1.9.0")){
Ame.shareMiniApp({
"param1": "value1",
"param2": "value2"
});
} else {
Ame.shareMiniApp();
}
Pacotes npm
É possível utilizar alguns pacotes npm pré-determinados dentro de um mini-app. Abaixo está a relação de pacotes disponíveis
Pacotes npm
esses pacotes podem ser utilizados tanto com a sintaxe ECMAScript 6 (import) ou CommonJs (require). Para instruções de como utilizar cada pacote, consulte a documentação dele no npm
Operações HTTP
Existem métodos para realizar requisições HTTP.
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.0.0 | http adicionado ao runtime |
GET
Ame.http.get(url, [config]);
POST
Ame.http.post(url, data, [config]);
PUT
Ame.http.put(url, data, [config]);
DELETE
Ame.http.delete(url, [config]);
Dados 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.
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.0.0 | askUserData adicionado ao runtime |
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.
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.0.0 | askDefaultAddress adicionado ao runtime |
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
});
pickAddress
Abre uma tela que permite selecionar um endereço e retorna os dados do endereço selecionado.
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.0.0 | pickAddress adicionado ao runtime |
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'
} */
});
askLocation
Obtém dados da localização atual do usuário, é necessário que o usuário conceda o acesso à localização do dispositivo.
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.0.0 | askLocation adicionado ao runtime |
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
}
} */
});
manageUserBankingData
⚠ Necessita privilégio de acesso a dados bancários habilitado no Portal do Desenvolvedor
Abre uma tela que permite criar ou alterar dados de conta bancária e os devolve como retorno em caso de sucesso.
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.15.0 | manageUserBankingData adicionado ao runtime |
Ame.manageUserBankingData().then(data => {
console.log(data)
/* Exemplo de saída desse console.log:
{
"account": "123456",
"type": "CORRENTE", // ou "POUPANCA"
"id": "a130b75e-dcee-45f9-a7a4-a0e364eae8e9",
"bank": "260",
"agency": "0001"
}*/
});
askUserBankingData
⚠ Necessita privilégio de acesso a dados bancários habilitado no Portal do Desenvolvedor
Solicita os dados bancários do usuário.
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.15.0 | askUserBankingData adicionado ao runtime |
Ame.askUserBankingData().then(data => {
console.log(data)
/* Exemplo de saída desse console.log:
{
"account": "123456",
"type": "CORRENTE",
"id": "a130b75e-dcee-45f9-a7a4-a0e364eae8e9",
"bank": "260",
"agency": "0001"
}*/
});
getCheckingAccountData
⚠ Necessita privilégio de acesso a dados bancários habilitado no Portal do Desenvolvedor
Solicita os dados da conta da Ame do usuário
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.31.0 | getCheckingAccountData adicionado ao runtime |
try {
let checkingAccountData = await Ame.getCheckingAccountData()
console.log(checkingAccountData)
/**
* Exemplo de saída desse console.log:
* {
* accountDigit: "3",
* accountNumber: "28992958",
* agencyNumber: "0001"
* }
*/
} catch(e) {
if (e === "permission.denied") {
// Seu miniapp não tem permissão para acessar os dados da conta Ame do usuário
}
}
pickContact
Abre a interface nativa do dispositivo móvel do usuário para selecionar um contato
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.33.0 | pickContact adicionado ao runtime |
try {
let contact = await Ame.pickContact()
/**
* // Lógica utilizando o contato aqui
* // Exemplo de retorno no caso de sucesso:
* {
* "name": "Saul Goodman",
* "emailArray": [
* "primeiroemail@uol.com.br",
* "segundoemail@hotmail.com"
* ],
* "phoneArray": [
* "03121987654321",
* "+5521912345678",
* "22940797"
* ]
* }
*/
} catch (e) {
console.log("erro ao buscar contato", e)
}
Caso o super-app não tenha permissão para ler os contatos, uma janela do sistema será disparada automaticamente pedindo a permissão. É possível, também, verificar previamente se o super-app tem a permissão para ler os contatos utilizando o método isGrantedPermission
Notas:
Os números de telefone que voltam desse método podem estar em formatos "não esperados" para o desenvolvedor, conforme ilustrado no exemplo acima. É imperativo tratar esses números para o funcionamento correto do seu miniapp. Algumas possibilidades para se atentar ao tratar esses números são:
Ele pode ter o código da operadora de telefone com a qual será feita a ligação, como no primeiro exemplo de telefone (onde 031
indica que a ligação está sendo feita pela operadora Oi, 21
é o código do estado do RJ e 987654321
é o número do telefone em si).
Ele pode possuir o código de ligação internacional do país, como no segundo exemplo (onde +55
indica que o telefone é do Brasil, 21
é o código do estado do RJ e 912345678
é o número do telefone em si).
Ele pode possuir ou não o código do estado do telefone. No terceiro exemplo, o número não possui o código de estado, em contraste com o primeiro e segundo exemplos, onde o código de estado está presente.
Outros casos possíveis são números começando com 0800
, números de apenas 5 digitos (como número de contato com operadoras de telefonia), ou simplesmente números incorretos e que não façam sentido (apenas um ou dois dígitos, etc.), dentre diversos outros.
Como esses números são input de usuário com uma validação muito fraca, é importante tratar esses números no seu miniapp, para garantir que eles conformem com o desejável para o seu business, verificando, adicionando, e removendo partes do número, conforme necessário.
O mesmo vale para os emails, onde eles podem não ter formato válido de email ou o email pode simplesmente não existir.
Métodos de navegação
Os métodos listados abaixo estão relacionados à navegação entre as diferentes "views" do miniapp
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.4.0 | backToTop adicionado ao runtime |
1.0.0 | navigation adicionado ao runtime |
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});
Acesso ao state
Os dados enviados da seguinte forma:
Ame.navigation.navigate({path: "/Destino", state: {productSKU: "9999999A"}});
Podem ser obtidos na View de destino da seguinte forma
this.props.location.state.productSKU
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.back
quando a pilha de navegação está vazia, o miniapp será fechadoAo chamar
Ame.navigation.back(n)
quando a pilha de navegação tem menos den
pá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.backToTop
caso seja esse o efeito desejado.
navigation.backToTop
Volta para o topo da pilha de navegação.
Ame.navigation.backToTop()
navigation.closeMiniApp
Fecha o miniapp corrente e retorna para a tela anterior
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.0.0 | closeMiniApp adicionado ao runtime |
1.33.0 | closeMiniApp depreciado em favor de Ame.navigation.closeMiniApp |
Ame.navigation.closeMiniApp();
navigation.closeAllAndGoHome
Fecha todas as telas e volta para a Home do App
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.33.0 | closeAllAndGoHome adicionado ao runtime |
Ame.navigation.closeAllAndGoHome();
Storage
Métodos de acesso de leitura e escrita em storage para uso nos mini-apps
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.11.0 | Storage adicionado ao runtime |
storage.setItem
Insere um item no storage
await Ame.storage.setItem("chave", "valor");
storage.getItem
Recupera um item do storage
let valoreRecuperado = await Ame.storage.getItem("chave"); // método sync
storage.removeItem
Remove um item do storage
await Ame.storage.removeItem("chave");
storage.clear
Remove todos os itens que o mini-app escreveu no storage
await Ame.storage.clear();
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.
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.9.0 | startPayment adicionado ao runtime |
1.24.0 | promise aguarda a conclusão do pagamento do cliente e retorna dados da transação |
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
let startPaymentRes = await Ame.startPayment(paymentOrder)
console.debug("startPaymentRes", startPaymentRes);
/*
{
"transaction": {
"id": "6a2fad69-b882-487b-ab8b-55f06f505815",
"qrCodeLink": "https://api.amedigital.com/api/qrcode?qrcode=eyJ0eXBlIjoiUEFZTUVOVCIsIm9yZGVyX2lkIjoiNmEyZmFkNjktYjg4Mi00ODdiLWFiOGItNTVmMDZmNTA1ODE1In0=",
"deepLink": "amedigital://payment?qrcode=eyJ0eXBlIjoiUEFZTUVOVCIsIm9yZGVyX2lkIjoiNmEyZmFkNjktYjg4Mi00ODdiLWFiOGItNTVmMDZmNTA1ODE1In0=",
},
"result": {
"message": "user.back.pressed",
"success": false
}
}
*/
webhook de pagamento
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
}
Para criação de telas especiais, exibindo a detalhes de um pagamento realizado, consulte exibição de detalhes do pedido
startBilletPayment
Abre a tela de pagamento de boleto do super-app
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.26.0 | startBilletPayment adicionado ao runtime |
// Aceita numero do boleto com ou sem máscara
let resBilletPayment= await Ame.startBilletPayment({billetNumber: "34191.79001 01043.510047 91020.150008 6 85000001530" })
console.log(resBilletPayment)
/*
{
"result": {
"transactionId": "af6ec697-bb21-46f0-8fe0-8b452630ebdf",
"success": true
},
"transaction": {
"amountInCents": 2550,
"dueDate": "2021-06-29",
"id": "987b2d93-ac7e-4bba-b735-c58eb2eb4cdc"
}
}
*/
result.success
indica se a ordem de pagamento da Ame foi realizada com sucesso. result.message
indica mensagem de erro, caso result.success
seja false
. transaction
carrega dados referentes à transação
###Transfer Abre a tela de transferências no super-app
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.34.0 | transfer adicionado ao runtime |
- Parâmetros suportados
Parâmetro | Descrição |
---|---|
origin | (Opcional) String que indica de onde o saldo será consumido na transferência. Valores aceitos: creditCard , cashBack , balance |
amountInCents | (Opcional) Int que indica o valor em centavos a ser transferido |
destination | (Opcional) String que indica o CPF, CNPJ ou número de telefone da conta que receberá a transferência |
const result = await Ame.transfer({
origin: "creditCard",
amountInCents: 1000,
destination: "123123123123"
});
console.log("transfer result: ", result);
// Falha:
// {
// "errorMessage": "Ame.transfer.back.pressed",
// "success": false
// }
// Sucesso:
// {
// "transactionDetails": {
// "amount": 1000,
// "transactionId": "9f3abb87-dfa4-528b-a3bc-aaaaad843ab8"
// },
// "success": true
// }
É possível omitir todos os parâmetros:
const result = await Ame.transfer();
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
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.0.0 | Métodos de alerta adicionados ao runtime |
1.19.0 | Suporte a bbcode básico adicionado ao campos 'description' dos método Ame.alert e Ame.confirm |
1.25.0 | Suporte aos atributos 'dismissible' e 'docked' nos métodos Ame.alert e Ame.confirm |
- Parâmetros suportados
Parâmetro | Descrição |
---|---|
title | Título da modal |
description | Texto da janela |
buttonText | Texto do botão principal |
cancelText | Texto do botão de cancelar |
dismissible | Booleano que indica se a janela tem um X no canto superior direito para fechá-la (opcional, false por padrão) |
docked | Booleano que indica se a janela está ancorada no canto inferior da tela (opcional, false por padrão) |
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",
dismissible: true
})
.then(() => { /* Código a ser executado ao apertar no botão principal */ })
.catch(() => { /* Código a ser executado ao apertar no X. Faz sentido apenas quando o alert é chamado com dismissible === true */ })
O campo description
desse objeto aceita bbcode básico
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",
docked: true
})
.then(() => { /* Código a ser executado ao confirmar */ })
.catch(() => { /* Código a ser executado ao cancelar (ou apertar no X no caso de dismissible === true) */ })
O campo description
desse objeto aceita bbcode básico
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.
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.4.0 | showToast adicionado ao runtime |
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
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.4.0 | vibrateDevice adicionado ao runtime |
Ame.vibrateDevice({
duration: 400 //valor default
})
IO em interfaces
Métodos relacionados a entrada e saída de dados do usuário
getClipboard
Obtém os dados de texto do clipboard do device
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.4.0 | getClipboard adicionado ao runtime |
Ame.getClipboard();
setClipboard
Escreve dados de texto do clipboard do device
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.4.0 | setClipboard adicionado ao runtime |
Ame.setClipboard("novo conteúdo do clipboard");
dismissKeyboard
Fecha o teclado
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.15.0 | dismissKeyboard adicionado ao runtime |
Ame.dismissKeyboard();
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
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.4.0 | pickImage adicionado ao runtime |
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")
})
pickDocument
Abre uma tela de captura de imagem com a câmera do telefone, usando uma máscara dedicada à coleta de documentos.
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.18.0 | pickDocument adicionado ao runtime |
1.19.0 | suporte a cameraType,subtitle e quality adicionados |
1.20.0 | suporte a fluxo de review |
1.25.0 | suporte a escolha de imagens da galeria |
- Parâmetros suportados
Parâmetro | Descrição |
---|---|
screenConfig.title | texto que será utilizado no topo da tela de captura de documento (não obrigatório). Default: "Tire uma foto do seu documento" |
screenConfig.subtitle | texto secundário que será utilizado no topo da tela de captura de documento (não obrigatório). Default: null |
screenConfig.cameraType | Tipo de câmera que será aberta ao iniciar a captura ("front","back") (não obrigatório). Default: "back" |
quality | Qualidade da imagem obtida vs compressão. Valores entre 0 e 1. Significando 1 nenhuma compressão ou máxima qualidade. (não obrigatório). Default: 0.8 |
review | Ativa o fluxo de review de uma imagem (não obrigatório). Default: false |
imageWidth | Define um tamanho alvo de saída para a largura e redimensiona a altura proporcionalmente (não obrigatório). Default: 1280. Max:1280 |
useStorage | Boolean - Caso true apresenta as opções de câmera ou galeria. Caso false abre a câmera diretamente. Não obrigatório. Default: false |
modalTitle | Título que será exibido na janela de escolha entre câmera e galeria. Caso seja omitido, screenConfig.title será usado. Não obrigatório. Default: "" |
Ame.pickDocument({
quality: 0.8,
screenConfig: {title: "Foto do RG ou CNH"}
}).then(imgData => {
//imgData é um objeto com informações relativas a imagem capturada
//imgData.imageBase64 é a representação em base64 da imagem capturada
console.log("Imagem capturada de tamanho", imgData.imageBase64.length)
//Pode ser realizado um preview no miniapp utilizando o componente Image.
// JS : this.setState({documentScannedBase64: imgData.imageBase64})
// JSX : <Image source={'data:image/png;base64, '+ this.state.documentScannedBase64} />
})
.catch((e) => {
console.log("Processo de seleção de imagem cancelado pelo usuário", e)
})
Notas:
- Ao chamar o
Ame.pickDocument()
não utilizar oconsole.log
no retorno do método, pois isso ocasionará uma grande saída de dados no log do miniapp, o que pode causar lentidão em alguns terminais.
openFileSelector
Apresenta opções para o usuário escolher um arquivo da galeria ou do armazenamento. Este método retorna informações básicas do arquivo para que sejam utilizadas no método uploadFile.
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.36.0 | openFileSelector adicionado ao runtime |
//showLoading()
Ame.openFileSelector().then(file => {
console.log("aquivo selecionado: ", file);
/*
{
"id": "upload_file_1631631286566",
"sizeInBytes": 7409
}
*/
Ame.uploadFile({ url: "https://minha.url/upload", fileId: file.id })
.then()
.catch();
}).catch(error => {
console.log("erro ao selecionar aquivo: ", error);
});
//hideLoading()
uploadFile
Faz o upload do arquivo previamente selecionado via openFileSelector para a url informada
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.36.0 | uploadFile adicionado ao runtime |
- Parâmetros suportados
Parâmetro | Descrição |
---|---|
url | url que receberá o 'POST' de upload |
fileId | id do arquivo selecionado |
fileAttribute | atributo que chegará no servidor contendo o arquivo. (opcional, "file" por padrão) |
Notas:
- O upload será feito via método 'POST' do tipo "multipart/form-data" contendo os dados "name", "filename" e "content-type". O arquivo será enviado no atributo especificado por parâmetro ou, caso não seja especificado, no atributo "file".
Device Actions
Métodos de interação com outros apps ou experiências do device.
makePhoneCall
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.1.0 | makePhoneCall adicionado ao runtime |
Ame.makePhoneCall("21999999999");
openBrowser
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.19.0 | suporte a propriedade openInApp |
1.1.0 | openBrowser adicionado ao runtime |
- Parâmetros suportados
Parâmetro | Descrição |
---|---|
url | url que será aberta |
openInApp | Booleano que indica se o browser será aberto dentro do app ou externamente |
Ame.openBrowser({
url: "https://google.com",
openInApp: true // optional - default false
});
openUrlScheme
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.16.0 | suporte a propriedade closeCurrentMiniApp |
1.6.0 | openUrlScheme adicionado ao runtime |
Ame.openUrlScheme({
url: "tg://resolve?domain=translate_bot",
closeCurrentMiniApp: false // opcional, padrão false. Fecha o miniapp corrente durante a abertura do deeplink
});
openBarcodeScanner
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.0.0 | openBarcodeScanner adicionado ao runtime |
1.29.0 | boletoNumber adicionado ao retorno do método |
Ame.openBarcodeScanner()
.then(barcodeData => {
/*
{
data: "4123412341234",
type: "ean13",
boletoNumber: "08880..." //este valor é retornado caso o código de barras seja identificado como boleto
}
*/
})
.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));
openQrCodeScanner
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.21.0 | openQrCodeScanner adicionado ao runtime |
Ame.openQrCodeScanner()
.then(result => {
//{data: "https://miniapps.amedigital.com", type: "org.iso.QRCode"}
})
.catch(e => console.log("erro ao executar a leitura do QRCode", e));
startPayButtonScanner
Abre a tela scanner do super-app(botão "Pagar" da tela principal do App)
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.35.0 | startPayButtonScanner adicionado ao runtime |
Ame.startPayButtonScanner();
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
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.9.0 | suporte a parâmetros |
1.3.0 | shareMiniApp adicionado ao runtime |
Ame.shareMiniApp({
"param1": "value1",
"param2": "value2"
});
Os parâmetros passados aqui podem ser obtidos utilizando o método getInitializationInfos
share
Realiza o compartilhamento de informações utilizando a interface de share nativa dos sistemas operacionais móveis.
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.27.0 | share adicionado ao runtime |
- Parâmetros suportados
Parâmetro | Descrição |
---|---|
title | (não obrigatório) título da janela de compartilhamento. |
message | (obrigatório caso não use file) mensagem que será compartilhada com outros apps |
file | (não obrigatório) objeto contendo duas propriedades obrigatórias (mimeType, base64String) |
- *base64String - máximo de 600000 caracteres.
Ame.share({
"title": "Cinema", "message": "Venha curtir comigo o filme: https://yourvaliddomain.com/movie/1982"
});
Ame.share({
"file": {
"mimeType": "image/gif",
"base64String":
"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",
}
});
openMiniApp
Método que permite abrir outro mini app passando parâmetros.
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.32.0 | suporte a objetos complexos nos parâmetros initializationParams e contextParams |
1.32.0 | parâmetros resetStack e replace adicionados |
1.12.0 | suporte a contextParams |
1.9.0 | openMiniApp adicionado na versão 1.9.0 do runtime |
- Parâmetros suportados
Parâmetro | Descrição |
---|---|
slug | identificador do mini-app que será aberto |
initializationParams | objeto* passado para o mini-app destino que poderá ser acessado via getInitializationInfos no mini-app de destino |
contextParams | objeto* que será devolvido quando voltar ao mini-app corrente. Poderá ser acessado via getInitializationInfos quando o mini-app atual voltar a ser o corrente, ou seja, o topo da pilha |
resetStack | Boolean indica que a pilha de mini-apps será resetada durante a abertura do mini-app destino(opcional, false por padrão) |
replace | Boolean indica que o mini-app atual será substituído pelo mini-app destino na pilha de mini-apps(opcional, false por padrão) |
- O tamanho máximo é 2Mb.
Ame.openMiniApp({
slug: "meu-mini-app",
initializationParams:{
"param1": "value1",
"param2":{
"a": 1,
"b": 2,
},
"param3": 1234,
"param4": true,
},
contextParams:{
"currentParam1":"currentValue1",
"currentParam2": {
"c": 3,
"d": 4,
},
"currentParam2": 4321,
"currentParam2": false,
}
})
openSystemSettings
Método para abrir settings do sistema, já com o app da Ame selecionado
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.20.0 | openSystemSettings adicionado ao runtime |
Ame.openSystemSettings()
Geocoding Utils
Método auxiliares para conversão de dados de localização do usuário
getGeolocationFromAddress
Geocoding. Obtém dados de latitude e longitude à partir de uma query de endereço
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.9.0 | getGeolocationFromAddress adicionado ao runtime |
1.25.0 | name adicionado ao retorno com o nome do POI. se houver |
Ame.getGeolocationFromAddress({addressQuery: "praia de botafogo 501, botafogo, RJ"}).then(geolocResults => {
console.log(geolocResults)
/* Exemplo de saída desse console.log:
[
{
"address": "Praia de Botafogo",
"city": "Rio de Janeiro",
"country": "Brazil",
"longitude": -43.1806511,
"latitude": -22.9505129,
"neighborhood": "Botafogo",
"zip": "22250-040",
"state": "RJ",
"name": "Centro Empresarial Mourisco"
}
]
*/
});
getAddressFromLocation
Reverse Geocoding. Obtém dados de endereço à partir de dados de latitude e longitude
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.0.0 | getAddressFromLocation adicionado ao runtime |
Ame.getAddressFromLocation(-22.9505129, -43.1806511).then(addressResult => {
console.log(addressResult)
/* Exemplo de saída desse console.log:
{
"address": "Praia de Botafogo",
"city": "Rio de Janeiro",
"country": "Brazil",
"latitude": -22.9505129,
"longitude": -43.1806511,
"neighborhood": "Botafogo",
"state": "RJ",
"zip": "22250-040"
}
*/
});
getAddressByZipCode
Retorna dados de endereço para um determinado CEP. Pode voltar estado, cidade, bairro, e logradouro, ou apenas alguns desses dados, dependendo do CEP.
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.23.0 | getAddressByZipCode adicionado ao runtime |
Ame.getAddressByZipCode({zipCode: "01001000"})
.then( addressData => {
console.log(addressData)
/* Exemplo de saída desse console.log:
{
state: "SP",
city: "São Paulo",
district: "Sé",
address: "Praça da Sé"
}
*/
})
Esse método também aceita CEPs formatados, como por exemplo 01001-000
ao invés de 01001000
. Todos os outros formatos de entrada de dados de CEP serão rejeitados.
Métodos de interação com os componentes
Métodos para interagir diretamente com os componentes da plataforma. Todos os métodos dessa sessão podem ser usados apenas com componentes que aceitem id (dependendo da versão da biblioteca de componentes)
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.0.0 | namespace component adicionado ao runtime |
1.0.0 | setFocus adicionado ao runtime |
1.0.0 | blur component adicionado ao runtime |
1.0.0 | scrollTo component adicionado ao runtime |
setFocus
Foca o componente com o id passado como parâmetro.
Home.jsx
<Input id={"meu_input"} type={"text"} />
Home.js
Ame.component.setFocus({componentId: "meu_input"})
blur
Desfoca o componente com o id passado como parâmetro. É essencialmente o inverso do setFocus
Home.jsx
<Input id={"meu_input"} type={"text"} />
Home.js
Ame.component.blur({componentId: "meu_input"})
scrollTo
Move o scroll até o componente com o id passado como parâmetro.
Home.jsx
<Input id={"meu_input"} type={"text"} />
Home.js
Ame.component.scrollTo({componentId: "meu_input"})
Validadores
isStateCode
Valida se uma string é um código de estado válido ("RJ", "SP", etc.)
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.0.0 | isStateCode adicionado ao runtime |
let isValid1 = Ame.validation.isStateCode("RJ")
console.log(isValid1)
// Saída: true
let isValid2 = Ame.validation.isStateCode("NO")
console.log(isValid2)
// Saída: false
Permissionamento
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.0.0 | namespace permission adicionado ao runtime |
isGrantedPermission
Verifica se a permissão passada por parâmetro foi concedida.
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.17.0 | isGrantedPermission adicionado ao runtime |
let isGranted = await Ame.permission.isGrantedPermission("camera"); // returns true || false
Permissões disponíveis para consulta:
- location
- camera
- read_contacts
checkNotificationPermission
Verifica se a permissão de envio de push notification está habilitada no aparelho.
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.31.0 | checkNotificationPermission adicionado ao runtime |
let notificationPermission = await Ame.permission.checkNotificationPermission()
if (notificationPermission.hasNotificationPermission) {
// aparelho ja tem permissao de push
} else {
// aparelho nao tem permissao de push
}
askNotificationPermission
⚠ Essa permissão não dá acesso ao desenvolvedor de miniapps para enviar notificações. Não há mecanismo no SDK para enviar as notificações, apenas verificar e pedir as permissões do aparelho. O envio das notificações é considerado fora do escopo desse SDK no momento.
Pede a permissão de envio de push notification para o usuário
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.31.0 | askNotificationPermission adicionado ao runtime |
let notificationPermission = await Ame.permission.checkNotificationPermission()
if (!notificationPermission.hasNotificationPermission) {
// Dispositivo nao tem permissao de notificacao
try {
await Ame.confirm({
title: "Que tal ativar suas notificações?",
description: "Percebemos que você está com as notificações do app desligadas. Para acompanhar o status do seu cartão físico, seria bacana ativar, o que acha?",
confirmText: "Ativar notificações",
cancelText: "Agora não",
})
await Ame.permission.askNotificationPermission()
} catch (e) {
if (e === "could.not.ask.for.notification.permission") {
// leva o usuário para as configurações de sistema para ativar as notificações
await Ame.openSystemSettings()
} else if (e === "notification.permission.denied") {
// Permissao pedida com sucesso, mas negada pelo usuario")
} else {
// Usuario negou a janela de confirmacao
}
}
}
Validação do cliente
check
⚠ Esse método requer análise prévia de risco por parte da equipe da Ame, entre em contato para análise.
Verifica estado atual de validação do cliente, baseado no slug do miniapp. Este método verifica a necessidade de coleta de dados para validação permitindo que, caso necessário, seja possível implementar um aviso para o cliente antes de começar o processo de coleta.
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.33.0 | customerValidation.check adicionado ao runtime |
try {
let res = await Ame.customerValidation.check()
/**
* Exemplo de retorno desse método:
* {
* approved: true
* }
*/
} catch(e) {
if (e === "checkValidationStatus.unknown.error") {
console.log("Erro ao verificar o estado de validação do cliente")
}
}
start
⚠ Esse método requer análise prévia de risco por parte da equipe da Ame, entre em contato para análise.
Começa o processo de validação do cliente, baseado no slug do miniapp. Esse processo coletará todos os documentos necessários do cliente de forma automatizada. O mini-app receberá o controle novamente quando o fluxo de coleta de documentos tiver sido concluído.
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.33.0 | customerValidation.start adicionado ao runtime |
try {
let res = await Ame.customerValidation.start()
/**
* Exemplo de retorno desse método:
* {
* approved: true
* }
*/
} catch(e) {
if (e === "customerIdentityValidation.start.in.progress") {
// Processo de validação já está acontecendo. Esse erro pode ser evitado ao botar um loading no elemento que dispara o método enquanto o ele não termina de executar
// Alternativamente, esse erro pode ser silenciado
console.log("Processo de validação tentou ser disparado duas vezes concorrentemente")
} else {
console.log("Erro ao validar usuário:", e) // "customerValidation.start.error"
}
}
Demais métodos
getEnvironment
Retorna em que ambiente o aplicativo Ame está sendo executado.
Possíveis retornos:
- prod
- qa
- dev
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.0.0 | getEnvironment adicionado ao runtime |
Ame.getEnvironment()
.then(env => console.log(`Ambiente ${env}`)/* dev, qa ou prod */)
.catch(e => console.log("erro ao recuperar o ambiente.", e));
getDeviceSpecs
Retorna dados a respeito do device que está sendo utilizado
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.4.0 | getDeviceSpecs adicionado ao runtime |
Ame.getDeviceSpecs().then(specs => {});
Dados de retorno
Exemplo de um iPhone 12 Pro Max:
specs = {
// se o telefone tem a barra de navegação inferior, como os iPhones a partir da versão X
"hasBottomGestureBar": true,
// ios / android
"platform": "ios",
// versão do sistema operacional
"platformVersion": "14.6",
// marca do dispositivo
"deviceBrand": "Apple",
// Nome da versão do telefone conforme utilizado pela fabricante. Nesse exemplo, o iPhone 12 Pro Max retorna "iPhone13,4".
"deviceId": "iPhone13,4",
"deviceName": "iPhone",
"safeAreas": {
"top": 35,
"bottom": 30
}
}
Exemplo de um Samsung Galaxy S9
specs = {
"hasBottomGestureBar": false,
"platform": "android",
"platformVersion": "10",
"deviceBrand": "samsung",
"deviceId": "sdm845",
"deviceName": "SM-G9600",
"safeAreas": {
"top": 24,
"bottom": 0
}
}
getAppInfo
Retorna os números de versão do app nativo e do runtime do SDK
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.9.0 | getAppInfo adicionado ao runtime |
Ame.getAppInfo().then(info => {});
Dados de retorno
info = {
app_version: "x.x.x",
sdk_runtime_version: "x.x.x"
}
addListener
Registra um callback a ser invocado ao disparar de um evento nativo.
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.15.0 | evento onKeyboardChange adicionado |
1.11.0 | evento onBackPress adicionado |
1.9.0 | addListener adicionado ao runtime |
Tipos de evento disponíveis:
- onAppStateChanged:
Invocado quando o aplicativo é colocado em background ou foreground.
Valores passados no callback: active, background, inactive(iOS)*.
Ame.addListener("onAppStateChanged", (state)=>{
console.log("New app state", state);
})
* inactive(iOS): Este é um estado que ocorre ao fazer a transição entre primeiro e segundo plano e durante períodos de inatividade, como entrar na exibição Multitarefa ou no caso de uma chamada recebida.
- onBackPress:
Invocado ao realizar a ação de back no Android ou tocar no botão back do header do miniapp. Precisa receber uma função que retornatrue
para continuar a execução normal da ação de back oufalse
para prevenir que a ação de back aconteça. Este listener funciona apenas na página onde foi declarado e não necessita ser removido, pois é removido automaticamente ao realizar ações de navegação.
Ame.addListener("onBackPress", this.backPressCallback);
...
backPressCallback(){
Ame.confirm({
title: "Atenção",
description: "Deseja realmente sair?",
confirmText: "Sim",
cancelText: "Não"
})
.then(() => { Ame.navigation.back() }) //faz a ação de back via framework
.catch(() => { /* Código a ser executado ao cancelar */ });
return false; //previne que o back aconteça
}
- onKeyboardChange:
Invocado durante mudanças de estado do teclado, quando ele for exibido ou removido da tela.
Ame.addListener("onKeyboardChange", (evt) => {
console.log("evt", evt);
/* Exemplo de saída desse console.log:
{
"isOpen": true,
"nativeEvent": {...}
}
*/
});
removeListener
Remove um callback registrado anteriormente do evento. O callback a ser removido deve ser passado como parâmetro.
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.9.0 | removeListener adicionado ao runtime |
Ame.removeListener("onAppStateChanged", (state)=>{
console.log("New app state", state);
})
Registra um callback a ser invocado ao disparar de um evento nativo.
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
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.2.0 | getOrderDetails adicionado ao runtime |
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)
})
getBalance
⚠ Necessita privilégio de acesso ao saldo habilitado no Portal do Desenvolvedor
Obtém o saldo do usuário.
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.27.0 | getBalance adicionado ao runtime |
Ame.getBalance()
.then(balance => {
console.log(balance)
/* Exemplo de saída desse console.log:
{
"cashBackBalance": {
"futureCredit": "0",
"futureDebit": "0",
"available": "0"
},
"cashBalance": {
"futureCredit": "0",
"futureDebit": "0",
"available": "2000"
},
"totalBalance": {
"futureCredit": "0",
"futureDebit": "0",
"available": "2000"
} */
}
})
.catch(error => {
console.log("Erro ao obter saldo do usuário:", error)
})
Todos os valores retornados são strings que representam o valor em centavos.
cashBackBalance
é referente ao saldo em cashback do usuário. cashBalance
é referente ao saldo em dinheiro (não-cashback) do usuário. totalBalance
é a soma de cashBackBalance
e cashBalance
.
available
é quanto o usuário possui disponível no momento. futureCredit
é quanto está previsto entrar na conta do usuário. futureDebit
é quanto está previsto sair da conta do usuário.
Google Analytics
Disponibilizamos suporte ao Google Analytics e Google Analytics 4, basta ter em mãos o seu trakingID
Google Analytics (Legacy)
Disponibilizamos uma instância do Google Analytics para que seja possível utilizar os eventos de rastreio do Google, basta possuir o trackingId no formato legacy (UA-XXXX-X).
Ame.GA.getInstance(TRACKING_ID)
Este método recebe o trackingId(obrigatório) como parâmetro e retorna a instância do Google Analytics. Com a instância do rastreador em mãos é possível utiliza-la para enviar os eventos ao Analytics
let ga = null;
try {
ga = await Ame.GA.getInstance("UA-123123-3")
} catch (e) {
// error
}
if(ga){
ga("send", {
hitType: "event",
eventCategory: "myEventCategory",
eventAction: "myEventAction",
eventLabel: "myEventLabel"
})
}
Google Analytics 4
Disponibilizamos uma instância do Google Analytics 4 para que seja possível utilizar os eventos de rastreio do Google, basta possuir o trackingId v4 (U-XXXXXX ou G-XXXXXXX).
Ame.GA4.getInstance(TRACKING_ID)
Este método assíncrono recebe o trackingId(obrigatório) como parâmetro e retorna a instância do Google Analytics. Com a instância do rastreador em mãos é possível utiliza-la para enviar os eventos ao Analytics
let gtag = null;
try{
gtag = await Ame.GA4.getInstance("G-Q1W2E3")
} catch (e) {
// error
}
if(gtag){
gtag("event", "exception", {
description: "Exception description",
fatal: false
})
gtag("event", "myEventAction", {
event_category: "myEventCategory",
event_label: "myEventLabel"
})
}
sendGoogleAnalytics
Deprecado. Utilize a implementação do Google Analytics.
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: Esse parâmetro tem como objetivo identificar determinado usuário, dispositivo ou instância de navegador de modo anônimo
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.0.0 | sendGoogleAnalytics adicionado ao runtime |
const eventData = {
version: '1',
hitType: 'pageview',
trackingId: 'UA-XXXX-Y',
documentLocation: '/NameView',
clientId: '35009a79-1a05-49d7-b876-2b884d0f825b'
}
Ame.sendGoogleAnalytics(eventData)
getInitializationInfos
Método para recuperar os parâmetros recebidos pelo mini app durante a inicialização.
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.9.0 | getInitializationInfos adicionado ao runtime |
As opções de passagem de parâmetros durante a abertura de um mini app são:
deeplink
https://miniapps.amedigital.com/open/mini-app-slug? param1=value1¶m2=value2
Exemplo de uso:
Ame.getInitializationInfos().then(infos => {
console.log("infos: ", infos);
}
);
As informações de retorno estão dentro do atributo data do objeto de retorno.
infos: [
{
"type": "NAVIGATION", // or "SHARE"
"data": {
"param1": "value1",
"param2": "value2"
}
}
]
Para fins de desenvolvimento é possivel passar parâmetros na inicialização do mini app utilizando a CLI ame-app-tools
defineSceneType
Método para chavear entre os diferentes tipos de cenas disponíveis no miniapp.
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.23.0 | defineSceneType adicionado ao runtime |
1.29.0 | buttonsColorScheme ROUNDED_LIGHT e ROUNDED_DARK adicionados ao runtime |
Exemplo de uso:
let options = {
sceneType: "TRANSPARENT",
buttonsColorScheme: "AME",
}
Ame.defineSceneType(options)
O atributo sceneType
é uma string com os possíveis valores de: DEFAULT
ou TRANSPARENT
.
DEFAULT: Header degradê padrão do app da Ame
TRANSPARENT: Sem Header, mas com botões de voltar e fechar presentes
O atributo buttonsColorScheme
é uma string com os possíveis valores de: LIGHT
, DARK
, ROUNDED_LIGHT
, ROUNDED_DARK
ou AME
. Esse atributo só é utilizado para o sceneType TRANSPARENT
, e é ignorado se passado para qualquer outro sceneType
LIGHT: Botões de controle brancos
DARK: Botões de controle pretos
ROUNDED_LIGHT: Botões redondos escuros para temas claros
ROUNDED_DARK: Botões redondos claros para temas escuros
AME: Botões de controle rosa
checkRuntimeSupportFor
Método para comparar a versão do ambiente de runtime do SDK com uma versão
Histórico de alterações
runtime SDK | Alterações |
---|---|
1.0.0 | checkRuntimeSupportFor adicionado ao runtime |
Exemplo de uso:
let version = "1.11.0"
if (await Ame.checkRuntimeSupportFor(version)) {
// Chamada a alguma funcionalidade do SDK adicionada na versão passada:
return await Ame.storage.setItem("chave", "valor")
}
);
BBCode básico
Essa sessão se refere aos métodos com suporte a tags BBCode básicas.
As seguintes tags são suportadas:
let BBText1 = "[b] Texto em negrito [/b]"
let BBText2 = "[u] Texto sublinhado [/u]"
let BBText3 = "[i] Texto em itálico [/i]"
let BBText4 = "[color=red] Texto vermelho [/color]"
let BBText5 = "[color=#53B4A5] Texto com cor hexadecimal [/color]"
As tags também podem ser aninhadas umas dentro das outras:
let nestedBBText1 = "Texto não formatado. [b] Essa parte do texto está em negrito. [color=blue] Essa parte do texto está azul E negrito [/color] E essa apenas em negrito [/b] E essa aqui não formatada"
Notas
Há uma limitação onde não podem ser abertas tags de um determinado tipo dentro de tags do mesmo tipo.
Todos os exemplos abaixo não serão exibidos:
// Todos os exemplos abaixo estão quebrados e não vão funcionar
let brokenBBText1 = "[b] Negrito [b]mais negrito?[/b][/b]" // [b] dentro de [b]
let brokenBBText2 = "[color=red] Vermelho, [color=blue] azul? [/color] [/color]" // [color=...] dentro de [color=...]
let brokenBBText3 = "[b] Negrito [i] itálico e negrito [b] negrito e itálico e negrito? [/b] [/i] [/b]" // [b] dentro de [b], com um [i] no meio
Texto com tags não fechadas corretamente também não será exibido:
// Todos os exemplos abaixo estão quebrados e não vão funcionar
let brokenBBText4 = "[b] Meu texto" // tag [b] não fechada
let brokenBBText5 = "Meu texto [/b]" // Fechamento de tag sem abertura
let brokenBBText6 = "[u] Meu texto quebrado [/i]" // Tag de fechamento [/i] não corresponde com abertura [u]
let brokenBBText7 = "[b] Negrito [i] Negrito e itálico [/b] apenas itálico? [/i]" // Tag [i] não fechada dentro de [b]...[/b]
Exibição de detalhes do pedido
Caso o mini-app queira exibir algo relevante após um pagamento, como um código de resgate, qrCode ou link de acompanhamento do pedido, é possível fornecer um botão "Detalhes do Pedido" após a conclusão da ordem de pagamento.
Esse botão ficará disponível para o cliente final na tela de resumo dos dados de pagamento, e enviará o cliente de volta para o mini-app, em uma tela especial.
É necessário seguir alguns passos para ter suporte à exibição de detalhes do pedido:
Enviar o parâmetro
hasOrderDetails: true
no corpo do objeto em Ame.startPaymentCriar uma view nomeada
OrderDetails
no miniapp, e nela, chamar a funçãoAme.getOrderDetails
para obter oid
do pedido Ame.
Para facilitar a conciliação do id do pagamento da Ame com um pedido do lado do mini-app, o mini-app pode registrar os pedidos realizados pelo cliente em seu banco de dados, utilizando o webhook de pagamentos:
Declarar o parâmetro
callbackUrl
no corpo do objeto doAme.startPayment
, indicando um endpoint que receberá notificações dos pagamentos realizados no mini-appOs dados recebidos no endpoint indicado seguem o formato indicado em webhook de pagamento