Web (script tag)

O SDK embeddable da Web é um bundle vanilla, sem dependências. Inclua uma <script> e o objeto global MalvoConnect fica disponível. Ele abre o widget hospedado em um popup centralizado e converte os eventos postMessage (malvo:success, malvo:error, malvo:close) nos seus callbacks.

Instalação

<script src="https://malvo.io/widget.js"></script>

Uso

A única opção obrigatória é o connectToken gerado pelo seu backend.

<script src="https://malvo.io/widget.js"></script>
<script>
  var handle = MalvoConnect.init({
    connectToken: "<token do seu backend>",
    countries: ["GB", "PT"],
    language: "pt",
    onSuccess: function (data) {
      // data.item — o Item criado (id, status, connector, ...)
      console.log("Item:", data.item);
    },
    onError: function (error) {
      // error.code, error.message
      console.error(error);
    },
    onClose: function () {
      console.log("widget fechado");
    },
  });

  // Para fechar o widget programaticamente:
  // handle.close();
</script>

Chamar MalvoConnect.init(...) abre o widget imediatamente e devolve um handle com um método close().

Os webhooks são a fonte da verdade. O onSuccess é UX best-effort — o usuário pode fechar a aba/popup antes dele disparar. Persista as conexões a partir dos webhooks item/created / item/updated no seu backend. Veja Webhooks.

Opções de `MalvoConnect.init`

string

required

O connectToken de 30 minutos gerado pelo seu backend (POST /connect_token). Sem ele, o init lança um erro.

string

default:"origem do widget hospedado"

Origem que serve o widget hospedado. O widget é aberto em {url}/connect?token=.... Em produção, é https://malvo.io.

boolean

default:"false"

Exibe conectores de sandbox que já estejam autorizados para a aplicação.

string

Id do Item em atualização. O connectToken deve ter sido emitido para esse mesmo Item.

string[]

Restringe o catálogo por tipo, como ["PERSONAL_BANK"].

number[]

Restringe o catálogo aos IDs informados.

string[]

Países ISO-3166-1 alpha-2, por exemplo ["GB", "PT"]. O filtro sempre intersecta o catálogo autorizado pelo backend.

'pt' | 'en'

default:"pt"

Idioma do fluxo hospedado.

number

Abre diretamente o conector quando ele também satisfaz todos os filtros ativos.

(data) => void

Disparado no evento malvo:success. Recebe { item }, onde item é o Item criado.

(error) => void

Disparado no evento malvo:error. Recebe { code, message }. Se o widget não enviar detalhes, o callback recebe { code: "UNKNOWN", message: "Erro desconhecido" }.

() => void

Disparado no evento malvo:close, quando você chama handle.close(), ou quando o usuário fecha o popup manualmente.

(event) => void

Recebe os eventos de ciclo de vida do widget para telemetria de UX.

Eventos (postMessage)

O widget se comunica com a sua página por postMessage. O SDK envia automaticamente a origem exata da página ao abrir o popup; o widget usa essa origem como targetOrigin, e o SDK só aceita mensagens vindas da origem configurada e da janela que ele próprio abriu. Cada mensagem tem um campo type:

`type`	Callback	Payload
`malvo:success`	`onSuccess({ item })`	`item` — o Item criado.
`malvo:error`	`onError(error)`	`error` com `code` e `message`.
`malvo:close`	`onClose()`	— fecha o popup e encerra os listeners.

O SDK também detecta o usuário fechando o popup manualmente (por polling) e, nesse caso, dispara onClose.

Se o navegador bloquear o popup, o SDK faz um redirect de página inteira para a URL do widget. Nesse caso, a conclusão é sinalizada pelos webhooks no seu backend — mais um motivo para tratá-los como a fonte da verdade.

Obtendo o connectToken do backend

O navegador só pode ver o connectToken. Gere-o em um endpoint autenticado do seu backend e busque-o antes de abrir o widget.

async function openMalvo() {
  const res = await fetch("/api/malvo/connect-token", { method: "POST" });
  const { accessToken } = await res.json();

  MalvoConnect.init({
    connectToken: accessToken,
    onSuccess: function (data) { console.log("Item:", data.item.id); },
    onError: function (error) { console.error(error); },
    onClose: function () {},
  });
}

const { apiKey } = await fetch("https://api.malvo.io/auth", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    clientId: process.env.MALVO_CLIENT_ID,
    clientSecret: process.env.MALVO_CLIENT_SECRET,
  }),
}).then((r) => r.json());

const { accessToken } = await fetch("https://api.malvo.io/connect_token", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-API-KEY": apiKey },
  body: JSON.stringify({
    options: {
      clientUserId: req.user.id,
      webhookUrl: process.env.MALVO_WEBHOOK_URL,
    },
  }),
}).then((r) => r.json());

return { accessToken };

Nunca exponha clientId, clientSecret ou apiKey no navegador. Gere um connectToken novo a cada abertura do widget. Veja o uso server-side completo em Node (server).

Próximos passos

React / Next.js

O componente <MalvoConnect> para apps React.

Node (server)

Geração do connectToken e leitura de dados com X-API-KEY.

Connect Widget

Todas as opções de inicialização e callbacks.

Webhooks

A fonte da verdade para o ciclo de vida dos Items.

Visão geral

Web & JavaScript

Mobile

Web (script tag)

Instalação

Uso

Opções de `MalvoConnect.init`

Eventos (postMessage)

Obtendo o connectToken do backend

Próximos passos

React / Next.js

Node (server)

Connect Widget

Webhooks

​Instalação

​Uso

​Opções de MalvoConnect.init

​Eventos (postMessage)

​Fallback quando o popup é bloqueado

​Obtendo o connectToken do backend

​Próximos passos

React / Next.js

Node (server)

Connect Widget

Webhooks

Instalação

Uso

Opções de `MalvoConnect.init`

Eventos (postMessage)

Fallback quando o popup é bloqueado

Obtendo o connectToken do backend

Próximos passos