@ 指导技术/旗子
TypeScript 的向导特征旗帜,远程配置和实验. 一个浏览器客户端, Node.js ~ 18, Next.js (服务器和边缘), Deno, Bun and React Industrial; 没有运行时间依赖性.
如果您已经使用指南 SDK(@guidelytech/react, (中文(简体) ), nextjs, (中文(简体) ), react-native, (中文(简体) ), svelte, (中文(简体) ),
sveltekit, (中文(简体) ), sdk-core 或脚本标签),旗帜构建于: guidely.flags, (中文(简体) ), useFlag(), (中文(简体) ),
flag()...有身份、页面和设备属性 直接使用此软件包
用于服务器、边缘功能和只使用旗帜的应用程序.
pnpm add @guidelytech/flags
密钥
- 公用钥匙
pk_…——您已经用作环境密钥projectId用于跟踪。 工程 无处不在,没有其他配置. - 密钥
gly_sk_…(范围)flags:read——也需要environment获取 ,当环境从公共密钥中隐藏规则时工作.
浏览器
import { createFlagsClient } from "@guidelytech/flags";
const flags = createFlagsClient({
sdkKey: "pk_prod_…",
apiUrl: "https://guidelytech.com",
attributes: { id: user.id, plan: user.plan, account: { id: org.id } },
});
await flags.ready();
if (flags.isEnabled("new-checkout")) showNewCheckout();
const color = flags.getString("checkout-button-color", "blue");
flags.subscribe(() => render()); // payload, attribute or override changes
flags.updateAttributes({ plan: "enterprise" });
最后一个有效载荷保存在 localStorage因此,返回的来访者立即获得旗帜,并下线.
节点.js / 服务器
每个进程有一个客户;对每个请求进行评价 forUser() (它永远不会改变客户端):
import { createFlagsClient } from "@guidelytech/flags";
export const flags = createFlagsClient({ sdkKey: process.env.GUIDELY_SDK_KEY!, environment: "production" });
app.get("/checkout", async (req, res) => {
await flags.ready(); // resolves once, after the first download (or failure)
const f = flags.forUser({ id: req.user.id, plan: req.user.plan });
res.render("checkout", { newCheckout: f.isEnabled("new-checkout"), limits: f.getJson("limits", {}) });
});
下一个.js
使用 @guidelytech/nextjs/server (单位:千美元)getFlags(), (中文(简体) ), getFlagsBootstrap(): 它让一个客户横跨
请求和热重装并绕过 Next.js 获取缓存 。 过 getFlagsBootstrap() 页:1
在服务器和客户端上生成相同值的浏览器提供者 .
边缘运行时间和无服务器
当缓存停止时
const flags = createFlagsClient({ sdkKey: "pk_prod_…", pollingMode: "lazy", cacheTtlSeconds: 30 });
API 密码
ready() 编号 : isReady() | 第一个负载确定( bootstrap, 网络成功或失败) 。 绝不拒绝. |
isEnabled(key, fallback = false) | 只有布尔旗:任何其他值给出 fallback。 。 。 . |
getValue(key, fallback) | 数值,或 fallback 失踪时,无效或属于JSON类型. |
getString 编号 : getNumber 编号 : getBoolean 编号 : getJson | 键入器有相同的规则. |
getDetails(key, fallback) | 数值加 reason, (中文(简体) ), ruleId, (中文(简体) ), variationId, (中文(简体) ), experiment, (中文(简体) ), usedFallback。 。 。 . |
getAll() | 每面旗帜的值(记录不曝光). |
forUser(attributes) | 获取其它属性( 合并到客户端) . |
setAttributes 编号 : updateAttributes 编号 : getAttributes | 替换/ 合并/ 读取属性 . |
setOverrides(map | null) | 当地价值(见 overrideBehaviour) (中文(简体) ). |
setOffline(bool) 编号 : refresh() | 暂停网络活动 / 现在获取 . |
getPayload() | 从服务器渲染中拖出浏览器的有效载荷(或远程结果) . |
subscribe(listener) | 更改通知; 返回 unsubscribe (与 useSyncExternalStore) (中文(简体) ). |
flush() 编号 : destroy() | 现在发送使用/ 停止计时器和流 . |
Getters 从不掷出也从不挡道:在旗下加载(或者如果向导无法到达)之前,他们返回 你的后退 以及最后的好载荷.
选项
| 选项 | 默认 | |
|---|---|---|
sdkKey (别名) projectId(中文(简体) ) | —— 说 | pk_… 或者说 gly_sk_…。 。 。 . |
apiUrl | https://guidelytech.com | 您的指南 URL . |
environment | —— 说 | 要求为 gly_sk_ 键. |
attributes | {} | 默认属性. |
pollingMode | auto | auto (每个 pollIntervalSeconds,默认为60, lazy (关于 cacheTtlSeconds, (中文(简体) ), manual (单位:千美元)refresh() 仅此而已, stream (服务器出席活动,断开时进行投票). |
payload 编号 : remoteResults | —— 说 | 靴子:即时使用(ready (一时). |
remoteEval | false | 对服务器进行评估( E)POST /flags/evaluate用于隐藏其规则的环境。 当公钥获得时自动打开 remote_evaluation_required。当属性改变时,重新评价(解析出);每个属性集的结果被缓存. |
decryptionKey | —— 说 | 对于加密的有效载荷(AES-256-GCM通过WebCrypto). |
overrides 编号 : overrideBehaviour | - / (单位:千美元) localOverRemote | localOnly (从不取来; 覆盖,然后是靴子) payload, (中文(简体) ), localOverRemote (胜诉), remoteOverLocal (仅用于远程缺失的旗帜). |
devOverrides | true | 读取 dev 覆盖 从环境变量和测试全局. |
enableUrlOverrides | false | 浏览器 QA : ?guidely_flags=new-checkout:true,checkout-button-color:"green"。 。 。 . |
stickyBucketService | —— 说 | InMemoryStickyBucketStore 编号 : LocalStorageStickyBucketStore:用户保留其实验变异. |
storage | localStorage 在浏览器中 | 任意 getItem编号 :setItem 存储、同步或同步. false 禁用 . |
trackingCallback(experiment, result) | —— 说 | 每(实验,用户,变异)一次:向你的分析仪发送曝光. |
trackExposures | true 除非 trackingCallback | 向"向导"发送曝光,获取实验结果. |
reportUsage | true | 合计评价计数,最多为每60人sendBeacon 在页面隐藏中). |
onReady, (中文(简体) ), onChange, (中文(简体) ), onFlagEvaluated, (中文(简体) ), onError | —— 说 | 钩子. |
offline, (中文(简体) ), fetch, (中文(简体) ), logger, (中文(简体) ), now | —— 说 | 开始下线; 自定义获取; null 沉默日志; 用于测试的时钟. |
createStaticFlags({ payload, attributes }) 在没有网络的有效载荷上给同样的进取器
或跟踪——框架绑定使用它来提供服务器和水合物.
Dev 覆盖( CI和测试)
不触摸应用程序的平子旗值 。 每个客户都读过一次,当它创建时:
| 来源 | 示例 |
|---|---|
GUIDELY_FLAG_OVERRIDES | new-checkout:true,limit:5,theme:"dark" 或者说 {"new-checkout":true} |
GUIDELY_FLAG_OVERRIDES_FILE | 路径到持有相同文本的文件( JSON 对象或一个) key:value (每行) |
GUIDELY_FLAG_OVERRIDE_BEHAVIOUR | localOnly ——无网络,无缓存有效载荷:隐形试验 |
globalThis.__GUIDELY_FLAG_OVERRIDES__ 编号 : __GUIDELY_FLAG_OVERRIDE_BEHAVIOUR__ | 对象或同文本,由页面中的测试导师设置 |
GUIDELY_FLAG_OVERRIDES='new-checkout:true' GUIDELY_FLAG_OVERRIDE_BEHAVIOUR=localOnly pnpm test
GUIDELY_FLAG_OVERRIDES_FILE=ci/flags.json pnpm test
样本 ci/flags.json (键为旗下键;给每个值为旗下类型,因为
类型错误或 null 使受难者返回倒计时:
{
"new-checkout": true,
"checkout-button-color": "green",
"max-cart-items": 25,
"pricing-page": { "layout": "grid", "plans": ["starter", "pro", "team"] },
"holiday-banner": null
}
// Playwright: set before the page's scripts run.
await page.addInitScript(() => {
(window as any).__GUIDELY_FLAG_OVERRIDES__ = { "new-checkout": true };
});
// Cypress: cy.visit("/", { onBeforeLoad: (win) => { win.__GUIDELY_FLAG_OVERRIDES__ = { "new-checkout": true }; } });
每旗,后取胜: overrides 编号 : setOverrides() * 文件 · 可变 · 全球 · ?guidely_flags=。 。 。 .
setOverrides() 仅取代第一个。 价值有道理 OVERRIDE客户端
日志一个列出使用中的源的警告, 因此生产中设置的变量显示于
日志; 格式错误的源到 onError 并被置之不理. devOverrides: false 关掉它.
使用服务器渲染, 既设置:服务器代码的变量, 也设置浏览器的全局性变量
(反应和Svelte服务器使读取靴子载荷,该载荷没有覆盖).
parseOverrides(text) 用于在其它地方读取相同的格式.
国 际
# In CI on your main branch: upload where each flag is used in code (shown on the flag's page).
npx guidely-flags code-refs --key "$GUIDELY_API_KEY" --environment production --repo acme/web
# Debug an evaluation.
npx guidely-flags evaluate --key pk_prod_… --flag new-checkout --attributes '{"id":"u1","plan":"pro"}'
code-refs 需要一个 gly_sk_ 键为 flags:read 财务报告和审定财务报表 flags:code-refs它扫描来自
git ls-files (或散步跳过) node_modules, (中文(简体) ), dist, (中文(简体) ), build, (中文(简体) ), vendor...) 旗下 1 MB
键作为引用的字符串文字写入,并上传 { repo, branch, commit, refs }部门
承诺默认为当前 git 退出( 或 GITHUB_REF_NAME 编号 : GITHUB_SHA) (中文(简体) ). --dry-run
打印参考文献. guidely-flags --help 列出每个选项.
评价语义在 文件/地貌-旗帜-规格.md。 。 。 .