Lite SDK (Enrollment Android)

Esta página fornece um guia para o Lite SDK do Yuno Lite SDK para registro no Android. Esse SDK oferece um processo de integração simplificado com funcionalidade essencial de registro, tornando-o ideal para comerciantes que:

• Precisa de uma implementação rápida com requisitos mínimos de personalização
• Deseja se concentrar principalmente no registro de métodos de pagamento
• Prefira uma interface de usuário pronta para uso que lide com o fluxo de registro

O Lite SDK inclui recursos essenciais como:

• Componentes de UI de registro pré-criados
• Processamento de registro de cartões
• Tratamento básico do status do registro
• Gerenciamento de erros essenciais

Para os comerciantes que precisam de recursos mais avançados, como vários métodos de pagamento, interface de usuário personalizada ou prevenção avançada contra fraudes, considere usar nosso Full SDK em vez disso.

Requisitos

Antes de iniciar a integração do Yuno Android SDK, certifique-se de que seu projeto atenda aos requisitos técnicos. Além disso, certifique-se de que os seguintes pré-requisitos estejam em vigor:

• Você deve ter uma conta Yuno ativa
• Você precisa de suas credenciais de API da Yuno (public-api-key), que você pode obter no Seção de desenvolvedores do painel do Yuno
• Antes de registrar um método de pagamento, você deve primeiro criar um cliente usando o endpoint Criar cliente

Etapa 1: Criar um cliente

Crie um cliente no sistema da Yuno usando o Criar endpoint do cliente antes de registrar os métodos de pagamento. Esse endpoint retornará um customer_id que você usará para associar os métodos de pagamento inscritos a um cliente específico.

O endpoint retornará um customer_session que você precisará usar ao chamar os métodos de registro.

Etapa 2: Inclua a biblioteca em seu projeto

Adicione o Lite SDK do Yuno Lite SDK ao seu projeto Android:

Adicionar o repositório

Adicione o repositório Maven do Yuno à configuração do Gradle do seu projeto:

maven { url "https://yunopayments.jfrog.io/artifactory/snapshots-libs-release" }

Inclua o seguinte código no arquivo build.gradle para adicionar a dependência do Yuno SDK ao aplicativo:

dependencies {
    implementation 'com.yuno.payments:android-sdk:{last_version}'
}

Permissões

O SDK do Yuno inclui o INTERNET por padrão, que é necessária para fazer solicitações de rede.

<uses-permission android:name="android.permission.INTERNET" />

Etapa 3: Initialize o SDK com a chave pública

Initialize o SDK:

1. Obtenha sua chave de API pública no painel do Yuno
2. Crie uma classe de aplicativo personalizada, caso ainda não o tenha feito
3. No onCreate() de sua classe de aplicativo, chame o método Yuno.initialize() com sua chave de API:

class CustomApplication : Application() {
  override fun onCreate() {
    super.onCreate()
    Yuno.initialize(
      this,
      PUBLIC_API_KEY,
      config: YunoConfig,
    )
  }
}

Use a classe de dados YunoConfig para personalizar o comportamento do SDK. Inclua essa configuração ao chamar Yuno.initialize(). As opções disponíveis são:

data class YunoConfig(
    val cardFlow: CardFormType = CardFormType.ONE_STEP,
    val saveCardEnabled: Boolean = false,
    val keepLoader: Boolean = false,
    val cardFormDeployed: Boolean = false,
    val language: YunoLanguage? = null,
    val styles: YunoStyles? = null
)

A tabela a seguir descreve cada opção de personalização:

Você também precisa atualizar seu manifesto para usar seu aplicativo:

<application android:name=".CustomApplication"></application>

Etapa 4: Registre um novo método de pagamento

O processo de registro é um fluxo de duas etapas. Primeiro, initialize o processo para configurar os componentes necessários. Em seguida, inicie o fluxo da interface do usuário para permitir que o usuário registre um método de pagamento.

4.1 Initialize o processo de registro

Ligue para o initEnrollment dentro do método onCreate para preparar seu aplicativo para lidar com o fluxo de registro. Essa é uma etapa de configuração obrigatória exigida pelo sistema operacional Android para registrar o contrato que permite que o SDK envie o status final da inscrição de volta ao seu aplicativo.

fun ComponentActivity.initEnrollment(
   callbackEnrollmentState: ((String?) -> Unit)? = null
)

4.2 Iniciar o fluxo de registro

Ligue para o startEnrollment para iniciar a interface do usuário e começar o registro de um novo método de pagamento. Você pode chamar esse método em qualquer ponto após initEnrollment tiver sido executada, como quando um usuário toca no botão "Inscrever novo método de pagamento".

fun Activity.startEnrollment(
    customerSession: String,
   countryCode: String,
    showEnrollmentStatus: Boolean = true,
   callbackEnrollmentState: ((String?) -> Unit)? = null,
    requestCode: Int
)

A tabela a seguir descreve os startEnrollment parâmetros:

Estado de registro de retorno de chamada

O callbackEnrollmentState é uma função que retorna o status atual do processo de registro. Forneça essa função somente se quiser rastrear o status do registro.

Use o AppCompatActivity.enrollmentStatus() para verificar o estado atual do registro a qualquer momento. Essa função é opcional e aceita os mesmos parâmetros que startEnrollment. O bloco de código a seguir mostra a assinatura da função:

fun AppCompatActivity.enrollmentStatus(
    customerSession: String,
   countryCode: String,
    showEnrollmentStatus: Boolean = false,
   callbackEnrollmentState: ((String?) -> Unit)? = null,
)

📘

Função opcional

Usando a função enrollmentStatus é opcional. Não é um requisito para concluir o processo de inscrição. Saiba mais

🚧

Substituição de retorno de chamada

Se você fornecer um novo retorno de chamada ao chamar a função enrollmentStatusele substituirá o retorno de chamada que você definiu ao chamar a função initEnrollment.

O bloco de código a seguir mostra os possíveis estados:

const val ENROLLMENT_STATE_SUCCEEDED =SUCCEEDED"
const val ENROLLMENT_STATE_FAIL = "FAIL" (Reprovado)
const val ENROLLMENT_STATE_PROCESSING = "PROCESSANDO"
const val ENROLLMENT_STATE_REJECT = "REJECT" (Rejeitado)
const val ENROLLMENT_STATE_INTERNAL_ERROR = "INTERNAL_ERROR"
const val ENROLLMENT_STATE_CANCELED_BY_USER = "CANCELED" (Cancelado pelo usuário)

A tabela a seguir fornece informações adicionais sobre os possíveis estados:

Usando o OnActivityResult método

❗️

Método obsoleto

O onActivityResult é uma solução obsoleta. Se você estiver realizando uma nova integração com o Android, a Yuno recomenda usar o método initEnrollment() que segue as práticas recomendadas do Google.

O método onActivityResult é chamado automaticamente quando uma atividade retorna um resultado. Você pode usar essa opção para executar ações sempre que o status do registro for alterado. Siga estas etapas para processar o resultado do registro:

📘

Uso do código de solicitação padrão

Se você estiver usando o onActivityResult mas não informou um método requestCode ao chamar o startEnrollment em Etapa 3, você deve usar o YUNO_ENROLLMENT_REQUEST_CODE fornecido pela Yuno.

1. Substituir o onActivityResult método. Isso garante que as chamadas de hierarquia sejam respeitadas.

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
}

2. Verifique se o requestCode corresponde a YUNO_ENROLLMENT_REQUEST_CODE. Como você está executando Yuno em seu aplicativo, você pode importar o YUNO_ENROLLMENT_REQUEST_CODE para usá-lo.

Se (requestCode == YUNO_ENROLLMENT_REQUEST_CODE) {
}

3. Se o requestCode corresponde, manipule o resultado do registro. Extraia o estado de registro usando a função YUNO_ENROLLMENT_RESULT fornecida pela biblioteca Yuno. Criar um onEnrollmentStateChange para lidar com as alterações de estado.

onEnrollmentStateChange(data?.getStringExtra(YUNO_ENROLLMENT_RESULT))

O bloco de código a seguir mostra um exemplo de código para usar o OnActivityResult para executar funções quando o status do registro for alterado:

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)

    if (requestCode == YUNO_ENROLLMENT_REQUEST_CODE) {
        val enrollmentState = data?.getStringExtra(YUNO_ENROLLMENT_RESULT)
        onEnrollmentStateChange(enrollmentState)
    }
}

fun onEnrollmentStateChange(enrollmentState: String?) {
    when (enrollmentState) {
        "SUCCEEDED" -> {
        }
        "FAIL" -> {
        }
    }
}

Etapa 5: Obter o status da inscrição

Ligue para o initEnrollment no método onCreate da atividade para registrar um retorno de chamada para obter o estado final da inscrição.

Recursos complementares

O Yuno Android SDK fornece serviços e configurações adicionais que você pode usar para melhorar a experiência dos clientes. Use a personalização do SDK para alterar a aparência do SDK de acordo com sua marca ou para configurar o carregador.

styles

Com o styles opção de personalização, você pode definir estilos visuais globais por meio de um YunoStyles objeto. Ele permite que você aplique uma marca consistente em todo o SDK, personalizando a aparência e a tipografia do botão.

classe de dados YunoStyles(
    val buttonStyles: YunoButtonStyles? = null,
    val fontFamily: FontFamily? = null
)

O YunoButtonStyles permite que você defina configurações específicas para a aparência do botão:

classe de dados YunoButtonStyles(
    val backgroundColor: Color? = null,
    val contentColor: Color? = null,
    val cornerRadius: Dp? = null,
    val elevation: Dp? = null,
    val padding: Dp? = null,
    val fontFamily: FontFamily? = null,
    val fontSize: TextUnit? = null,
    val fontStyle: FontStyle? = null
)

Use o YunoConfig descrita na Etapa 3, para usar a classe de dados styles opção de personalização.

Carregador

A funcionalidade do carregador é controlada por meio do keepLoader no parâmetro YunoConfig que está documentada em linha na seção de configuração do SDK acima.

Opções de renderização

Você pode escolher entre duas opções de renderização de formulário de cartão. As capturas de tela a seguir mostram a diferença entre cardFormType ONE_STEP e STEP_BY_STEP:

Personalização do SDK

Você pode alterar a aparência do SDK para que corresponda à sua marca. Para obter mais informações, consulte a página de personalização do SDK.

📘

Aplicativo de demonstração

Além dos exemplos de código fornecidos, você pode consultar o repositório do Yuno para concluir a implementação dos SDKs do Yuno para Android.

Modo de renderização (registro)

O modo de renderização do Yuno SDK permite integrar o fluxo de registro com controle total da interface do usuário, mantendo a validação e a lógica do SDK. O SDK retorna o Android Fragment que você pode exibir nos layouts Jetpack Compose (via AndroidView) e XML tradicional.

Função principal: startEnrollmentRender

fun Activity.startEnrollmentRender(
    customerSession: String,
   countryCode: String,
    submitButton: Boolean = false,
    coroutineScope: CoroutineScope,
    listener: YunoEnrollmentRenderListener
): YunoEnrollmentFragmentController

Parâmetros

Valor de retorno

Retorna um YunoEnrollmentFragmentController para controlar o fluxo de registro (por exemplo, enviar formulários).

Exemplo de uso

class EnrollmentActivity : Activity() {

    private lateinit var fragmentController: YunoEnrollmentFragmentController

    private fun initializeEnrollment() {
        fragmentController = startEnrollmentRender(
            customerSession = "your_customer_session_id",
            countryCode = "US",
            submitButton = false,
            coroutineScope = lifecycleScope,
            listener = enrollmentRenderListener
        )
    }
}

Interface: YunoEnrollmentRenderListener

Implemente essa interface para receber fragmentos e eventos de registro.

interface YunoEnrollmentRenderListener {
    fun showView(fragment: Fragment, needSubmit: Boolean)
    fun returnStatus(resultCode: Int, paymentStatus: String)
    fun loadingListener(isLoading: Boolean)
}

showView(fragment: Fragment, needSubmit: Boolean)

• Recebe o fragmento a ser exibido no contêiner da interface do usuário
• needSubmit indica se você deve exibir seu próprio botão de envio (quando submitButton = false)

Exemplo (XML):

override fun showView(fragment: Fragment, needSubmit: Boolean) {
    supportFragmentManager.beginTransaction()
        .replace(R.id.enrollment_container, fragment)
        .commit()

    clientSubmitButton.isVisible = needSubmit
    if (needSubmit) {
        clientSubmitButton.setOnClickListener { fragmentController.submitForm() }
    }
}

returnStatus(resultCode: Int, paymentStatus: String)

• Evento de status final de inscrição. Use-o para notificar o usuário sobre o sucesso ou fracasso

loadingListener(isLoading: Boolean)

• Carregamento da chamada de retorno de estado para mostrar/ocultar os spinners e desativar/desabilitar a interface do usuário

override fun loadingListener(isLoading: Boolean) {
    progressBar.isVisible = isLoading
    clientSubmitButton.isEnabled = !isLoading
}

Interface: YunoEnrollmentFragmentController

Devolvido por startEnrollmentRender para controlar o fluxo de registro.

interface YunoEnrollmentFragmentController {
    fun submitForm()
}

val fragmentController = startEnrollmentRender(
    customerSession = "your_customer_session_id",
   countryCode = "US",
    submitButton = false,
    coroutineScope = lifecycleScope,
    listener = enrollmentRenderListener
)

3. Controle o fluxo (envie quando necessário):

fragmentController.submitForm()

Vantagens do modo de renderização

Flexibilidade da interface do usuário

• Compatível com Compose (via AndroidView) e XML
• Controle total sobre onde e como as visualizações são exibidas
• Fácil de combinar com o sistema de design do seu aplicativo

Controle de fluxo

• Tempo de envio personalizado usando submitForm()

Considerações importantes

• Gravata coroutineScope para seu ciclo de vida de atividade/fragmento (por exemplo, lifecycleScope)
• Quando needSubmit = truerenderize seu próprio botão de envio e chame submitForm()
• No Compose, coloque o fragmento em um arquivo AndroidView contêiner