Connect documentation

One account across storefronts

The SDK lets customers sign in to a storefront with the account they use in the app. This documentation describes the methods available on supported storefronts.

The central dialog supports sign-in and account creation. Its interface currently supports French and English, although this documentation is available in twelve languages.

Add sign-in

On a supported storefront, window.rankappConnect is already loaded and configured. Use three methods: login(), getSession() and logout(). No additional installation is needed. The complete example below only adds buttons and accessible messages.

Call login() directly from a click. Its promise resolves with {status: "success", session}, {status: "cancelled"} or {status: "redirecting"}. Errors reject with a stable code. Mobile devices and blocked popups continue through a redirect. returnTo must stay on your storefront.

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">Sign in with RankAPP</button>
<button type="button" id="connect-logout" hidden>Sign out</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": "Sign-in cancelled. You can try again.",
  "redirecting": "Redirecting to sign-in…",
  "login": "Sign in with RankAPP",
  "logout": "Sign out",
  "signedOut": "You are signed out.",
  "signedIn": "Signed in: ",
  "error": "Sign-in is unavailable. Try again.",
  "pending": "Signing in…"
};
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>

Display the session

getSession() reads the server: {authenticated: false} means signed out. An authenticated session exposes user (userId, username, avatarUrl, language) and, on managed storefronts, orders. Call it on page load and after redirects; never infer identity from URL parameters.

Service failures remain errors: STOREFRONT_SESSION_ERROR does not become a signed-out session. Display a retry message. login() distinguishes cancellation from failure; logout() closes only the storefront session.

Identity and cookies

The SDK requires HTTPS for all sites and endpoints, including local development. Use a local HTTPS server with a certificate trusted by your browser. HTTP is never accepted for authentication.

Customers enter their password on auth.rankapp.io, not on the merchant’s website. A single-use code and PKCE S256 bind the dialog to the initial request. The code exchange and tokens stay on the server; the popup’s completion message contains no token.

Session cookies use HttpOnly, Secure and SameSite=Lax. Each cookie belongs to its own host, without a shared Domain attribute. The central identity session and individual storefront sessions are separate. Calling logout() signs out of the storefront; it does not automatically end the central session.

The storefront server

This documentation covers SDK 1.1.0. On a compatible storefront, use only the preconfigured window.rankappConnect client. The server handles sign-in, sessions and sign-out; the supplied client applies the required signed transport. You do not need to configure endpoints or adapters in your page.

Test in preview

Preview supports real accounts so you can test sign-in and sign-out as a customer. Private access to the draft uses a separate permission: opening a preview does not automatically sign in a buyer. Payments are disabled there.

Check successful sign-in, cancellation, closing the popup, mobile redirects and signing in again after sign-out. A production storefront must be published and accessible. Authentication alone never confirms a payment, so keep the payment result separate from the sign-in state.

Prepare an external integration

Independent external websites cannot register integrations yet. Opening that service requires client registration, approved return URLs and explicit access rights before public availability.

Do not invent a compatible client_id, token endpoint or OIDC configuration. The supported contract currently belongs to supported storefronts and their supplied adapter. Keep passwords and tokens out of merchant JavaScript, rely on server-checked sessions, and design customer feedback for cancellation and temporary failures as well as successful sign-in.