UICallback

UICallback

Interface que disponibiliza os callbacks de interação com o usuário, responsável por gerenciar o comportamento e orquestrar a captura dos dados necessários para processar uma transação.

Para inicializar o MobileSDK, é necessário ter uma instância de UICallback. Sendo assim, nossa sugestão é criar uma Activity que se responsabilize pelo fluxo de integração e implemente essa interface (verifique nosso App de exemplo).

Abaixo, temos uma lista dos métodos definidos pela interface e informações que devemos utilizar para compreender qual o comportamento esperado pelo SDK, durante o processo transacional.

void onBeep()

Deve emitir um feedback sonoro, quando suportado.

void onClean()

Os componente utilizados para exibir mensagens e capturar dados ao usuário, devem ser “resetados”. Ou seja, devem ter seus status iniciais restaurados.

void onShowError(String message)

Utilizado para exibir uma mensagem de erro ao usuário. O App deve definir a melhor forma para tratar o callback. Contudo, a mensagem deve ser exibida de uma forma que permita ao usuário identificar que se trata de uma mensagem de erro.

Para auxiliar na visualização da mensagem, aplicar uma sleep de 2 segundos, após exibição da mensagem.

void onShowMessage(String message)

Deve exibir a mensagem ao usuário, da forma como ela é notificada. Esse callback é utilizado para apresentar mensagens gerais ao usuário, por exemplo: "Aguarde", "Solicitando autorização". Para exibir mensagens enviadas pelo autorizador, etc.

void requestConfirmation(String message, Result result)

Deve exibir a mensagem e solicitar confirmação ao usuário. Pode ser utilizado para confirmar a intenção de cancelar a execução da transação, por exemplo.

void onShowAlert(String message)

Deve exibir a mensagem ao usuário, de preferência, de forma destacada, para enfatizar que se trata de uma mensagem de atenção.

Atualmente, esta função é utilizada no momento de se desfazer uma transação, onde é apresentada uma mensagem indicando que a transação foi desfeita e o cupom deve ser retido. Por ser uma situação importante, é necessário a confirmação de leitura pelo operador, mesmo que o callback não exija uma resposta.

void onInput(InputModel inputModel, Result result)

Deve exibir ao usuário um componente para entrada de dados, respeitando as regras e definição do InputModel.

Observação

Para viabilizar a coleta da informação de forma automatizada, sem intervenção do usuário, pode-se utilizar o método inputModel.getValueId() a fim de identificar qual é a informação que está sendo solicitada. Deste modo, se a automação possuir a informação em memória, poderá retorná-la sem que seja necessária a entrada manual pelo usuário. (Consultar as informações possíveis em getValueId())

Se o valor retornado no getValueId for zero ou não estiver na lista de identificadores, deve-se manter a coleta padrão, com a solicitação da entrada da informação pelo usuário.

void onShowMenu(String label, List items, int selectedOption, MenuResult menuResult)

Deve exibir um componente de seleção, onde o usuário terá a possibilidade de selecionar uma das opções apresentadas ou cancelar a operação.

void onMaskInput(boolean clean, String label, String mask, String defaultValue, boolean enterKey, Result result)

Deve solicitar ao usuário a entrada de um dado, utilizando a máscara de edição informada nos parâmetros do callback. Dessa forma, é responsabilidade do App interpretar a máscara e formatar para o usuário.

Observação

A máscara deve ser omitida na resposta.

Exemplo

10/20, deve ser respondida como 1020.

CRetorno onMaskInputIdentified(int valueId, boolean clean, String label, String mask, String defaultValue, boolean enterKey)

[EM DESENVOLVIMENTO]

Deve solicitar ao usuário a entrada de um dado com máscara, similar à onMaskInput. Porém, nesse callback é possível identificar o valor que está sendo capturado através do parâmetro "valueId", que contém o código identificador (para mais detalhes, consultar getValueId()).

int getCanceledStatus()

Deve informar que o usuário sinalizou a intenção de abortar a operação. Normalmente esse callback é chamado em operações de pinpad, ou seja, quando a aplicação está no fluxo de pagamento, interagindo com o usuário através do DTEFMobile para capturar dados do cartão. (0 - cancelar, 1 - não cancelar)

Exemplo

Leitura do cartão, captura de senha.

int setCanceled(boolean canceled)

Permite que o usuário sinalize que deseja abortar uma operação que ocorre de forma paralela ao fluxo de UI. O retorno indica se a troca de status foi executada com sucesso. (0 - sucesso)

Esse callback funciona de forma complementar ao getCanceledStatus(). Para indicar que o fluxo deve ser abortado, o App deve informar valor true.

void onShowQRCode(String message, String qrCode, List tags)

Deve exibir o qrCode para o usuário e aguardar até o próximo comando de callback. Normalmente, utilizado no fluxo de pagamento com QrLinx/PIX, onde a lista de tags, pode ser retornada com informações associadas ao QrCode apresentado.

Observação

No caso do fluxo de QrLinx/PIX, a lista de tags irá informar o nome das carteiras de Wallet que podem finalizar (pagar) o QrCode

void onShowConsumer(String mensagem)

Adicionado na v2.7.13

Deve exibir a mensagem para o Consumidor (PDVs Android). A implementação desse callback é obrigatório quando se utiliza pinpad que não possui display, como o D140 da PAX.

void setCurrentTransactionInfo(int code, String value)

Adicionado na v2.7.3.4

Esse callback permite passar para a automação informação relacionada à transação corrente.

Parâmetro	Descrição
code	código da informação passada para a automação
value	valor da informação passada para a automação

Os códigos das informações constam na tabela a seguir:

Informação	Código
Código da rede autorizadora	25
Campos não utilizados na transação de Frota (formato JSON) [EM DESENVOLVIMENTO]	456
Link de pagamento na Transação com QR Code	1336

Clique aqui para expandir e mostrar exemplos

code = 25

Para a rede Stone o código é 127. Assim, nesse callback a automação deve receber code = 25 e value = "127", indicando que a transação será autorizada pela rede Stone.

code = 456 [EM DESENVOLVIMENTO]

Quando a automação enviar na transação de Frota produtos que não forem utilizados (devido às regras da adquirente), retorna-se nesse callback: code = 456 e value = String em formato JSON, conforme a estrutura a seguir:

JSON SCHEMA

{
"type": "object",
"required": [],
"properties": {
  "detalhes": {
  "type": "object",
  "required": [],
  "properties": {
    "nao_utilizados": {
    "type": "object",
    "required": [],
    "properties": {
    "servicos": {
    "type": "array",
        "items": {
        "properties": {
            "codigo"    : { "type": "number" },
            "quantidade": { "type": "number" },
            "valorTotal": { "type": "number" }
        },
        "required": [ "codigo", "quantidade", "valorTotal" ]
        }
    },
    "abastecimentos": {
    "type": "array",
        "items": {
        "properties": {
            "combustivel": { "type": "number" },
            "litros"     : { "type": "number" },
            "valorTotal" : { "type": "number" },
        },
        "required": [ "combustivel", "litros", "valorTotal" ]
        }
    }}}
  }}
}}

EXEMPLO

{
  "detalhes":{
    "nao_utilizados":{
      "servicos":[
        {
          "codigo":"1",
          "quantidade":"1",
          "valorTotal":"100.00"
        }
      ],
      "abastecimentos":[
        {
          "combustivel":"2",
          "litros":"10.00",
          "valorTotal":"66.30"
        }
      ]
    }
  }
}

// Caso a aplicação, não consiga alocar o buffer de retorno, será retornado o json
{
  "erro": "Buffer insuficiente"
}

code = 1336

Ao realizar uma Transação com QR Code via a rede QRLinx, a automação deve receber nesse callback code = 1336 e value sendo uma String contendo um link de pagamento. Este link pode ser disponibilizado ao cliente final via whatsapp, e-mail, SMS ou de alguma outra forma, permitindo assim disponibilizar mais um canal de pagamento para seu cliente.