初始化开发工具包

云眼About 7 min

初始化开发工具包

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

使用createInstance方法初始化 JavaScript SDK，并实例化 Eyeofcloud 客户端类的实例，该实例公开 API 方法（如 Decide 方法）。每个客户端对应于表示特定环境的项目状态的数据文件。

版本

SDK v3.2.1 及更高版本

描述

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

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

参数

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

参数类型描述
数据文件 (可选)字符串表示项目的 JSON 字符串。必须至少提供一个 sdkKey 或数据文件。
sdk密钥 (可选)字符串与项目中的环境关联的键。必须至少提供一个 sdkKey 或数据文件。
事件调度程序 (可选)对象用于管理网络调用的事件调度程序。具有调度事件方法的对象。
记录器(可选)对象用于记录消息的记录器实现。具有日志方法的对象。
错误处理程序 (可选)对象用于处理错误的错误处理程序对象。具有句柄错误方法的对象。
用户配置文件服务 （可选）对象用户配置文件服务。具有查找和保存方法的对象。
jsonSchemaValidator （可选）对象要对数据文件执行 JSON 架构验证，请从'@eyeofcloud/eyeofcloud-sdk/dist/eyeofcloud.json_shema_validator.min.js'导入验证程序，并将其作为此初始化选项传递。跳过 JSON 架构验证可提高初始化期间的性能。
数据文件选项 （可选）对象具有用于自动数据文件管理的配置的对象。可以具有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

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

使用 HTML 脚本标记

<!--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 
    });

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

使用 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 
    });

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

笔记

自定义数据文件管理行为

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

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

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

使用 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 通过包含布尔成功属性的结果对象实现。

当属性success为true时，实例已准备好与有效的数据文件一起使用。当success属性为false时，还有一个描述失败的字符串属性reason。失败可能是由超时过期、网络错误、HTTP 响应失败、数据文件验证错误或调用实例的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
Last update:
Contributors: “zhangweixue”,zhangweixue