Como integrar a EngagED com minha base de dados?

Se você deseja atribuir um desconto automático para pessoas de sua base, utilizar uma autenticação própria ou impedir que a inscrição ocorra por determinadas regras de negócio própria, leia este artigo!

Existem diferentes cenários que necessitam de integração entre a EngagED e a base de dados de nossos clientes. Se você se identifica com algum dos casos abaixo, este artigo é pra você:

• Quero atribuir um desconto automático para pessoas que trabalham em minha empresa, que são ex-alunos, associados, entre outros;
• Quero impedir de que a pessoa prossiga com sua inscrição caso esteja inadimplente em minha base;
• Quero que a pessoa se autentique em minha base, e eu possa reaproveitar alguns dados básicos como nome, e-mail, e telefone para que ela prossiga com a inscrição na EngagED sem precisar criar um cadastro do zero, ou então simplesmente que se autentique em minha base para que eu dê sequência com outros processos internamente;

Se você se identifica com algum dos casos acima, este artigo é para você.

 

Diferente da abordagem padrão de autenticação que a EngagED costuma utilizar (passwordless), quando nosso cliente decide utilizar uma página de autenticação externa para atender alguma das necessidades pontuadas acima, precisamos passar pelos seguintes passos:

1. Redirecionamento para a página para autenticação;
2. Processamento dos dados retornados para a EngagED pós autenticação;

Redirecionamento para a página de autenticação

 

Sempre que o usuário (aluno) clicar em "Inscreva-se" (a partir das Landing Pages da EngagED Sales), a EngagED exibirá uma “modal” com as seguintes opções de autenticação:

1. Autenticação externa (autenticação através da página de nosso cliente EngagED, com o nome do botão de acordo com o devido contexto, por exemplo: "Entrar como advogado”, “entrar como Comerciário", "entrar como Associado XYZ", entre outros...);
2. Outros (autenticação através do método tradicional da EngagED, para público aberto, permitindo que a pessoa acesse a inscrição através de nosso próprio método de autenticação passwordless);

Autenticação externa

No momento em que o usuário (aluno) deseja realizar a inscrição em uma turma, e optar pela autenticação externa definida pelo cliente EngagED, a EngagED abrirá a página de autenticação externa, enviando o seguinte parâmetro por URL:

 

Parâmetro enviado pela EngagED, por URL, ao chamar a página de autenticação do cliente EngagED:

Variável	Tipo	Descrição
redirect_uri	String	Parâmetro enviado por URL pela EngagED ao chamar a página de autenticação externa do cliente EngagED. Esta URL deverá ser requisitada (GET) pela página de autenticação do cliente EngagED após autenticação pelo usuário (aluno), enviando o parâmetro payload com os atributos pertinentes ao usuário (aluno) recém autenticado (mais informações sobre o payload abaixo). |

 

Após o usuário realizar a autenticação externa no ambiente do cliente EngagED, a página de autenticação deverá redirecionar o usuário (aluno) chamando a URL passada no parâmetro redirect_uri, contendo o parâmetro de URL payload, "encodado" em base64, contendo os atributos esperados pela EngagED para continuidade da jornada do usuário.

 

Parâmetro que deve ser enviado pelo cliente EngagED para a EngagED, por URL, ao chamar a URL (redirect_uri) informada pela EngagED

Chave	Tipo	Descrição
payload	String	String “encodada” em base64, contendo todos os atributos esperados pela EngagED para dar continuidade na jornada do usuário (aluno) no processo de inscrição;

 

 

Exemplo de codificação base64

ewoJIm5hbWUiOiAiSnVjYSBGcmFuYXRvIiwKCSJjcGYiOiAiNjc0MTgwNDQwNDYiLAoJImVtYWlsIjogImp1Y2EuZnJhbmF0b0BnbWFpbC5jb20iLAoJInBob25lIjogIis1NTQxOTk4MzU4MTgwIgoJImFjdGlvbiI6IHsKCQkiY29kZSI6ICJkaXNjb3VudCIsCgkJInR5cGUiOiAiY2VudHMiLAoJCSJhbW91bnQiOiAyNTQwCgl9LAoJImZyZWV6ZV9wcm9wZXJ0aWVzIjogWyJuYW1lIiwgInBob25lIiwgImVtYWlsIiwgImNwZiJdCn0

 

Processamento dos dados retornados para a EngagED pós autenticação

 

Após o usuário (aluno) ter realizado a autenticação externa na página do cliente EngagED, a EngagED, agora com posse do payload retornado por parâmetro, irá converter a String recebida em base64 para a interpretação dos atributos retornados.

 

Exemplo de payload retornado em base64

ewoJIm5hbWUiOiAiSnVjYSBGcmFuYXRvIiwKCSJjcGYiOiAiNjc0MTgwNDQwNDYiLAoJImVtYWlsIjogImp1Y2EuZnJhbmF0b0BnbWFpbC5jb20iLAoJInBob25lIjogIis1NTQxOTk4MzU4MTgwIgoJImFjdGlvbiI6IHsKCQkiY29kZSI6ICJkaXNjb3VudCIsCgkJInR5cGUiOiAiY2VudHMiLAoJCSJhbW91bnQiOiAyNTQwCgl9LAoJImZyZWV6ZV9wcm9wZXJ0aWVzIjogWyJuYW1lIiwgInBob25lIiwgImVtYWlsIiwgImNwZiJdCn0=

 

Utilizando ferramentas de codificação/decodificação de base64, a String acima resultará em:

{
	"name": "Vinícius Mendes",
	"cpf": "78734297090",
	"email": "vms@engaged.com.br",
	"phone": "+5541998358180"
	"action": {
		"code": "discount",
		"type": "cents",
		"amount": 2540
	},
	"freeze_properties": ["name", "phone", "email", "cpf"]
}

Dados do usuário no payload

 

Campo	Tipo	Descrição
name	String	Nome completo do usuário (aluno) que recém se autenticou.
cpf	String	CPF do usuário (aluno) que recém se autenticou (sem pontuação e caracteres especiais, exemplo 78734297090
email	String	E-mail do usuário (aluno) que recém se autenticou
phone	String	Telefone do usuário (aluno) que recém se autenticou, no formato +5541998358180

Objeto de ação a ser tomada após autenticação

 

O payload deverá conter o atributo action, contendo qual ação (code) a EngagED deverá tomar após o cliente da EngagED ter redirecionado para a página redirect_uri.

Possíveis ações que podem ser tomadas

• none: a EngagED prosseguirá normalmente com o fluxo de inscrição, apenas auto-preenchendo os campos do usuário (aluno) retornados no payload;
• discount: a EngagED prosseguirá com o fluxo de inscrição, auto-preenchendo os campos do usuário (aluno), e adicionando automaticamente o desconto informado no objeto action;
• block: a EngagED irá interromper o fluxo de inscrição, exibindo na interface a mensagem configurada pelo cliente EngagED na variável user_message.

action.none

Para casos onde se deseja continuar com o fluxo de inscrição após a autenticação, apenas auto-preenchendo os campos do usuário.

Exemplo de objeto action

...

  "action": {
    "code": "none"
  } 

...

action.discount

Para casos onde se deseja continuar com o fluxo de inscrição após a autenticação, auto-preenchendo os campos do usuário, e adicionando um desconto automaticamente durante o processo de pagamento.

Existem 2 possibilidades de atribuição de desconto:

1. percentage: desconto em porcentagem, onde se deseja aplicar uma porcentagem de desconto em cima do valor à ser cobrado. Em casos onde se deseja aplicar, por exemplo, X% de desconto no pagamento para a pessoa autenticada;
2. cents: desconto, em centavos, referente ao valor absoluto em desconto que se deseja aplicar. Em casos onde se deseja aplicar, por exemplo, X reais de desconto no pagamento para a pessoa autenticada;

Exemplo de objeto de desconto para porcentagem

    ...
    
    "action": {
        "code": "discount",
        "type": "percentage",
        "amount": 50
    }
    
    ...

Exemplo de objeto de desconto para valores absolutos (cents)

    ...
    
    "action": {
        "code": "discount",
        "type": "cents",
        "amount": 2540
    }
    
    ...

action.block

Para casos onde se deseja interromper o fluxo de inscrição, por qualquer que seja o motivo, exibindo na interface a mensagem configurada pelo cliente EngagED na variável user_message.

 

Exemplo de objeto de interrupção de inscrição

    ...
    
    "action": {
        "code": "block",
        "user_message": "Infelizmente você não poderá seguir com a inscrição.<br/>Regularize sua situação financeira <a href=\\"<https://meusite.com>\\">clicando aqui</a>."
    }
    
    ...

 

Bloqueio de campos para não serem alterados pelo usuário (aluno) durante a inscrição

 

O payload poderá conter o atributo freeze_properties, contendo os campos que deseja que o usuário (aluno) não altere durante seu fluxo de inscrição.

Campo	Tipo	Descrição
freeze_properties	Array de Strings String[]	Array contendo as opções de campos que deseja bloquear para que o usuário (aluno) não altere durante seu processo de inscrição, podendo ser ”name”, “phone”, “email”, “cpf”

 

Exemplo de array freeze_properties preenchido

    ...
    
    "freeze_properties": ["name", "phone", "email", "cpf"]
    
}

Entendi! Por agora por onde devo começar?

Aqui vão algumas lições do lado do cliente EngagED para poder operar com autenticação externa:

1 - Prepare uma página própria, que a EngagED irá chamar, no procedimento de autenticação externa, para que assim que alguém demonstrar interesse em se inscrever a partir das Landing Pages da EngagED, possamos redirecionar para esta página;

2 - Prepare esta página para receber por parâmetro o atributo redirect_uri, contendo a URL que deverá ser chamada (GET) (assim que tiver esta página desenvolvida, informe o time da EngagED para que possamos dar sequência na configuração de sua conta com método de autenticação externo);

3 - Em paralelo, após a autenticação do usuário (aluno) em sua página, interprete o que fazer com esta pessoa, para saber qual comportamento direcionar quando for chamar a URL presente em redirect_uri da EngagED;

4 - Sabendo como proceder, chame a URL redirect_uri informada, passando o payload em JSON “encodado” em base64;

Caso não tenha entendido alguma etapa deste artigo, fique a vontade em consultar nosso time de suporte! Estamos à disposição para te ajudar!

 

Conte conosco!

 

Vamos juntos!