Quick Start: Sua Primeira Inicialização

Antes de poder processar quaisquer pagamentos, seu aplicativo cliente deve inicializar o Tap on Phone App. Esta inicialização estabelece uma sessão segura, aciona a validação de Single Sign-On (SSO) com o seu backend e prepara o terminal.

Normalmente, você realiza essa inicialização uma vez quando o lojista faz login no seu aplicativo. A sessão permanece ativa entre as inicializações do app e as reinicializações do dispositivo até que você a redefina (reset) explicitamente.

Este tutorial orienta você na criação do intent InitActivity, na passagem dos parâmetros necessários e no tratamento do resultado.

Pré-requisitos

Antes de começar, certifique-se de que você tem:

• Seu Client ID, Merchant ID, User ID e User Token. (Você pode usar os valores de teste em sandbox fornecidos no guia Pré-requisitos e Configuração).
• Configurou seu backend para gerenciar solicitações de SSO, conforme descrito em Integração de Backend: Gerenciando Solicitações de SSO.
• Integrou as APIs Activity Result do AndroidX em seu projeto Android.

Passo 1: Preparar os metadados da operação

Para rotear a solicitação de SSO para o seu backend corretamente, você deve passar o seu Client ID no extra operationMetadata. Este campo requer uma string JSON válida.

Formate o seu Client ID como uma string JSON no seu código:

// Replace with your actual Client ID or the sandbox test value
val operationMetadata = "{\"ClientID\":\"your-client-id-here\"}"

Passo 2: Registrar o Activity Result Launcher

Para gerenciar a resposta do aplicativo Tap on Phone, registre um callback de Activity Result. Este callback escuta a conclusão do processo de inicialização.

val posInitResult = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result ->
    if (result.resultCode == Activity.RESULT_OK) {
        // Initialization successful. The POS is ready to process payments.
        println("SoftPOS Initialization completed successfully.")
    } else if (result.resultCode == Activity.RESULT_CANCELED) {
        // Initialization failed. Extract the error details.
        val data = result.data
        val errorCode = data?.getStringExtra("errorCode") ?: "None"
        val errorName = data?.getStringExtra("errorName") ?: "None"
        val errorMessage = data?.getStringExtra("errorMessage") ?: "None"

        println("Initialization failed: $errorName ($errorCode) - $errorMessage")
        // Manage the error and display options to your user
    }
}

Passo 3: Iniciar o Intent InitActivity

Construa um Android Intent direcionado à InitActivity do aplicativo Tap on Phone. Você deve incluir o package name, o class name e todos os extras obrigatórios.

Crie uma função para construir e iniciar o intent:

private fun startPosInit(userId: Int, merchantId: Int, userToken: String, operationMetadata: String) {
    val intent = Intent().apply {
        // Specify the Tap on Phone package and the InitActivity class
        setClassName(
            "com.dejamobile.cbp.sps.app",
            "com.dejamobile.cbp.sps.app.InitActivity"
        )

        // Add the mandatory extras
        putExtra("userId", userId)
        putExtra("merchantId", merchantId)
        putExtra("userToken", userToken)
        putExtra("operationMetadata", operationMetadata)
    }

    // Launch the intent using the registered callback
    posInitResult.launch(intent)
}

Passo 4: Executar e Verificar

Chame a sua função startPosInit usando suas credenciais de sandbox.

Se a validação de SSO for bem-sucedida e o dispositivo passar nas verificações de segurança iniciais, o callback receberá RESULT_OK. Seu aplicativo agora está pronto para processar transações.

Se você receber RESULT_CANCELED, verifique o errorCode e errorMessage retornados. Problemas comuns durante a inicialização incluem timeouts de rede, Client IDs incorretos ou respostas não autorizadas do seu backend de SSO.

Próximos Passos

Agora que você inicializou com sucesso o aplicativo Tap on Phone, você pode explorar os conceitos centrais ou ir direto para o processamento de pagamentos.

• Entenda a Arquitetura.
• Aprenda como Processar uma Transação de Compra.