Documentazione Connect

Un account per i negozi

Il SDK consente di accedere a un negozio con l’account usato nell’applicazione. Questa documentazione descrive i metodi disponibili nei negozi supportati.

La finestra centrale permette di accedere e creare un account. L’interfaccia è disponibile in francese e inglese, anche se la documentazione è tradotta in dodici lingue.

Aggiungere l’accesso

In un negozio compatibile, window.rankappConnect è già caricato e configurato. Usa tre metodi: login(), getSession() e logout(). Non occorrono altre installazioni. L’esempio completo aggiunge soltanto pulsanti e messaggi accessibili.

Chiama login() direttamente da un clic. La promessa restituisce {status: "success", session}, {status: "cancelled"} o {status: "redirecting"}. Gli errori rifiutano la promessa con un codice stabile. Su mobile o con popup bloccati si usa un reindirizzamento. returnTo deve rimanere nel tuo negozio.

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">Accedi con RankAPP</button>
<button type="button" id="connect-logout" hidden>Esci</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": "Accesso annullato. Puoi riprovare.",
  "redirecting": "Reindirizzamento all’accesso…",
  "login": "Accedi con RankAPP",
  "logout": "Esci",
  "signedOut": "Non hai effettuato l’accesso.",
  "signedIn": "Accesso effettuato: ",
  "error": "Accesso non disponibile. Riprova.",
  "pending": "Accesso in corso…"
};
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>

Mostrare la sessione

getSession() interroga il server: {authenticated: false} indica una sessione assente. Una sessione autenticata include user (userId, username, avatarUrl, language) e, nei negozi gestiti, orders. Chiamala al caricamento e dopo un reindirizzamento; non dedurre l’identità dalla URL.

I guasti del servizio restano errori: STOREFRONT_SESSION_ERROR non diventa una sessione disconnessa. Mostra un messaggio per riprovare. login() distingue annullamento ed errore; logout() chiude solo la sessione del negozio.

Identità e cookie

Il SDK richiede HTTPS per tutti i siti e gli endpoint, anche nello sviluppo locale. Usa un server locale HTTPS con un certificato considerato attendibile dal browser. HTTP non è mai accettato per l’autenticazione.

La password viene inserita su auth.rankapp.io, non sul sito del commerciante. Un codice monouso e PKCE S256 collegano la finestra alla richiesta iniziale. Lo scambio del codice e i token rimangono sul server; il messaggio di completamento della finestra non contiene token.

I cookie sono HttpOnly, Secure e SameSite=Lax, limitati al proprio host e privi di un Domain condiviso. La sessione centrale e quelle dei singoli negozi sono separate. logout() chiude la sessione del negozio, non automaticamente quella centrale.

Il server del negozio

Questa documentazione riguarda l’SDK 1.1.0. In un negozio compatibile, usa solo il client preconfigurato window.rankappConnect. Il server gestisce accesso, sessione e disconnessione; il client applica il trasporto firmato necessario. Non occorre configurare endpoint o adattatori nella pagina.

Provare l’anteprima

L’anteprima accetta account reali per provare accesso e disconnessione come cliente. Il permesso di aprire la bozza privata è separato: aprire l’anteprima non autentica automaticamente un acquirente. I pagamenti sono disattivati in questo ambiente.

Verifica accesso riuscito, annullamento, chiusura della finestra, ritorno mobile e nuovo accesso dopo la disconnessione. In produzione il negozio deve essere pubblicato e accessibile. L’autenticazione non conferma il pagamento: i due risultati vanno gestiti separatamente.

Preparare un’integrazione esterna

La registrazione di integrazioni per siti esterni indipendenti non è ancora disponibile. Prima dell’apertura servono registrazione dei client, approvazione degli URL di ritorno e definizione dei permessi.

Non inventare un client_id, un endpoint token o una configurazione OIDC presumendoli compatibili. Il contratto attuale riguarda i negozi supportati e il loro adattatore. Mantieni password e token fuori dal JavaScript del commerciante e verifica sempre la sessione tramite il server.