跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

TypeScript 客户端 SDK

最后更新 查看 MarkdownAgent 设置

FlagshipClientProvider 为浏览器应用程序实现了 OpenFeature web 提供商接口。它在初始化时预取声明的一组标志值,并从内存缓存中同步解析评估。

这使得提供商适用于需要同步访问标志值的客户端渲染。

prefetchFlags

prefetchFlags 是一个必需的标志键数组,提供商在初始化和每次上下文更改时会获取这些标志。只有此数组中列出的标志才能进行同步评估——未包含的任何标志键在解析时都会返回 FLAG_NOT_FOUND 错误。

获取行为:

  • 在初始化时 —— prefetchFlags 中的所有标志并行获取并存储在内存缓存中。一旦所有获取完成(单个失败是非致命的),提供商将转换为 READY。
  • 在上下文更改时 —— 缓存失效,并且针对新上下文重新获取所有标志。这是由 OpenFeature web SDK 使用的 静态上下文范式 (static context paradigm) ↗ 要求的,在该范式中,上下文全局设置,并且期望提供商在上下文更改时重新评估。
  • 在解析时 —— 评估从缓存同步提供。在 getBooleanValue、getStringValue 等期间不发出任何网络请求。

设置

以下示例使用一组预取标志初始化提供商,并在浏览器应用程序中对其进行评估。

import { OpenFeature } from "@openfeature/web-sdk";
import { FlagshipClientProvider } from "@cloudflare/flagship/web";

await OpenFeature.setProviderAndWait(
	new FlagshipClientProvider({
		appId: "<APP_ID>",
		accountId: "<ACCOUNT_ID>",
		authToken: "<API_TOKEN>",
		prefetchFlags: ["promo-banner", "dark-mode", "max-uploads"],
	}),
);

// Set evaluation context globally. The provider re-fetches all prefetchFlags
// whenever the context changes.
await OpenFeature.setContext({ targetingKey: "user-42", plan: "enterprise" });

const client = OpenFeature.getClient();

// Synchronous — served from the in-memory cache.
const showBanner = client.getBooleanValue("promo-banner", false);

if (showBanner) {
	document.getElementById("banner").style.display = "block";
}
import { OpenFeature } from "@openfeature/web-sdk";
import { FlagshipClientProvider } from "@cloudflare/flagship/web";

await OpenFeature.setProviderAndWait(
    new FlagshipClientProvider({
        appId: "<APP_ID>",
        accountId: "<ACCOUNT_ID>",
        authToken: "<API_TOKEN>",
        prefetchFlags: ["promo-banner", "dark-mode", "max-uploads"],
    }),
);

// Set evaluation context globally. The provider re-fetches all prefetchFlags
// whenever the context changes.
await OpenFeature.setContext({ targetingKey: "user-42", plan: "enterprise" });

const client = OpenFeature.getClient();

// Synchronous — served from the in-memory cache.
const showBanner = client.getBooleanValue("promo-banner", false);

if (showBanner) {
    document.getElementById("banner").style.display = "block";
}

配置选项

选项 类型 必需 描述
appId string 是 Cloudflare 仪表板中的 Flagship 应用 ID。
accountId string 是 您的 Cloudflare 账户 ID。
authToken string 是 具有 Flagship Evaluate 或 Flagship App Evaluate 权限的 Cloudflare API 令牌。
fetchOptions RequestInit 否 应用于 HTTP 请求的自定义 fetch 选项。
timeout number 否 请求超时时间,单位为毫秒。默认为 5000。
retries number 否 发生临时错误时的重试次数。默认为 1,最高上限为 10。
retryDelay number 否 重试之间的延迟时间,单位为毫秒。默认为 1000,最高上限为 30000。
prefetchFlags string[] 是 在初始化和每次上下文更改时要获取的标志键。不在此列表中的标志在评估时返回 FLAG_NOT_FOUND。

评估上下文

从 0.6.0 版开始,客户端提供程序接受字符串、有限数字、布尔值、null、嵌套对象和数组。它会将有效的 Date 值(包括对象和数组中的值)规范化为 ISO 8601 字符串。

初始化和上下文变更期间,提供程序会使用带 JSON 正文的 POST 发送结构化上下文。若上下文仅包含字符串、数字、布尔值或日期,则会使用 GET 查询参数。看起来像 JSON 的字符串仍为字符串,不会创建嵌套上下文。

何时使用客户端提供商

在浏览器应用程序、单页应用 (SPA) 或任何客户端 JavaScript 环境中使用客户端提供商。

评估是同步的,因此它们不会阻塞渲染。标志值在初始化期间获取一次,并在评估上下文更改时重新获取。要强制刷新,请通过 OpenFeature.setContext(...) 更新上下文。

这篇文档对您有帮助吗?