AME-SUPER-APP-CLIENT · 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 chamar Ame.navigation.back(1)
Ao chamar Ame.navigation.back quando a pilha de navegação está vazia, o miniapp será fechado
Ao chamar Ame.navigation.back(n) quando a pilha de navegação tem menos de n páginas, o Miniapp voltará para a primeira página da pilha. Esse, porém, não é o uso projetado desse método. Considere usar Ame.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 o console.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

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":
            "R0lGODlhPQBEAPeoAJosM//AwO/AwHVYZ/z595kzAP/s7P+goOXMv8+fhw/v739/f+8PD98fH/8mJl+fn/9ZWb8/PzWlwv///6wWGbImAPgTEMImIN9gUFCEm/gDALULDN8PAD6atYdCTX9gUNKlj8wZAKUsAOzZz+UMAOsJAP/Z2ccMDA8PD/95eX5NWvsJCOVNQPtfX/8zM8+QePLl38MGBr8JCP+zs9myn/8GBqwpAP/GxgwJCPny78lzYLgjAJ8vAP9fX/+MjMUcAN8zM/9wcM8ZGcATEL+QePdZWf/29uc/P9cmJu9MTDImIN+/r7+/vz8/P8VNQGNugV8AAF9fX8swMNgTAFlDOICAgPNSUnNWSMQ5MBAQEJE3QPIGAM9AQMqGcG9vb6MhJsEdGM8vLx8fH98AANIWAMuQeL8fABkTEPPQ0OM5OSYdGFl5jo+Pj/+pqcsTE78wMFNGQLYmID4dGPvd3UBAQJmTkP+8vH9QUK+vr8ZWSHpzcJMmILdwcLOGcHRQUHxwcK9PT9DQ0O/v70w5MLypoG8wKOuwsP/g4P/Q0IcwKEswKMl8aJ9fX2xjdOtGRs/Pz+Dg4GImIP8gIH0sKEAwKKmTiKZ8aB/f39Wsl+LFt8dgUE9PT5x5aHBwcP+AgP+WltdgYMyZfyywz78AAAAAAAD///8AAP9mZv///wAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACH5BAEAAKgALAAAAAA9AEQAAAj/AFEJHEiwoMGDCBMqXMiwocAbBww4nEhxoYkUpzJGrMixogkfGUNqlNixJEIDB0SqHGmyJSojM1bKZOmyop0gM3Oe2liTISKMOoPy7GnwY9CjIYcSRYm0aVKSLmE6nfq05QycVLPuhDrxBlCtYJUqNAq2bNWEBj6ZXRuyxZyDRtqwnXvkhACDV+euTeJm1Ki7A73qNWtFiF+/gA95Gly2CJLDhwEHMOUAAuOpLYDEgBxZ4GRTlC1fDnpkM+fOqD6DDj1aZpITp0dtGCDhr+fVuCu3zlg49ijaokTZTo27uG7Gjn2P+hI8+PDPERoUB318bWbfAJ5sUNFcuGRTYUqV/3ogfXp1rWlMc6awJjiAAd2fm4ogXjz56aypOoIde4OE5u/F9x199dlXnnGiHZWEYbGpsAEA3QXYnHwEFliKAgswgJ8LPeiUXGwedCAKABACCN+EA1pYIIYaFlcDhytd51sGAJbo3onOpajiihlO92KHGaUXGwWjUBChjSPiWJuOO/LYIm4v1tXfE6J4gCSJEZ7YgRYUNrkji9P55sF/ogxw5ZkSqIDaZBV6aSGYq/lGZplndkckZ98xoICbTcIJGQAZcNmdmUc210hs35nCyJ58fgmIKX5RQGOZowxaZwYA+JaoKQwswGijBV4C6SiTUmpphMspJx9unX4KaimjDv9aaXOEBteBqmuuxgEHoLX6Kqx+yXqqBANsgCtit4FWQAEkrNbpq7HSOmtwag5w57GrmlJBASEU18ADjUYb3ADTinIttsgSB1oJFfA63bduimuqKB1keqwUhoCSK374wbujvOSu4QG6UvxBRydcpKsav++Ca6G8A6Pr1x2kVMyHwsVxUALDq/krnrhPSOzXG1lUTIoffqGR7Goi2MAxbv6O2kEG56I7CSlRsEFKFVyovDJoIRTg7sugNRDGqCJzJgcKE0ywc0ELm6KBCCJo8DIPFeCWNGcyqNFE06ToAfV0HBRgxsvLThHn1oddQMrXj5DyAQgjEHSAJMWZwS3HPxT/QMbabI/iBCliMLEJKX2EEkomBAUCxRi42VDADxyTYDVogV+wSChqmKxEKCDAYFDFj4OmwbY7bDGdBhtrnTQYOigeChUmc1K3QTnAUfEgGFgAWt88hKA6aCRIXhxnQ1yg3BCayK44EWdkUQcBByEQChFXfCB776aQsG0BIlQgQgE8qO26X1h8cEUep8ngRBnOy74E9QgRgEAC8SvOfQkh7FDBDmS43PmGoIiKUUEGkMEC/PJHgxw0xH74yx/3XnaYRJgMB8obxQW6kL9QYEJ0FIFgByfIL7/IQAlvQwEpnAC7DtLNJCKUoO/w45c44GwCXiAFB/OXAATQryUxdN4LfFiwgjCNYg+kYMIEFkCKDs6PKAIJouyGWMS1FSKJOMRB/BoIxYJIUXFUxNwoIkEKPAgCBZSQHQ1A2EWDfDEUVLyADj5AChSIQW6gu10bE/JG2VnCZGfo4R4d0sdQoBAHhPjhIB94v/wRoRKQWGRHgrhGSQJxCS+0pCZbEhAAOw==",
    }
});

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 retorna true para continuar a execução normal da ação de back ou false 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&param2=value2
openMiniApp
shareMiniApp

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.startPayment
Criar uma view nomeada OrderDetails no miniapp, e nela, chamar a função Ame.getOrderDetails para obter o id 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 do Ame.startPayment, indicando um endpoint que receberá notificações dos pagamentos realizados no mini-app
Os dados recebidos no endpoint indicado seguem o formato indicado em webhook de pagamento