ZZD public AI gateway · zzd_public_ai_gateway_v3
Resource: 07 · Space SDK / 应用接入包
Canonical map: https://zzd.show/docs/ai/map.json
Full handbook: https://zzd.show/llms-full.txt
REST capabilities: https://zzd.show/api/v1/capabilities/

# ZZD Space SDK

Space SDK is the stable client boundary between a Show and ZZD's
identity, app-scoped user data, creator information, and device
capability consent. A Show should call this SDK instead of building
its own login form, copying credentials, or inventing app-specific
platform routes.

Every normal blank Show receives the versioned UMD global
`window.ZZDSpaceSDK` (also available as the backwards-compatible
`window.AppRuntime`). ES modules may import the module URL advertised
by `window.seen.runtime.sdk.module_url`. Check the advertised version
and feature namespace rather than inspecting platform internals.

## Stable namespaces

```js
const zzd = window.ZZDSpaceSDK;

// Login is a trusted-main-domain handoff. No password, phone code,
// WeChat token, cookie, or platform secret enters Show code.
zzd.auth.open();
zzd.auth.login({ returnTo: location.href });
const identity = await zzd.getIdentity();

// App data is isolated by the bound backend app, current identity,
// and namespace. Guest state is promoted when login succeeds.
const current = await zzd.data.get("progress");
await zzd.data.set("progress", { level: 4 }, {
  expectedRevision: current.revision
});
await zzd.data.remove("progress");

// Creator data is public and read-only on the code origin. Follow,
// subscribe, purchase, and account mutations occur on zzd.show.
const creator = zzd.creator.get();
zzd.creator.open();

// Device motion is opt-in. The platform presents consent when the
// browser requires a user gesture and never stores raw sensor data.
const granted = await zzd.motion.request({
  title: "开启体感？",
  message: "倾斜设备即可操控。"
});
if (granted) {
  const stop = zzd.motion.subscribe((event) => {
    // consume beta/gamma in this Show only
  });
}
```

The supported public methods are:

- `configure({runtime})`, `environment()`, `identity()`,
  `getIdentity()`, and `subscribeIdentity(listener)`;
- `auth.login/open/close/logout/identity/subscribe`;
- `data.get/set/remove/reset`;
- `creator.get/open/close`;
- `motion.supported/permission/request/subscribe`;
- optional standard account and creator trigger mounting.

`data.reset` is destructive and requires the confirmation phrase
supplied by the app contract. Show UI must ask the user clearly
before calling it. Do not silently reset or merge data.

## Identity and login lifecycle

An unauthenticated visitor receives an opaque, expiring guest
identity when the bound app needs state. The Show may work
immediately without forcing login. The platform login surface adapts
to the environment: WeChat clients receive a direct WeChat action;
other clients receive the available trusted-domain choices. After
login, ZZD promotes compatible guest data into the account-scoped
app state. Identity conflicts stop automatic merging and require an
explicit account flow.

The code origin is an untrusted execution boundary. It may display a
platform-provided login or creator trigger, but credentials and
sensitive account fields are entered only on the exact canonical
general origin. Return navigation uses a one-time, expiring handoff
and a validated continuation URL. Show authors must not reproduce,
obscure, iframe, or intercept that trusted login surface.

## Creator boundary

`creator.get()` returns only public presentation data: creator ID,
display name, avatar, biography, public counts, selected public
works, and canonical profile URL. On `code.zzd.show` this is strictly
read-only. Follow, subscribe, paid-content, and creator-management
actions belong to the canonical creator page on `zzd.show`, where
session, CSRF, ownership, and product rules are enforced.

## Validation

Verify guest and signed-in states, login return to the exact Show,
guest-state promotion, namespace isolation, reset confirmation,
creator read-only behavior on the code host, creator mutations only
on the canonical host, WeChat and ordinary-browser login variants,
motion consent/deny/retry, orientation changes, touch fallback, and
environments without motion support. Never treat sensor availability
or a logged-in browser as authorization for an unrelated app.