初始化开发工具包

云眼About 8 min

初始化开发工具包

本主题介绍如何在应用程序中初始化云眼灰度发布（特性标帜）AB实验 JavaScript（节点）SDK。

使用createInstance方法初始化 JavaScript（节点）开发工具包，并实例化公开 API 方法（如启用功能）的 Eyeofcloud 客户端类的实例。每个客户端对应于表示特定环境的项目状态的数据文件。

版本

SDK v3.2.1 及更高版本

描述

createInstance方法接受配置对象来配置云眼灰度发布（特性标帜）AB实验。

某些参数是可选的，因为 SDK 提供默认实现，但开发者可能希望为生产环境覆盖这些参数。例如，开发者可能希望覆盖这些内容以设置错误处理程序和记录器来捕获问题，设置事件调度程序来管理网络调用，以及设置用户配置文件服务以确保粘性分桶。

参数

下表列出了配置对象的必需属性和可选属性：

参数类型描述
数据文件 (可选)字符串表示项目的 JSON 字符串。必须至少提供一个 sdkKey 或数据文件。
sdk密钥 (可选)字符串与项目中的环境关联的键。必须至少提供一个 sdkKey 或数据文件。
事件调度程序 (可选)对象用于管理网络调用的事件调度程序。具有调度事件方法的对象。
记录器(可选)对象用于记录消息的记录器实现。具有日志方法的对象。
错误处理程序 (可选)对象用于处理错误的错误处理程序对象。具有句柄错误方法的对象
用户配置文件服务(可选)对象用户配置文件服务。具有查找和保存方法的对象。
jsonSchemaValidator (可选)对象要对数据文件执行 JSON 架构验证，请从“@eyeofcloud/eyeofcloud-sdk/dist/eyeofcloud.json_schema_validator.min.js”导入验证程序，并将其作为此初始化选项传递。跳过 JSON 架构验证可提高初始化期间的性能。
数据文件选项 (可选)对象具有用于自动数据文件管理的配置的对象。可以具有autoUpdate（布尔值）、urlTemplate（字符串）和updateInterval（数字）属性。
access_token(可选)字符串（仅限服务器端）云眼灰度发布（特性标帜）AB实验 SDK 可以使用访问令牌（与 sdk 密钥结合使用）从经过身份验证的终结点提取数据文件。在 Eyeofcloud 应用程序的设置>环境中找到数据文件访问令牌。选择安全环境，然后复制数据文件访问令牌。
默认决定选项 (可选)数组Array of EyeofcloudDecideOption enums.当使用此参数构造 Eyeofcloud 客户端时，它会设置默认的 decide 选项，这些选项将应用于在 Eyeofcloud 客户端的生命周期内进行的所有 Decide 调用。此外，还可以将选项传递给各个 Decide 方法（不会覆盖默认值）。

返回

实例化云眼灰度发布（特性标帜）AB实验类的实例。

例子

在节点 SDK 中，可以提供sdkKey和datafile其中之一或两者兼而有之。

  • 仅使用 SDK 密钥初始化时，SDK 将定期在后台轮询数据文件更改。
  • 仅使用数据文件初始化时，SDK 不会在后台轮询数据文件更改。
  • 同时使用 SDK 密钥和数据文件进行初始化时，SDK 将使用给定的数据文件，并在后台开始轮询数据文件更改。

使用开发工具包密钥实例化

在 JavaScript（节点）SDK 中，只需传递 SDK 键值即可实例化客户端。每当实验配置发生更改时，SDK 都会为你处理更改。

sdkKey作为字符串属性包含在传递给createInstance方法的选项对象中。

使用 NPM

const eyeofcloud = require('@eyeofcloud/eyeofcloud-sdk'); 
const eyeofcloudClientInstance = eyeofcloud.createInstance({   
    sdkKey: '12345', // Provide the sdkKey of your desired environment here 
});

当您提供sdkKey时，SDK 实例将下载与该sdkKey关联的数据文件。下载完成后，SDK 实例会自行更新以使用下载的数据文件。可以使用onReady方法等待数据文件下载，然后再使用实例。

使用 NPM

const eyeofcloud = require('@eyeofcloud/eyeofcloud-sdk'); 
const eyeofcloudClientInstance = eyeofcloud.createInstance({   
    sdkKey: '12345', // Provide the sdkKey of your desired environment here 
}); 

eyeofcloudClientInstance.onReady().then(() => {   
    // eyeofcloudClientInstance is ready to use, with datafile downloaded from the   
    // Eyeofcloud CDN 
});

使用数据文件实例化

要使用数据文件进行实例化，首先必须从我们的服务器获取数据文件的副本。在下面的示例中，我们演示了使用请求-承诺库获取数据文件。

使用 NPM

// Minimal client 
const eyeofcloud = require("@eyeofcloud/eyeofcloud-sdk"); 
const rp = require("request-promise");  

// replace <Your_SDK_Key> 
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

如果不传入 SDK 密钥，云眼客户端将不会自动同步较新版本的数据文件。每次检索更新的数据文件时，只需重新实例化同一客户端即可。

对于简单的应用程序，实例化客户端所需提供的只是一个数据文件，该文件指定给定环境的项目配置。对于大多数高级实现，需要根据特定要求自定义记录器或错误处理程序。

笔记

自定义数据文件管理行为

要自定义数据文件管理行为，请在传递给createInstance的options对象中提供一个datafileOptions对象属性。下表列出了支持的可自定义选项。

选择类型描述
自动更新布尔如果为 true，并在createInstance选项中提供sdkKey，则会在此实例上启用自动更新。默认值为true。
更新间隔数启用自动更新后，这将控制更新间隔。单位为毫秒。允许的最小值为 1000（1 秒）。默认值为 300000 毫秒（5 分钟）。
网址模板字符串用于构建 SDK 将从中请求数据文件的 URL 的格式字符串。%s的实例将替换为sdkKey.如果未提供，SDK 将从云眼 cdn 请求数据文件。

下面的示例演示如何自定义数据文件管理行为：

使用 NPM

const eyeofcloud = require('@eyeofcloud/eyeofcloud-sdk');  
const eyeofcloudClientInstance = eyeofcloud.createInstance({   
    sdkKey: '12345',   
    datafileOptions: {     
        autoUpdate: true,     
        updateInterval: 600000, // 10 minutes in milliseconds     
        urlTemplate: 'http://localhost:5000/datafiles/%s.json',   
    }, 
});

onReady 详细信息

使用 onReady 方法等待下载完成且 SDK 可供使用。

onReady 方法返回一个表示初始化过程的 Promise。
onReady 接受一个可选的超时参数（以毫秒为单位定义），该参数控制返回的 Promise 将保持挂起状态的最长持续时间。如果未提供超时，则默认为 30 秒。

Node

const { createInstance } = require('@Eyeofcloud/Eyeofcloud-sdk'); 
const Eyeofcloud = createInstance({   
    sdkKey: '<YOUR_SDK_KEY>', 
}); 
if (!Eyeofcloud) {   
    // there was an error creating the instance, handle error 
} else {   
    // Use EyeofcloudClient   
    Eyeofcloud.onReady().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   
    });   
    // Provide a timeout in milliseconds - promise will resolve if the datafile still is not available after the timeout   
    Eyeofcloud.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 通过包含布尔 success 属性的结果对象来实现。

当success属性为true时，实例已准备好与有效的数据文件一起使用。当 success 属性为false时，还有一个描述失败的字符串属性reason。失败可能是由超时过期、网络错误、HTTP 响应失败、数据文件验证错误或调用实例的close方法引起的。

设置回退数据文件

如果您提供了 sdkKey 和静态回退数据文件进行初始化，则 SDK 会立即使用回退数据文件（如果有效），同时下载与 sdkKey 关联的数据文件。下载完成后，如果下载的数据文件有效，并且其修订版本比回退数据文件更新，则开发工具包会更新实例以使用下载的数据文件。

Node

const { createInstance } = 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 Eyeofcloud = createInstance({   
    sdkKey: '<Your_SDK_Key>',   
    datafile, 
}); 
// EyeofcloudClientInstance can be used immediately with the given datafile, but 
// will download the latest datafile and update itself

在安全环境中使用经过身份验证的数据文件

可以使用服务器端（仅限）Eyeofcloud 功能试验 SDK（如 JavaScript （Node） SDK））从经过身份验证的终结点提取 Eyeofcloud 数据文件。

要使用经过身份验证的数据文件，请从 Eyeofcloud 应用程序的 Settings**>Environments** 下载 Eyeofcloud 环境的访问令牌。选择安全环境，然后复制 Datafile 访问令牌。下面的示例显示了如何使用访问令牌和sdk_key初始化 Eyeofcloud 客户端，使客户端能够获取经过身份验证的数据文件并完成初始化。

Node

import { createInstance } from '@Eyeofcloud/Eyeofcloud-sdk';  

// fetch the datafile from an authenticated endpoint 
const Eyeofcloud = createInstance({   
    sdkKey: '<YOUR_SDK_KEY>',   
    datafileOptions: {     
        datafileAccessToken: '<YOUR_DATAFILE_ACCESS_TOKEN>',   
    }, 
});
Last update:
Contributors: “zhangweixue”,zhangweixue