一个账号，多家商店
SDK 让客户使用应用中的账号登录商店。本文档介绍兼容商店可使用的方法。
中央窗口支持登录和创建账号，目前界面只有法语与英语。文档提供十二种语言，两者的语言支持范围不同。
添加登录功能
在 兼容店铺中，window.rankappConnect 已加载并配置完成。使用三个方法即可：login()、getSession() 和 logout()，无需额外安装。下方完整示例只补充按钮和无障碍状态消息。
请在点击事件中直接调用 login()。Promise 返回 {status: "success", session}、{status: "cancelled"} 或 {status: "redirecting"}；错误会以稳定代码拒绝 Promise。移动设备或弹窗被阻止时会使用页面跳转。returnTo 必须留在您的店铺内。
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">使用 RankAPP 登录</button>
<button type="button" id="connect-logout" hidden>退出登录</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": "已取消登录。您可以重试。",
"redirecting": "正在跳转至登录页面…",
"login": "使用 RankAPP 登录",
"logout": "退出登录",
"signedOut": "你尚未登录。",
"signedIn": "已登录：",
"error": "暂时无法登录，请重试。",
"pending": "正在登录…"
};
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>显示会话状态
getSession() 从服务器读取会话：{authenticated: false} 表示未登录。登录会话包含 user（userId、username、avatarUrl、language），托管店铺还包含 orders。请在页面加载和跳转返回后调用；切勿根据 URL 参数推断用户身份。
服务故障仍然是错误：STOREFRONT_SESSION_ERROR 不会被转换为未登录状态。请显示可重试的提示。login() 区分取消与失败；logout() 仅结束店铺会话。
身份与 Cookie
SDK 要求所有网站和端点使用 HTTPS，包括本地开发。请使用带有浏览器信任证书的本地 HTTPS 服务器。身份验证绝不接受 HTTP。
密码在 auth.rankapp.io 输入，商家不收集密码。一次性授权码与 PKCE S256 将窗口绑定到初始请求。代码交换与令牌留在服务器；弹窗完成消息不包含令牌。
Cookie 使用 HttpOnly、Secure、SameSite=Lax，仅属于自己的主机，没有共享 Domain。中央与商店会话相互独立：logout() 退出当前商店，不自动结束中央会话。
商店服务器的职责
本文档适用于 SDK 1.1.0。在兼容的店铺中，只需使用预配置的 window.rankappConnect 客户端。服务器负责登录、会话和退出，客户端负责所需的签名传输。无需在页面中配置端点或适配器。
在预览中测试
预览支持真实账号，可从客户角度测试登录与退出。私人草稿访问需要另一项独立授权；打开预览不会自动登录买家。预览的支付功能保持关闭。
检查成功、取消、关闭弹窗、移动端返回与退出后重登。生产商店必须发布并可访问。登录成功不等于付款成功，支付结果应由支付流程单独确认。
准备外部网站集成
独立外部网站的注册尚未开放。公开前需建立客户端注册、验证返回地址，并明确访问权限。单独的浏览器库不能替代这些服务器端约束。
不要假设存在可用的 client_id、令牌端点或 OIDC 配置。当前范围是 兼容商店与适配器。密码与令牌不能放入商家 JavaScript，身份显示依赖服务器验证的会话，并应清晰处理取消和临时故障。