1.1.2

API de interação com o Super-APP AME

Toolset de interação com a camada de Super App

Para instalar no mini-app (enquanto estamos sem publicar com um nome definitivo):

npm i ame-super-app-client -s

Para atualizar no mini-app:

npm up ame-super-app-client

Caso o a api não seja atualizada pelas as vias normais...

rm -rf ./node_modules/ame-super-app-client
npm install

Para utilizar no mini-app é necessário importar a API:

import Ame from "ame-super-app-client";

Métodos da API

Operações HTTP

Existem métodos para realizar requisições HTTP.

Método GET

import Ame from "ame-super-app-client";
Ame.get(url, [config]);

Método POST

import Ame from "ame-super-app-client";
Ame.post(url, [config]);

Método PUT

import Ame from "ame-super-app-client";
Ame.put(url, [config]);

Método DELETE

import Ame from "ame-super-app-client";
Ame.delete(url, [config]);

Métodos para obtenção de informações do usuário

Método askUserData

Permite requisitar os dados do usuário. Caso o usuário aceite, a função retorna um objeto com os dados do usuário. Caso o usuário não aceite, a função lança uma excessão.

import Ame from "ame-super-app-client";

Ame.askUserData()
    .then(user => {
        // usuario deu permissao para ler os dados
        console.log(user);
        /* Exemplo de saída desse console.log:
        {
            "phone": "21994291123",
            "documentType": "CPF",
            "documentNumber": "55410786360",
            "email": "johndoe@domain.com",
            "name": "John Doe",
            "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
        } */
    })
    .catch(err => {
        // usuario negou acesso aos dados
    });

Método askDefaultAddress

Permite requisitar o endereço padrão cadastrado no super-app. Caso o usuário aceite, a função retorna um objeto com os dados do endereço. Caso o usuário não aceite, a função lança uma excessão.

import Ame from "ame-super-app-client";

Ame.askDefaultAddress()
    .then(address => {
        // usuario deu permissao para ler os dados (nome, cpf, email, etc.)
        console.log(address);
        /* Exemplo de saída desse console.log:
        {
            "address": "Rua São Clemente",
            "number": "258",
            "district": "Botafogo",
            "state": "RJ",
            "city": "Rio de Janeiro",
            "zipCode": "22260-004",
            "countryCode": "BRA",
            "additionalInfo": "4º andar"
        } */
    })
    .catch(err => {
        // usuario negou acesso aos dados
    });

Método askLocation

Obtém dados da localização atual do usuário, é necessário que o usuário conceda o acesso à localização do dispositivo.

import Ame from "ame-super-app-client";

Ame.askLocation().then(location => {
    console.log(location)
    /* Exemplo de saída desse console.log:
    {
        mocked: false,
        timestamp: 1567520589000,
        coords: {
            speed: 0,
            heading: 0,
            accuracy: 20,
            altitude: 5,
            longitude: -122.08400000000002,
            latitude: 37.421998333333335
        }
    } */
});

Métodos de navegação

Os métodos listados abaixo estão relacionados à navegação entre as diferentes "views" do app

Método navigate

Permite navegar entre as diferentes "views" do miniapp, conforme definidas no diretório src/views, passando-se parâmetros quaisquer entre elas. Então, no caso de uma estrutura de arquivos do miniapp que possui as views Index e Confirm (ou seja, os arquivos Index.js , Index.jsx , Confirm.js e Confirm.jsx) , pode ser usado no arquivo Index.js :

import Ame from "ame-super-app-client";

state = {
    productName: "Celular",
    productColor: "Cinza"
};
Ame.navigate("/Confirm", state);

Método navigateBack

Realiza o retorno da view atual para a anterior na stack de navegação

import Ame from "ame-super-app-client";
Ame.navigateBack()

Método closeMiniApp

import Ame from "ame-super-app-client";
Ame.closeMiniApp().then(() => console.log("Mini-app fechado"));

Métodos de pagamento

Método startPayment

Permite que o usuário inicie o fechamento de um pedido, lançando a tela de pagamentos do super-app.

import Ame from "ame-super-app-client";

let item = { name: "my product", price: 1.99 };

// o valor tem que ser em centavos, ou seja, 1.99 vira 199
let itemPrice = parseInt(item.price * 100, 10);
let paymentOrder = {
    title: "Titulo",
    description: "Descricao",
    walletToken: "999999-99999999-99999999-99999999", //opcional, somente para miniapps multi wallet
    amount: itemPrice,
    cashbackAmountValue: 0,
    customPayload: {
        cartId: "12345" /* Dados customizados para fechar o pedido apos pagamento */
    },
    hasOrderDetails: false // opcional, somente para miniapps com suporte a ver detalhes de pedido. Ler mais na seção "Exibição de detalhes do pedido"
    callbackUrl:
        "https://yourdomain.com/api/checkout" /* URL para a API da Ame enviar os dados de pagamento */,
    items: [
        {
            description: item.name,
            quantity: 1,
            amount: itemPrice
        }
    ]
};

// abre a tela de pagamento da Ame
Ame.startPayment(paymentOrder)

Ao realizar um pagamento, a URL informada em callbackUrl será requisitada passando o corpo abaixo:

{
    "id": "1b8bb06b-b217-460a-9a41-72279a0f8123",
    "date": [2019, 8, 4, 20, 28, 6, 658839000],
    "operationType": "DEBIT",
    "name": "Compra on-line",
    "title": "Titulo",
    "description": "Descricao",
    "status": "AUTHORIZED",
    "type": "PAYMENT",
    "currency": "BRL",
    "cashType": "CARD",
    "amount": 199,
    "amountRefunded": 0,
    "splits": [
        {
            "id": "4b109db8-08eb-4404-9fb0-4bbcfae0a123",
            "date": [2019, 8, 4, 20, 28, 6, 658868000],
            "status": "AUTHORIZED",
            "cashType": "CARD",
            "amount": 199,
            "installments": 1,
            "cardMasked": "409602######6243",
            "cardBrand": "VISA"
        }
    ],
    "attributes": {
        "payOnce": true,
        "transactionChangedCallbackUrl": "https://yourdomain.com/api/checkout",
        "items": [
            {
                "description": "my product",
                "amount": 199,
                "quantity": 1
            }
        ],
        "customPayload": {
            "cartId": "12345"
        },
        "orderId": "3aa8e856-f54b-4caa-aa17-97eb62d25123"
    },
    "operationReference": null,
    "peer": null
}

Métodos de alerta

Métodos para exibir uma janela modal ao usuário, seja para exibir informação para ele, ou para pedir confirmação antes de executar operações importantes

Método alert

Abre uma janela modal que exibe uma informação e permite o usuário clicar em um botão para fecha-lá.

import Ame from "ame-super-app-client";

Ame.alert({title: "Título da modal", description: "Texto da janela", buttonText: "Texto dentro do botão"})

Método confirm

Abre uma janela modal que exibe uma informação e permite o usuário clicar em um botão para confirmar ou em um botão para cancelar a ação.

import Ame from "ame-super-app-client";

Ame.confirm({title: "Título da modal", description: "Texto da janela", buttonText: "Texto dentro do botão"})

Ame.confirm({
          title: "Título da modal",
          description: "texto a ser exibido",
          confirmText: "Texto do botão de confirmar",
          cancelText: "Texto do botão de cancelar"
        })
        .then(() => { /* Código a ser executado ao confirmar */ })
        .catch(() => { /* Código a ser executado ao cancelar */ })

Demais métodos

Métodos que não se encaixam em nenhuma outra categoria

Método pickAddress

Abre uma tela que permite selecionar um endereço e retorna os dados do endereço selecionado.

import Ame from "ame-super-app-client";

Ame.pickAddress().then(address => {
    console.log(address)
    /* Exemplo de saída desse console.log:
    {
        countryCode: 'BRA',
        additionalInfo: '',
        zipCode: '12345-678',
        main: 'true',
        state: 'RJ',
        city: 'Rio de Janeiro',
        district: 'Centro',
        number: '1',
        address: 'Beco Diagonal',
        customerId: '85b6e3c8-85b6e3c8-85b6e3c8-85b6e3c8-85b6e3c8'
    } */
});

Método openBarcodeScanner

import Ame from "ame-super-app-client";
Ame.openBarcodeScanner()
    .then(barcodeData => {
        //{data: "4123412341234", type: "ean13"}
    })
    .catch(e => console.log("erro ao executar a leitura de código de barras", e));

Abrir QR Code trocando textos das telas

import Ame from "ame-super-app-client";

const barCodeOptions = {
    screens: {
        // Tela do leitor de código de barras
        reader: {
            // Texto que fica acima do leitor de código de barras
            text: 'Posicione o leitor em cima do código de barras ou do QR Code',
            // Texto do botão para informar o código de barras
            button: 'Digite código de barras',
        },
        // Tela para informar o código
        input: {
            // Título acima do campo de código de barras
            title: 'Por favor informe o código:',
            // Label do campo de código de barras
            label: 'Código',
            // Texto do botão para enviar o código de barras
            button: 'Pagar',
            description: [
                {
                    label: 'Favorecido:',
                    value: 'Estacionamento Novo Shopping',
                },
            ],
        },
    }
};

Ame.openBarcodeScanner(barCodeOptions).then(barcodeData => {
    //{data: "4123412341234", type: "ean13"}
}).catch(e => console.log("erro ao executar a leitura de código de barras", e));

Método getEnvironment

import Ame from "ame-super-app-client";
Ame.getEnvironment()
    .then(env => console.log(`Ambiente ${env}`))
    .catch(e => console.log("erro ao recuperar o ambiente.", e));

Método makePhoneCall

import Ame from "ame-super-app-client";
Ame.makePhoneCall("21999999999");

Método openBrowser

import Ame from "ame-super-app-client";
Ame.openBrowser({url: "https://google.com"});

Método pickAddress

Abre uma tela que permite selecionar um endereço e retorna os dados do endereço selecionado.

import Ame from "ame-super-app-client";

Ame.pickAddress().then(address => {
    console.log(address)
    /* Exemplo de saída desse console.log:
    {
        countryCode: 'BRA',
        additionalInfo: '',
        zipCode: '12345-678',
        main: 'true',
        state: 'RJ',
        city: 'Rio de Janeiro',
        district: 'Centro',
        number: '1',
        address: 'Beco Diagonal',
        customerId: '85b6e3c8-85b6e3c8-85b6e3c8-85b6e3c8-85b6e3c8'
    } */
});

Método getOrderDetails

Obtém informações sobre um pagamento. Esse método deve ser utilizado apenas na view OrderDetails, e é utilizado para exibir informações específicas sobre um pedido. Mais detalhes na seção "Exibição de detalhes do pedido"

import Ame from "ame-super-app-client";
Ame.getOrderDetails()
    .then(orderDetails => {
        console.log(orderDetails)
        /* Exemplo de saída desse console.log:
        {
            orderId: "1b8bb06b-b217-460a-9a41-72279a0f8123"
        } */
    })
    .catch(response => {
        console.log("Erro ao recuperar detalhes do pedido: ", response)
    })

Exibição de detalhes do pedido

Dependendo do pedido feito no MiniApp, pode ser necessário que o usuário verifique informações sobre o pedido. Por exemplo, caso esteja fazendo uma entrega de uma encomenda, é interessante que o usuário tenha a oportunidade de rastrear o pedido. Ou, pode ser importante que, em uma outra situação, o usuário tenha acesso a um QR Code após a compra.

É necessário seguir alguns passos para ter suporte à exibição de detalhes do pedido

  1. Na callbackUrl passada no Ame.startPayment do pedido, fazer com que essa url registre as informações do pedido Ame (em particular, o id da raiz do objeto*) e as associe com as informações do pedido no seu backend

* Esse id é o primeiro id no objeto de exemplo da documentação do Ame.startPayment. É importante notar que não é o id dentro de splits, e nem o orderId dentro de attributes

  1. Passar o parâmetro hasOrderDetails com valor true no objeto passado para o Ame.startPayment

  2. Criar uma view nomeada OrderDetails no miniapp, e nela, chamar a função Ame.getOrderDetails para obter o id do pedido Ame e buscar em seu backend as informações do pedido a serem exibidas para o usuário

Note que não deve haver navegação normal (através de Ame.navigate) levando à view OrderDetails, pois ela não ira funcionar se não for acessada através do detalhamento de pedido do App da Ame

Testando os detalhes de pedido

Antes de publicar o miniapp, é possível testar a funcionalidade de exibição dos detalhes do pedido usando a cli ame-app-tools. Mais informações sobre como utilizá-la na documentação da mesma.

Last updated on 7/9/2021
Notas da versão →