Documentação Connect

Uma conta para suas lojas

O SDK permite acessar uma loja com a conta usada no aplicativo. Esta documentação descreve os métodos disponíveis nas lojas compatíveis.

A janela central permite entrar e criar uma conta. Sua interface está disponível em francês e inglês, embora esta documentação tenha versões em doze idiomas.

Adicionar o acesso

Em uma loja compatível, window.rankappConnect já está carregado e configurado. Use três métodos: login(), getSession() e logout(). Não é necessário instalar mais nada. O exemplo completo apenas adiciona botões e mensagens acessíveis.

Chame login() diretamente a partir de um clique. A promessa retorna {status: "success", session}, {status: "cancelled"} ou {status: "redirecting"}. Erros rejeitam a promessa com um código estável. Em dispositivos móveis ou com popups bloqueados, o fluxo usa redirecionamento. returnTo deve permanecer na sua loja.

const connect = window.rankappConnect;

function onSignInClick() {
  return connect.login({ returnTo: '/account' });
}

function readSession() {
  return connect.getSession();
}

function onSignOutClick() {
  return connect.logout();
}

<button type="button" id="connect-login">Entrar com RankAPP</button>
<button type="button" id="connect-logout" hidden>Sair</button>
<p id="connect-status" role="status" aria-live="polite"></p>

<script>
const connect = window.rankappConnect;
const login = document.querySelector('#connect-login');
const logout = document.querySelector('#connect-logout');
const status = document.querySelector('#connect-status');
const copy = {
  "cancelled": "Login cancelado. Você pode tentar novamente.",
  "redirecting": "Redirecionando para o login…",
  "login": "Entrar com RankAPP",
  "logout": "Sair",
  "signedOut": "Você está desconectado.",
  "signedIn": "Conectado: ",
  "error": "Não foi possível entrar. Tente novamente.",
  "pending": "Entrando…"
};
function render(session) {
  status.textContent = session.authenticated
    ? copy.signedIn + session.user.username : copy.signedOut;
  logout.hidden = !session.authenticated;
}
function failure() {
  status.textContent = copy.error;
}
function busy(value) {
  login.disabled = logout.disabled = value;
}
login.addEventListener('click', async () => {
  busy(true);
  status.textContent = copy.pending;
  let redirecting = false;
  try {
    const result = await connect.login({ returnTo: '/account' });
    if (result.status === 'success') render(result.session);
    else if (result.status === 'cancelled') status.textContent = copy.cancelled;
    else {
      redirecting = true;
      status.textContent = copy.redirecting;
    }
  } catch (error) { failure(); }
  finally { if (!redirecting) busy(false); }
});
logout.addEventListener('click', async () => {
  busy(true);
  try { render(await connect.logout()); }
  catch (error) { failure(); }
  finally { busy(false); }
});
busy(true);
connect.getSession().then(render).catch(failure)
  .finally(() => busy(false));
</script>

Exibir a sessão

getSession() consulta o servidor: {authenticated: false} significa que não há sessão. Uma sessão autenticada inclui user (userId, username, avatarUrl, language) e, em lojas gerenciadas, orders. Consulte ao carregar a página e após redirecionamentos; nunca deduza a identidade pela URL.

Falhas do serviço continuam sendo erros: STOREFRONT_SESSION_ERROR não vira uma sessão desconectada. Exiba uma mensagem para tentar novamente. login() distingue cancelamento e falha; logout() encerra apenas a sessão da loja.

Identidade e cookies

O SDK exige HTTPS para todos os sites e endpoints, inclusive no desenvolvimento local. Use um servidor local HTTPS com um certificado confiável para o navegador. HTTP nunca é aceito para autenticação.

A senha é digitada em auth.rankapp.io, nunca no site do lojista. Um código de uso único e PKCE S256 vinculam a janela à solicitação original. A troca do código e os tokens ficam no servidor. A mensagem de conclusão da janela não contém tokens.

Os cookies usam HttpOnly, Secure e SameSite=Lax, limitados ao próprio host, sem atributo Domain compartilhado. A sessão central e as sessões de cada loja são separadas. logout() encerra a sessão da loja, sem necessariamente encerrar a sessão central.

O servidor da loja

Esta documentação abrange o SDK 1.1.0. Em uma loja compatível, use apenas o cliente pré-configurado window.rankappConnect. O servidor gerencia o login, a sessão e o logout; o cliente aplica o transporte assinado necessário. Não é preciso configurar endpoints nem adaptadores na página.

Testar na prévia

A prévia aceita contas reais para testar entrada e saída como cliente. O acesso privado ao rascunho usa uma permissão separada: abrir a prévia não conecta automaticamente um comprador. Os pagamentos ficam desativados nesse ambiente.

Teste acesso concluído, cancelamento, fechamento da janela, retorno no celular e nova entrada após sair. Em produção, a loja precisa estar publicada e acessível. Uma autenticação bem-sucedida não confirma pagamento; acompanhe o resultado financeiro separadamente.

Preparar uma integração externa

O cadastro de integrações para sites externos independentes ainda não está aberto. Essa etapa exige registro dos clientes, aprovação das URLs de retorno e definição dos direitos de acesso.

Não invente um client_id, um endpoint de tokens ou uma configuração OIDC supostamente compatíveis. O contrato atual atende às lojas compatíveis e ao adaptador fornecido. Mantenha senhas e tokens fora do JavaScript do lojista e confirme a sessão no servidor.