初始化开发工具包
初始化开发工具包
本主题介绍如何在应用程序中初始化云眼灰度发布（特性标帜）AB实验 JavaScript（浏览器）SDK。
使用该方法初始化 JavaScript SDK，并实例化 Eyeofcloud 客户端类的实例，该实例公开 API 方法（如 Decide 方法）。每个客户端对应于表示特定环境的项目状态的数据文件。createInstance
版本
SDK v3.2.1 及更高版本
描述
该方法接受配置对象来配置云眼灰度发布（特性标帜）AB实验。createInstance
某些参数是可选的，因为 SDK 提供默认实现，但开发者可能希望为生产环境覆盖这些参数。例如，开发者可能希望覆盖这些内容以设置错误处理程序和记录器来捕获问题，设置事件调度程序来管理网络调用，以及设置用户配置文件服务以确保粘性分桶。
参数
下表列出了配置对象的必需属性和可选属性：
参数
类型
描述
数据文件
可选
字符串
表示项目的 JSON 字符串。必须至少提供一个 sdkKey 或数据文件。
sdk密钥
可选
字符串
与项目中的环境关联的键。必须至少提供一个 sdkKey 或数据文件。
事件调度程序
可选
对象
用于管理网络调用的事件调度程序。具有调度事件方法的对象。
记录器可选
对象
用于记录消息的记录器实现。具有日志方法的对象。
错误处理程序
可选
对象
用于处理错误的错误处理程序对象。具有句柄错误方法的对象
用户配置文件服务
可选
对象
用户配置文件服务。具有查找和保存方法的对象。
jsonSchemaValidator
可选
对象
要对数据文件执行 JSON 架构验证，请从 导入验证程序，并将其作为此初始化选项传递。跳过 JSON 架构验证可提高初始化期间的性能。'@eyeofcloud/eyeofcloud-sdk/dist/eyeofcloud.json_shema_validator.min.js'
数据文件选项
可选
对象
具有用于自动数据文件管理的配置的对象。可以具有（布尔值）、（字符串）和（数字）属性。autoUpdate``urlTemplate``updateInterval
access_token_可选_
字符串
服务器端（仅限）云眼灰度发布（特性标帜）AB实验 SDK 可以使用访问令牌（带有 sdk 密钥）从经过身份验证的终结点提取数据文件。在 Eyeofcloud 应用程序的设置>环境中找到数据文件访问令牌。选择安全环境，然后复制数据文件访问令牌。
默认决定选项
可选
数组
Array of EyeofcloudDecideOption enums.当使用此参数构造 Eyeofcloud 客户端时，它会设置默认的 decide 选项，这些选项将应用于在 Eyeofcloud 客户端的生命周期内进行的所有 Decide 调用。此外，还可以将选项传递给各个 Decide 方法（不会覆盖默认值）。
有关示例代码，请参阅云眼决策选项。
返回
实例化 Eyeofcloud 类的实例。
例子
在 JavaScript SDK 中，可以提供其中之一或两者兼而有之。sdkKey``datafile
- 仅使用 SDK 密钥初始化时，将自动下载数据文件
- 仅使用数据文件初始化时，SDK 将使用给定的数据文件。
- 同时使用 SDK 密钥和数据文件进行初始化时，SDK 将使用给定的数据文件启动，然后在后台下载最新版本的数据文件。
使用数据文件实例化
首先，从我们的服务器获取数据文件的副本。然后，实例化客户端。
使用 NPM使用 HTML 脚本标记
// minimal client var eyeofcloud = require('@eyeofcloud/eyeofcloud-sdk'); const rp = require("request-promise"); // Rplace <Your_SDK_Key> to get the datafile const DATAFILE_URL = "https://cdn.eyeofcloud.com/datafiles/<Your_SDK_Key.json"; const datafile = await rp({ uri: DATAFILE_URL, json: true }); console.log("Datafile:", datafile); const eyeofcloudClient = eyeofcloud.createInstance({ datafile }); // Use eyeofcloudClient to run experiments
<!--step 1: add a <script> tag in your <head> tag: this adds the datafile on the window variable window.eyeofcloudDatafile--> <script src="https://cdn.eyeofcloud.com/datafiles/<Your_SDK_KEY>.json/tag.js"></script> <!--step 2. after the <body> tag, add a new <script> tag to instantiate an Eyeofcloud client from the datafile:--> <script> var eyeofcloudClient = window.eyeofcloudSdk.createInstance({ datafile: window.eyeofcloudDatafile, }); </script>`
如果不传入 SDK 密钥，云眼客户端将不会自动同步较新版本的数据文件。每次检索更新的数据文件时，只需重新实例化同一客户端即可。
对于简单的应用程序，实例化客户端所需提供的只是一个数据文件，该文件指定给定环境的项目配置。对于大多数高级实现，需要根据特定要求自定义记录器或错误处理程序。
使用开发工具包密钥实例化
若要使用 SDK 密钥进行实例化，请从项目的设置页获取 SDK 密钥，然后在传递给方法的选项对象中作为字符串属性传递。sdkKey``createInstance
使用 NPM
const eyeofcloud = require('@eyeofcloud/eyeofcloud-sdk'); const eyeofcloudClient = eyeofcloud.createInstance({ sdkKey: '<Your_SDK_Key>', // Provide the sdkKey of your desired environment here });
当您提供 时，SDK 实例会异步下载与该关联的数据文件。下载完成后，SDK 实例会自行更新以使用下载的数据文件。可以使用 promise 方法等待数据文件下载完毕，然后再使用实例。sdkKey``sdkKey``onReady
使用 NPM
const eyeofcloud = require('@eyeofcloud/eyeofcloud-sdk'); const eyeofcloudClient = eyeofcloud.createInstance({ sdkKey: '<Your_SDK_Key>', // Provide the sdkKey of your desired environment here }); eyeofcloudClient.onReady().then(() => { // eyeofcloudClientInstance is ready to use, with datafile downloaded from the // Eyeofcloud CDN });
对于简单的应用程序，实例化客户端所需提供的只是一个数据文件，该文件指定给定环境的项目配置。对于大多数高级实现，需要根据特定要求自定义记录器或错误处理程序。
笔记
自定义数据文件管理行为
要自定义数据文件管理行为，请在传递给 的对象中提供一个对象属性。下表列出了支持的可自定义选项。datafileOptions``options``createInstance
选择
类型
描述
自动更新
布尔
如果为 true，并在选项中提供，则会在此实例上启用自动更新。默认值为 。sdkKey``createInstance``false
更新间隔
数
启用自动更新后，这将控制更新间隔。单位为毫秒。允许的最小值为 1000（1 秒）。默认值为 300000 毫秒（5 分钟）。
网址模板
字符串
用于构建 SDK 将从中请求数据文件的 URL 的格式字符串。的实例将替换为 .如果未提供，SDK 将从云眼 cdn 请求数据文件。%s``sdkKey
下面的示例演示如何自定义数据文件管理行为：
使用 NPM
const eyeofcloud = require('@eyeofcloud/eyeofcloud-sdk'); const eyeofcloudClientInstance = eyeofcloud.createInstance({ sdkKey: '<Your_SDK_Key>', datafileOptions: { autoUpdate: true, updateInterval: 600000, // 10 minutes in milliseconds urlTemplate: 'http://localhost:5000/datafiles/%s.json', }, });
就绪详细信息
使用 onReady 方法等待下载完成且 SDK 可供使用。
onReady 方法返回一个表示初始化过程的承诺。
onReady 接受可选的超时参数（以毫秒为单位定义），该参数控制返回的 Promise 将保持挂起状态的最长持续时间。如果未提供超时，则默认为 30 秒。
使用 NPM
const eyeofcloud = require('@eyeofcloud/eyeofcloud-sdk'); let eyeofcloudClient = eyeofcloud.createInstance({ sdkKey: '<Your_SDK_Key>', }); eyeofcloudClient.onReady().then(() => { // eyeofcloudClient is ready to use, with datafile downloaded from the Eyeofcloud CDN }); // Provide a timeout in milliseconds - promise will resolve if the datafile still is not available after the timeout instance.onReady({ timeout: 5000 }).then(result => { // Returned Promise is fulfilled with a result object console.log(result.success); // true if the instance fetched a datafile and is now ready to use console.log(result.reason); // If success is false, reason contains an error message })
从 onReady 方法返回的 Promise 通过包含布尔成功属性的结果对象实现。
当属性为 时，实例已准备好与有效的数据文件一起使用。当属性为 时，还有一个描述失败的字符串属性。失败可能是由超时过期、网络错误、HTTP 响应失败、数据文件验证错误或调用实例的方法引起的。success``true``success``false``reason``close
设置回退数据文件
如果提供 sdkKey 和静态回退数据文件进行初始化，SDK 会立即使用该回退数据文件（如果该文件有效），同时下载与 sdkKey 关联的数据文件。下载完成后，如果下载的数据文件有效且修订变体比回退数据文件更新，则 SDK 会更新实例以使用下载的数据文件。
使用 NPM
const eyeofcloud = require('@eyeofcloud/eyeofcloud-sdk'); const datafile = '{"version": "4", "rollouts": [], "typedAudiences": [], "anonymizeIP": false, "projectId": "12345", "variables": [], "featureFlags": [], "experiments": [], "audiences": [], "groups": [], "attributes": [], "botFiltering": false, "accountId": "12345", "events": [], "revision": "1"}'; const eyeofcloudClient = eyeofcloud.createInstance({ sdkKey: '<Your_SDK_Key>', datafile, }); // eyeofcloudClient can be used immediately with the given datafile, but // will download the latest datafile and update itself
在安全环境中使用经过身份验证的数据文件
📘 注意
经过身份验证的数据文件处于测试阶段。如果有兴趣成为经过身份验证的数据文件的早期用户，作为测试版安全环境功能的一部分，请联系客户成功经理。
可以使用服务器端（仅限）云眼灰度发布（特性标帜）AB实验 SDK 从经过身份验证的终结点提取 Eyeofcloud 数据文件。要使用经过身份验证的数据文件，请从设置>环境中的 Eyeofcloud 应用程序下载 Eyeofcloud 环境的访问令牌。选择安全环境，然后复制_数据文件访问令牌_。下面的示例显示了如何使用访问令牌和sdk_key初始化 Eyeofcloud 客户端，使客户端能够获取经过身份验证的数据文件并完成初始化。
使用 NPM
const eyeofcloud = require('@eyeofcloud/eyeofcloud-sdk'); // fetch the datafile from an authenticated endpoint const eyeofcloudClientInstance = eyeofcloud.createInstance({ sdkKey: '<YOUR_SDK_KEY>', datafileOptions: { datafileAccessToken: '<YOUR_DATAFILE_ACCESS_TOKEN>', }, });
源文件
The source code files containing the implementation for the JavaScript SDK are at index.ts
Updated about 2 months ago
[
Install SDK
](/experimentation/v4.0.0-full-stack/docs/install-sdk-javascript)[
Client-side implementation tips
](/experimentation/v4.0.0-full-stack/docs/javascript-client-side-implementation)
Did this page help you?
Yes
No
创建用户上下文
介绍创建用户上下文方法，该方法为云眼灰度发布（特性标帜）AB实验中的标帜决策和事件创建用户上下文。
此方法的目的是创建用户并设置用户上下文一次，因此不必在每次做出标帜决策或跟踪事件时都指定用户。可以定义多个用户上下文。系统将用户上下文作为运行时对象返回，否则不会持久化。
版本
1.0.0-beta 或更高版本
描述
此调用为标帜决策和事件创建用户上下文。可以在 Eyeofcloud 客户端实例上成功调用此方法，甚至在完全配置实例之前也是如此。
参数
下表列出了必需参数和可选参数：
参数
类型
描述
(必选)用户 ID
字符串
用户的 ID。
属性
可选
Map
自定义键值字符串对的映射，指定系统用户用于受众群体定位的用户的属性。有关更多详细信息，请参阅以下部分。
受众群体属性
为用户设置自定义受众群体属性，可以使用这些属性来定位受众群体。可以将字符串、数字、布尔值和 nil 作为自定义用户属性值传递。如果要根据他们使用的应用程序变体定位访问群体，还可以传入格式为语义变体的字符串，然后在 Eyeofcloud 应用中定义受众条件。version
🚧 重要
在访问群体评估期间，如果没有为给定的访问群体条件传递有效的属性值（例如，如果在受众群体条件需要布尔值时传递字符串，或者忘记传递值），则系统会跳过该条件。发生这种情况时，SDK 日志会包含警告。
返回
返回一个 EyeofcloudUserContext 对象。有关详细信息，请参阅云眼用户上下文。
例
Dart
// option 1: create a user, then set attributes var user = await flutterSDK.createUserContext("user123"); var attributes = <String, dynamic>{}; attributes["is_logged_in"] = false; attributes["app_version"] = "1.3.2"; user!.setAttributes(attributes); // option 2: pass attributes when creating the user var attributes = <String, dynamic>{}; attributes["is_logged_in"] = false; attributes["app_version"] = "1.3.2"; var eyeofcloudUserContext = await eyeofcloudClient.createUserContext("user123", attributes);
参见
源文件
包含 Flutter SDK for Android Eyeofcloud 和 Swift 实现的语言/平台源文件.java为 EyeofcloudClient.swift。