Handle identity changes and keep SDK outages from interrupting pages

README.md

@@ -42,7 +42,9 @@ export function ServerStatus() {
 `createClient(...).initialize()` 可用于非 Provider 接入，首次 track 也会自动初始化。提供 `autoInitialize={false}` 可延后 Provider 初始化；track 仍会初始化。
 请求使用 credentials: include，匿名 token 默认保存在按 API 地址和应用隔离的 localStorage，可传入 storage: null 禁用或提供自定义存储。服务器仍提供 HttpOnly Cookie；不能靠设备指纹跨站识别。
 `prepareEvent` 创建带固定 event_id / occurred_at 的可序列化请求，`sendEvent` 可重试同一请求；不要为同一次重试重新调用 track，否则会生成新 ID。本版没有自动重试、离线队列或批量发送。
-服务器错误（未注册、参数错误、凭据错误）作为 Promise rejection 返回调用方。Provider 初始化失败抛出错误，可使用 React ErrorBoundary。
+服务器错误（未注册、参数错误、凭据错误）作为 Promise rejection 返回调用方。Provider 初始化失败通过可选 onInitializationError 回调报告，不中断客户页面。
 仅 collectionKey 可配置到 SDK；不得放入 server_key、management_key 或平台 SERVICE_TOKEN。客户端事件是行为信号，不作为付款、投递结果或广告计费的可信证据。
 
 检查：`npm test` 包含 TypeScript 构建和初始化、身份恢复、幂等请求及应用隔离测试。
+
+登录/身份缝合后，可把受控登录接口返回的新匿名身份传给 client.updateIdentity，更新 SDK 缓存；退出登录调用 client.resetIdentity，签发新匿名身份并覆盖本地存储。SDK 不持有身份管理接口的服务端凭据。

src/index.ts

@@ -30,6 +30,13 @@ export function createClient({ baseUrl, appId, collectionKey, eventVersion = 1,
     catch { activeStorage = null; }
   }
   let initialization: Promise<AnonymousIdentity> | null = null;
+  function updateIdentity(identity: AnonymousIdentity): AnonymousIdentity {
+    if (!identity || ![identity.anonymous_id, identity.master_id, identity.anonymous_token].every((value) => typeof value === "string" && value.length > 0)) throw new Error("Invalid anonymous identity response");
+    const copy = Object.freeze({ anonymous_id: identity.anonymous_id, master_id: identity.master_id, anonymous_token: identity.anonymous_token });
+    try { activeStorage?.setItem(storageKey, copy.anonymous_token); } catch { /* Cookie can still persist identity. */ }
+    initialization = Promise.resolve(copy);
+    return copy;
+  }
   async function request<T>(path: string, body: unknown, headers: Record<string, string> = {}, signal?: AbortSignal): Promise<T> {
     const response = await fetch(`${url}${path}`, { method: "POST", credentials: "include", headers: { "Content-Type": "application/json", ...headers }, body: JSON.stringify(body), signal });
     if (!response.ok) {
@@ -38,19 +45,19 @@ export function createClient({ baseUrl, appId, collectionKey, eventVersion = 1,
     }
     return response.json() as Promise<T>;
   }
-  function initialize(signal?: AbortSignal): Promise<AnonymousIdentity> {
+  function initialize(signal?: AbortSignal, rotate = false): Promise<AnonymousIdentity> {
     if (!initialization) {
       let token: string | null = null;
       try { token = activeStorage?.getItem(storageKey) || null; } catch { /* Storage may be blocked. */ }
-      initialization = request<AnonymousIdentity>("/v1/identity/anonymous", token ? { anonymous_token: token } : {}, {}, signal)
-        .then((identity) => { try { activeStorage?.setItem(storageKey, identity.anonymous_token); } catch { /* Cookie can still persist identity. */ } return identity; })
+      initialization = request<AnonymousIdentity>(rotate ? "/v1/identity/anonymous?rotate=true" : "/v1/identity/anonymous", token ? { anonymous_token: token } : {}, {}, signal)
+        .then(updateIdentity)
         .catch((error: unknown) => { initialization = null; throw error; });
     }
     return initialization;
   }
   function prepareEvent(name: string, properties: Record<string, JsonValue>, options: Partial<Pick<PreparedEvent, "event_id" | "occurred_at" | "event_version" | "session_id" | "context">> = {}): PreparedEvent {
     if (!appId || !collectionKey) throw new Error("Tracking requires appId and a collectionKey");
-    return { app_id: appId, name, properties: structuredClone(properties), event_version: options.event_version ?? eventVersion, event_id: options.event_id || crypto.randomUUID(), occurred_at: options.occurred_at || new Date().toISOString(), session_id: options.session_id, context: options.context };
+    return { app_id: appId, name, properties: structuredClone(properties), event_version: options.event_version ?? eventVersion, event_id: options.event_id || crypto.randomUUID(), occurred_at: options.occurred_at || new Date().toISOString(), session_id: options.session_id, context: options.context ? structuredClone(options.context) : undefined };
   }
   async function sendEvent(event: PreparedEvent, signal?: AbortSignal): Promise<EventReceipt> {
     if (!appId || !collectionKey || event.app_id !== appId) throw new Error("Event must belong to this configured application");
@@ -58,7 +65,8 @@ export function createClient({ baseUrl, appId, collectionKey, eventVersion = 1,
     return request<EventReceipt>("/v1/events", { ...event, anonymous_token: identity.anonymous_token }, { "X-Adcloud-Key": collectionKey }, signal);
   }
   return {
-    initialize, prepareEvent, sendEvent,
+    initialize, updateIdentity, prepareEvent, sendEvent,
+    resetIdentity(signal?: AbortSignal) { initialization = null; return initialize(signal, true); },
     track(name: string, properties: Record<string, JsonValue>, options?: Parameters<typeof prepareEvent>[2], signal?: AbortSignal) {
       return sendEvent(prepareEvent(name, properties, options), signal);
     },
@@ -101,16 +109,13 @@ export function useHealth(baseUrl: string) {
 
 export type AdCloudClient = ReturnType<typeof createClient>;
 const AdCloudContext = createContext<AdCloudClient | null>(null);
-export function AdCloudProvider({ children, autoInitialize = true, ...options }: ClientOptions & { children: ReactNode; autoInitialize?: boolean }) {
+export function AdCloudProvider({ children, autoInitialize = true, onInitializationError, ...options }: ClientOptions & { children: ReactNode; autoInitialize?: boolean; onInitializationError?: (error: Error) => void }) {
   const client = useMemo(() => createClient(options), [options.baseUrl, options.appId, options.collectionKey, options.eventVersion, options.storage]);
-  const [initializationError, setInitializationError] = useState<Error | null>(null);
   useEffect(() => {
     let active = true;
-    setInitializationError(null);
-    if (autoInitialize) client.initialize().catch((error: unknown) => { if (active) setInitializationError(error instanceof Error ? error : new Error(String(error))); });
+    if (autoInitialize) client.initialize().catch((error: unknown) => { if (active) onInitializationError?.(error instanceof Error ? error : new Error(String(error))); });
     return () => { active = false; };
-  }, [client, autoInitialize]);
-  if (initializationError) throw initializationError;
+  }, [client, autoInitialize, onInitializationError]);
   return createElement(AdCloudContext.Provider, { value: client }, children);
 }
 export function useAdCloud(): AdCloudClient {

tests/client.test.mjs

@@ -47,3 +47,20 @@ test('tracking requires collection configuration and cannot send another app env
   const client = createClient({ baseUrl: 'https://api.example', appId: 'shop', collectionKey: 'collection-demo', storage: null });
   await assert.rejects(client.sendEvent({ ...client.prepareEvent('page', {}), app_id: 'other' }), /configured application/);
 });
+
+test('login identity update and logout rotation replace the cached tracking identity', async () => {
+  const requests = [];
+  const next = { ...identity, anonymous_id: 'new-anonymous', anonymous_token: 'new-signed-token' };
+  globalThis.fetch = async (url, options) => {
+    requests.push({ url, body: JSON.parse(options.body) });
+    if (url.endsWith('?rotate=true')) return response(next);
+    return response(identity);
+  };
+  const client = createClient({ baseUrl: 'https://api.example', appId: 'shop', collectionKey: 'collection-demo', storage: null });
+  client.updateIdentity(next);
+  await client.track('page', { page_id: 'home' });
+  assert.equal(requests[0].body.anonymous_token, next.anonymous_token);
+  await client.resetIdentity();
+  assert.equal(requests[1].url, 'https://api.example/v1/identity/anonymous?rotate=true');
+  assert.throws(() => client.updateIdentity({}), /Invalid anonymous identity/);
+});