Skip to main content

小程序插件使用指南

云眼November 28, 2024About 32 min

小程序插件使用指南

本主题概述了微信、支付宝等小程序插件的链接

本参考指南介绍如何在小程序中使用插件

安装插件

  1. 微信小程序

将此代码添加到微信小程序 app.json文件中

  "plugins": {
    // 自定义插件名称，这里以abtest为例子
    "abtest": {
      "version": "Your plugin version",
      "provider": "Your plugin AppId"
    }
  }
  1. 支付宝小程序

将此代码添加到支付宝小程序 app.json文件中

  "plugins": {
    // 自定义插件名称，这里以abtest为例子
    "abtest": {
      "provider": "Your plugin AppId",
      "version": "*" //会自动识别插件的最新版本
    }
  }
  1. 京东小程序

将此代码添加到京东小程序 app.js文件中

  "plugins": {
    // 自定义插件名称，这里以abtest为例子
    "abtest": {
      "provider": "Your plugin AppId",
      "version": "Your plugin version"
    }
  }
  1. 抖音小程序

抖音小程序目前无相关插件使用

使用插件

  1. 微信小程序

在需要使用插件js接口的地方调用以下代码

// 在app.json文件中配置之后，通过插件名引入，此处以abtest为例
const plugin = requirePlugin('abtest');
  1. 支付宝小程序

在需要使用插件js接口的地方调用以下代码

// 在app.json文件中配置之后，通过插件名引入，此处以abtest为例
const plugin = requirePlugin('abtest');
  1. 京东小程序

在需要使用插件js接口的地方调用以下代码

// 在app.json文件中配置之后，通过插件名引入，此处以abtest为例
const plugin = requirePlugin('abtest');
  1. 抖音小程序

因为抖音小程序目前没有开发相关插件，可以通过引入eyeofcloud.browser.umd.min.js文件来调用js接口

eyeofcloud.browser.umd.min.js下载

在需要使用js接口的地方调用以下代码

//如果引入之后调用不了相关接口可以尝试将文件名字更改短一些(如eyeofcloud.js)再次尝试
const plugin = require('eyeofcloud.browser.umd.min.js')

示例用法

此示例演示了以下每个概念的基本用法，各个小程序之间通用：

  1. 使用decide方法计算具有键poduct_sort的标帜。作为副作用， Decision函数还会向Eyeofcloud发送决策事件，以记录当前用户已暴露于实验

  2. 有条件的执行特征代码，有以下几种选择：

  • 获取标帜启用状态，然后检查标帜上名为sort_method 的配置变量。SDK 会评估标帜规则，并确定用户所处的标帜变体，从而确定他们应该看到的排序方法变量。
  • 获取标帜变体，然后运行“控制”或“处理”代码。
  1. 使用事件跟踪跟踪名为purchased 的事件。此转化事件衡量实验的影响。使用 Track Event 方法，购买会自动归因到我们做出决定的正在运行的 A/B 测试，SDK 会通过可自定义的事件调度程序向 Eyeofcloud 发送网络请求，以便我们可以将其计入结果页面。

以下为调用插件js接口相关示例代码

var eyeofcloudClient = plugin.createInstance({sdk: "Your sdk_Key"});
eyeofcloudClient.onReady().then(() => {
    var attriutes = {city: "南京"}
    var user = eyeofloudClient.createUserContext('user123', attributes);
    var decision = user.decide('product_sort');
    var variationKey = decision['variationKey']
    if(variationKey == null) {
        consle.log('decision error:', decision['reasons']);
    }
        var enabled = decision['enabled'];    
    
    if (enabled) {     
        var sortMethod = decision.variables['sort_method'];     // execute code for sort method value   
        }    
    
    if (variationKey === 'control') {     
        // Execute code for control variation   
        } 
    else if (variationKey === 'treatment') {     
        // Execute code for treatment variation   
        }       // Track an event   user.trackEvent('purchased'); 
})

创建用户上下文

创建一个用户可以为其做出标帜决策和跟踪事件。用户上下文作为运行时对象返回，否则不会保留该对象。此方法的目的是设置一次用户上下文，因此不必在每次做出标帜决策或跟踪事件时都指定用户。可以定义多个用户上下文。

描述

此调用为标帜决策和事件创建用户上下文。可以在 Eyeofcloud 客户端实例上成功调用此方法，即使该实例尚未完全配置也是如此。

参数

下表列出了必需参数和可选参数：

参数类型描述
(必选)用户 ID字符串用户ID。
属性 (可选)Map自定义键值字符串对的映射，用于指定用于受众群体定位的用户属性。有关更多详细信息，请参阅以下部分。

受众群体属性

==================================

可以为用户设置自定义受众群体属性，然后可以使用这些属性来定位受众群体。可以将字符串、数字、布尔值和 null 作为自定义用户属性值传递。如果要根据访问群体使用的应用程序变体来定位访问群体，还可以传入格式为语义变体的字符串，然后在 Eyeofcloud 应用中定义version受众条件。

🚧 重要

请注意，在受众群体评估期间，如果没有为给定的受众群体条件传递有效的属性值（例如，如果在受众群体条件需要布尔值时传递字符串，或者您只是忘记传递值），则会跳过该条件。发生这种情况时，SDK 日志将包含警告。

返回

返回一个 EyeofcloudUserContext 对象。有关详细信息，请参阅云眼用户上下文。

分桶方法decide

决定

描述

返回用户的标帜键的决策结果。决策结果在 EyeofcloudDecision 对象中返回，并包含传递标帜规则所需的所有数据。

Decide 是 UserContext 对象的一种方法。有关详细信息，请参阅 EyeofcloudUserContext。

有关返回的决策对象的详细信息，请参阅 EyeofcloudDecision 。

参数

下表描述了 Decide 方法的参数：

参数类型描述
flagKey字符串特性标帜(Feature Flag)的键
选项（可选）数组Array of EyeofcloudDecideOption enums.请参阅下表。

云眼分桶结果 EyeofcloudDecision选项

下面的示例演示如何在任何 Decide 方法上单独设置选项，或在实例化 Eyeofcloud 客户端时将其设置为全局默认值。请参见初始化软件开发工具包。

下表显示了 EyeofcloudDecideOption 的详细信息。

EyeofcloudDecideOption 枚举如果设置：
EyeofcloudDecideOption.DISABLE_DECISION_EVENT防止访问者在仍收到变体时触发展示，这将禁止在 Eyeofcloud 应用程序的“结果”页面上显示 Decide 方法的结果。
此设置可能是 Decision Event Dispatched 枚举在返回的EyeofcloudDecision对象或 DECIDE 通知侦听器有效负载。
EyeofcloudDecideOption.ENABLED_FLAGS_ONLY仅返回已启用标志的决策。这仅适用于确定多个标志的方法（如 Decide All 方法）的有效选项。如果此选项无效，则忽略该选项。如果未设置此选项，则无论是否启用该标志，SDK 都会返回所有决策。
EyeofcloudDecideOption.IGNORE_USER_PROFILE_SERVICE设置后，SDK 会绕过用户配置文件服务 （UPS）（查找和保存）进行决策。 如果未设置此选项，UPS 将覆盖受众定位、流量分配和实验互斥组。
EyeofcloudDecideOption.INCLUDE_REASONS在 EyeofcloudDecision 对象的 Reasons 字段中返回日志消息。请注意，与信息或调试消息不同，无论此设置如何，始终返回严重错误消息。
EyeofcloudDecideOption.EXCLUDE_VARIABLES从决策结果中排除标志变量值。使用此选项可通过跳过大型 JSON 变量来最大程度地减少返回的决策。

返回

Decide 方法返回一个 EyeofcloudDecision 对象。有关详细信息，请参阅 EyeofcloudDecision。

如果该方法遇到严重错误（SDK 未就绪、标志键无效等），则它将返回一个包含空变体键字段的决策，并使用错误消息填充“原因”字段（无论“包含原因”选项如何）。

全部决定

返回用户的所有活动（未存档）标志的决策。

有关详细信息，请参阅 EyeofcloudDecision。

描述

使用 Decide All 方法可返回用户的标志决策映射。

参数

下表描述了 Decide All 方法的参数：

参数类型描述
options（可选）数组EyeofcloudDecideOption 枚举的数组。

返回

Decide All 方法返回 EyeofcloudDecisions 的映射。有关详细信息，请参阅 EyeofcloudDecision。

如果该方法的所有标志都失败（例如，SDK 未就绪或用户上下文无效），则返回空映射。如果该方法检测到特定标志的错误，则会在该标志的决策的“原因”字段中返回错误消息。

确定秘钥

Decide For Keys 方法返回由标志键映射的决策结果对象。

描述

获取标志键数组的标志决策图。

参数

下表描述了 Decide For Keys 方法的参数：

参数类型描述
Key数组字符串标志键的数组。
options（可选）数组EyeofcloudDecideOption 枚举的数组。

返回

返回 EyeofcloudDecisions 的映射。有关详细信息，请参阅 EyeofcloudDecision。

如果该方法的所有标志都失败（例如，SDK 未就绪或用户上下文无效），则返回空映射。如果该方法检测到特定标志的错误，则会在该标志的决策的“原因”字段中返回错误消息。

跟踪SDK事件

描述

使用此方法可跨用户的多个标帜规则跟踪事件。每次转化（即用户操作）只应进行一次跟踪调用，即使许多规则都在衡量转化也是如此。

在用户上调用跟踪事件trackEvent方法。有关用户对象的更多信息，请参阅云眼用户上下文。

传递给跟踪事件的属性仅用于结果细分。

参数

下表列出了跟踪事件trackEvent方法的必需参数和可选参数。

参数类型描述
(必选)事件键（Key）字符串要跟踪的事件的键。此键必须与在 Eyeofcloud 应用程序中创建事件时提供的事件键匹配。
事件标签 （可选）Map指定此特定事件的标签名称及其相应标签值的键值对映射。值可以是字符串、数字或布尔值。这些可用于跟踪数字指标，允许跟踪转化以外的操作，例如：收入、加载时间或总价值。请参阅有关保留标签键的详细信息。

返回

此方法将转化数据发送到云眼特性标帜(Feature Flag)AB实验。它不提供返回值。

副作用

下表列出了使用此方法可能触发的其他 Eyeofcloud 功能。

功能性描述
转换调用此方法会记录转换，并将其归因于用户看到的变体。 可以针对此转化事件创建指标，并在跟踪转化后向实验添加指标。 有关更多信息，请参阅有关事件：跟踪点击、网页浏览和其他访问者操作的支持文档。
重要！
- 当指定的事件键无效时，此方法不会跟踪事件。
- 更改正在运行的实验的流量分配会影响转化的记录方式以及将变体归因于用户的方式。
通知侦听器访问此方法会触发对通知侦听器的调用。
重要!
当指定的事件键无效时，该方法不会调用TRACK通知侦听器。

EyeofcloudConfig

概述

全栈 SDK 打开一组定义明确的公共 API，隐藏所有实现详细信息。但是，某些客户端可能需要访问数据文件中的项目配置数据。

在本文档中，我们扩展了公共 API 以定义数据模型和访问方法，客户端可以使用这些模型和方法访问项目配置数据。

EyeofcloudConfig API

公共配置数据模型（EyeofcloudConfig）在下面定义为静态Eyeofcloud项目数据的结构化格式。

获取云眼配置

EyeofcloudConfig可以通过以下公共API调用从EyeofcloudClient（顶级）访问：

var config = eyeofcloudClient.getEyeofcloudConfig();

getEyeofcloudConfig 返回一个实例EyeofcloudConfig，其中包括:

  • 环境键
  • 开发工具包密钥
  • 数据文件修订号
  • 按其键值映射的所有实验
  • 所有属性
  • 所有受众
  • 所有活动
  • 按其键值映射的特性标帜(Feature Flag)
  • 检索项目配置（数据文件）的函数

📘 注意

当 SDK 数据文件更新时（客户端可以为EYEOFCLOUD_CONFIG_UPDATE添加通知侦听器以获取通知），客户端应调用该方法以获取更新的 EyeofcloudConfig 数据。请参阅以下示例。

获取数据文件

要在多个 SDK 实例之间共享同一数据文件（例如，在客户端/服务器方案中），可以在实例之间传递配置（数据文件）的 JSON 字符串表示形式。若要获取数据文件，请使用EyeofcloudConfig对象的getDatafile方法。有关更多信息，请参阅与多个 SDK 实现共享数据文件。

EyeofcloudDecision

对象模型

下面显示了云眼决策对象的接口。

interface EyeofcloudDecision {   
    variationKey: string | null;   
    enabled: boolean;   
    variables: { [variableKey: string]: unknown };   
    ruleKey: string | null;   
    flagKey: string;   
    userContext: EyeofcloudUserContext;   
    reasons: string[]; 
}

下表描述了云眼决策对象的字段：

Field类型描述
启用布尔该标帜是否已启用。 云眼特性标帜(Feature Flag)AB实验从不为此字段返回 null;当由于错误而无法做出决定时，它返回 false。
变量Map所有标帜变量的键值对。当没有为标帜定义变量或 SDK 无法获取变量时，此字段将返回空映射。当 SDK 无法获取决策的变量时，“原因”字段将包含错误消息，而不考虑“包括原因”选项。
变体键字符串（可为空）当 SDK 无法做出决定时，此字段将返回 null，并且“原因”字段包含日志消息（如果设置了“包括原因”选项）。 在旧项目中，存在一种边缘情况：1. 原因字段中没有消息和 2.变体键字段中的空值表示找不到变体（例如，因为标帜是转出的一部分）。
规则键字符串（可为空）用户为此决策存储到的标帜规则的键。 当有效的规则键不可用时，将返回实验键的副本。 如果未找到有效的规则键和实验键，则返回 null。
旗键字符串做出决定的标帜的密钥。
用户上下文云眼用户上下文与对 Decide 方法的调用关联的用户。
原因数组按时间顺序排列的相关错误和日志消息的数组。云眼特性标帜(Feature Flag)AB实验在此字段中返回消息：
- 在做出决策时检测到错误时。
- 当在决定选项中启用决策原因时
- 没有消息时为空数组。
有关详细信息，请参阅以下部分。

原因

返回的决策对象在“原因”字段中包含错误和日志消息。

错误原因

为了与其他决策结果保持一致，云眼特性标帜(Feature Flag)AB实验返回具有空字段的决策，而不是引发错误或异常。

严重错误始终包含在返回的决策对象的原因字段中，而不考虑在 Decide 方法上设置的“包括原因”选项。

错误可能的原因
零variationKey- 云眼特性标帜(Feature Flag)AB实验 SDK 尚未正确配置
- 用户上下文无效
- 找不到键的标帜
空 variables- EyeofcloudJSON 的变量无效
- 键的变量值无效或类型错误

日志原因

Eyeofcloud特性标帜(Feature Flag)按日志记录的顺序在返回的EyeofcloudDecision对象的Reasons字段中收集日志消息。

如果在Decide方法上设置了“包括原因”选项，则以下类型的日志消息仅包含在“原因”字段中：

  • 与根据受众或属性对用户进行分桶相关的日志消息。
  • 根据流量百分比记录与对用户进行分桶相关的消息。

UserProfileService

使用用户配置文件服务保留有关用户的信息，并确保变体分配具有粘性。例如，如果正在处理后端网站，则可以创建一个从 Redis 或 Memcached 存储读取和保存用户配置文件的实现。

在 JavaScript Node SDK 中，没有默认实现。实施用户配置文件服务是可选的，仅当希望保持变体分配的粘性时，即使实验条件在运行过程中发生了变化（例如，受众群体、属性、变体暂停和流量分配），才需要实现该服务。否则，JavaScript Node SDK 是无状态的，并且依赖于确定性分桶来返回一致的分配。

如果用户配置文件服务未按预期对用户进行分桶，请检查其他特性标帜(Feature Flag)是否覆盖了分桶。有关更多信息，请参阅 分桶的工作原理。

实现服务

请参阅下面的代码示例以提供您自己的用户配置文件服务。它应公开两个具有以下签名的函数：

  • lookup ：获取用户 ID 字符串并返回与以下架构匹配的用户配置文件。
  • save ：获取用户配置文件并保留它。
    如果要将用户配置文件服务纯粹用于跟踪目的而不是粘性分桶，则只能实现save方法（始终从lookup返回nil）。

用户配置文件服务的界面如下所示：

// Sample user profile service implementation 
const userProfileService = {   
    lookup: userId => {     
        // Perform user profile lookup   
    },   
    save: userProfileMap => {     
        // Persist user profile   
    },
};  

var eyeofcloudClient = eyeofcloud.createInstance({   datafile,   userProfileService, });

Java SDK 使用你提供的 User Profile Service 在保存试验分配的情况下替代默认分桶行为。

在实现自己的 User Profile Service 时，建议在初始化时将用户配置文件加载到 User Profile Service 中，并避免对查找函数执行成本高昂的阻塞查找，以最大程度地减少合并服务对性能的影响。

在多服务器或无状态环境中实现时，我们建议将此接口与 Cassandra 或 Redis 等后端一起使用。您可以通过配置这些服务来决定要将粘性存储桶保留多长时间。

配置事件分派器

云眼特性标帜(Feature Flag)AB实验 SDK 为每个触发的决策事件或转化事件发出 HTTP 请求。每个 SDK 都有一个内置的事件调度程序来处理这些事件，但我们建议根据环境的具体情况重写它。

节点开发工具包具有开箱即用的异步调度程序。建议自定义在生产中使用的事件调度程序，以确保以可扩展到应用程序处理的卷的方式对事件进行排队和发送。通过自定义事件调度程序，可以有效地处理大型事件量。或者在请求失败时实现重试逻辑。可以从头开始构建调度程序，也可以从提供的调度程序开始。

这些示例显示，要自定义事件调度程序，请使用事件调度程序实例初始化 Eyeofcloud 客户端（或管理器）

// Client with defaultEventDispatcher 
const defaultEventDispatcher = require("@eyeofcloud/eyeofcloud-sdk/lib/plugins/event_dispatcher/index.node");  

// Create an Eyeofcloud client with the default event dispatcher 
var eyeofcloudClientWithDefaultDispatcher = eyeofcloud.createInstance({   
    datafile,   eventDispatcher: defaultEventDispatcher 
});

事件调度程序应实现一个dispatchEvent函数，该函数接受三个参数：httpVerb、url和params，所有这些都由内部类EventBuilder创建。在此函数中，应该使用params作为请求url的主体（确保将其字符串化为 JSON）和标头中{content-type: 'application/json'}向给定的请求发送POST请求。

🚧 重要

如果使用的是自定义事件调度程序，请不要修改从云眼特性标帜(Feature Flag)AB实验返回的事件负载。修改此有效负载将更改结果。

事件批处理

配置事件批处理

我们提供了两个选项来配置事件批处理：eventBatchSize和eventFlushInterval。可以在客户端创建期间传入这两个选项。事件保留在队列中，直到：

  • 事件数达到定义的eventBatchSize。
  • 最旧的事件在队列中存在的时间超过了定义的eventFlushInterval，该值以毫秒为单位指定。然后刷新队列，并在单个网络请求中将所有排队的事件发送到 Eyeofcloud 功能实验。
  • 收到新的数据文件修订版。仅当启用了实时数据文件更新时，才会发生这种情况。

JavaScript

const eyeofcloudSdk = require('@eyeofcloud/eyeofcloud-sdk')  

eyeofcloudSdk.createInstance({   
    // other options   
    eventBatchSize: 100,   
    eventFlushInterval: 3000, 
})

下表定义了这些选项，并列出了浏览器和服务器默认设置的一般建议。在浏览器上，我们建议使用小eventBatchSize（10）和短eventFlushInterval（1000）。这可确保以相对较快的方式发送事件，因为如果用户立即退回，某些事件可能会丢失，同时在许多决策调用连续发生的情况下获得网络效率。

对于服务器，这些数字更加灵活，应根据组织的流量和需求进行设置。请联系支持人员以获取针对特定实施的建议。

名字描述推荐值
事件批量大小队列中要保留的最大事件数。达到此数字后，将刷新所有排队的事件并将其发送到云眼灰度实验。 注意：将此值设置为 1，不会对事件进行批处理，并且事件请求的行为与 3.3.0 之前的 JavaScript SDK 中的行为完全相同。默认值：10
事件刷新间隔事件在刷新之前可以存在于队列中的最长持续时间（以毫秒为单位）。默认值：30000 ms

描述

推荐值

事件批量大小

队列中要保留的最大事件数。达到此数字后，将刷新所有排队的事件并将其发送到云眼特性标帜(Feature Flag)AB实验。
默认值：10

注意：将此值设置为 1，不会对事件进行批处理，并且事件请求的行为与 3.3.0 之前的 JavaScript SDK 中的行为完全相同。

根据组织的要求。

事件刷新间隔

事件在刷新之前可以存在于队列中的最长持续时间（以毫秒为单位）。
默认值：30000 ms

根据组织的要求。

📘 注意

最大有效负载大小为 3.5 MB。如果生成的批处理有效负载超过此限制，请求将被拒绝，并显示 400 响应代码Bad Request Error。

负载大小较大的最常见原因是批大小较高。如果有效负载超出大小限制，请尝试配置较小的批大小。

在应用程序退出时关闭云眼灰度实验

如果启用事件批处理，则必须在退出之前调用 Close 方法（eyeofcloud.close()）。这可确保尽快刷新排队的事件，以避免数据丢失。

❗

警告

由于 Eyeofcloud 客户端维护排队事件的缓冲区，因此必须在关闭应用程序之前或在取消引用实例时调用close() Eyeofcloud 功能实验实例。

方法描述
关闭（）停止所有计时器并刷新事件队列。此方法还将停止数据文件管理器发生的任何计时器。 注意：我们建议将此方法连接到正在运行的进程的终止信号。

可以挂钩到SIGTERM事件以确保调用close()事件，从而保证发送队列中的所有事件。

节点

// respond to SIGTERM and close eyeofcloud 
process.on('SIGTERM', async () => {   
    console.log('SIGTERM signal received.');   
    await eyeofcloud.close()   
    process.exit(0) 
});

SDK记录器

记录器记录有关实验的信息，以帮助你进行调试。可以自定义日志信息的发送位置以及跟踪的信息类型。

JavaScript SDK带有一个默认的Logger 实现 设置为ERROR日志级别。要配置日志级阈值，可以调用setLogLevel SDK。

节点

var eyeofcloudSDK = require('@eyeofcloud/eyeofcloud-sdk');  

// Set log level to debug 
// Can be 'info', 'debug', 'warn', 'error' 
eyeofcloudSDK.setLogLevel('debug');  
eyeofcloudSDK.setLogger(eyeofcloudSDK.logging.createLogger());  

// To turn off logging, call setLogger with null 
eyeofcloudSDK.setLogger(null);

🚧 重要

使用 defaault 记录器时：在最新版本的 Node SDK 中，需要手动创建记录器，然后才能调用 'setLogLevel'。为此，请在应用中调用“setLogLevel”方法之前添加以下行：

JavaScript

// create logger eyeofcloudSDK.setLogger(eyeofcloudSDK.logging.createLogger());

为了在生产环境中更好地控制 SDK 配置，请为 Eyeofcloud 客户端传入自定义记录器。自定义记录器是一个接受参数、级别和消息的函数。请参阅下面的代码示例来创建和设置自定义记录器。

节点

var eyeofcloudSDK = require('@eyeofcloud/eyeofcloud-sdk');  

// Set log level 
eyeofcloudSDK.setLogLevel('debug');  

/**  
* customLogger  
*   
* Example of a custom logger. A custom logger is a function that  
* takes two parameters (level, message) and logs to an appropriate place,  
* typically the console.  
*  
* @param {string} level indicating the level of the log message  
* @param {string} message indicating the log message  
*  
*/ 
var customLogger = function(level, message) {   
    var LOG_LEVEL = eyeofcloudSDK.enums.LOG_LEVEL;   
    switch (level) {     
        case LOG_LEVEL.INFO:       
            // INFO log message       
            console.log(message);       
            break;          
            
        case LOG_LEVEL.DEBUG:       
            // DEBUG log message       
            console.log(message);       
            break;      
            
        case LOG_LEVEL.WARNING:       
            // WARNING log message       
            console.log(message);       
            break;      
        
        case LOG_LEVEL.ERROR:       
            // ERROR log message       
            console.log(message);       
            break;   
    } 
}  

// Set the custom logger 
eyeofcloudSDK.setLogger({   
    log: customLogger, 
});

日志级别

下表列出了 JavaScript（节点）SDK 的日志级别。

日志级别解释
eyeofcloudSDK.enums.LOG_LEVEL.错误将记录阻止灰度标帜或实验正常运行的事件（例如，初始化中的无效数据文件和无效的功能键）。用户可以采取措施进行更正。
eyeofcloudSDK.enums.LOG_LEVEL.警告不会阻止灰度标帜或实验正常运行，但可能会产生意外结果（例如，将来的 API 弃用、记录器或错误处理程序设置不正确）的事件将被记录下来。
eyeofcloudSDK.enums.LOG_LEVEL.INFO记录重要事件（例如，决策已启动、决策成功、跟踪已启动和跟踪成功）。这有助于显示 API 调用的生命周期。
eyeofcloudSDK.enums.LOG_LEVEL.调试将记录与可帮助我们调试问题的错误相关的任何信息（例如，灰度标帜未运行、用户未包含在推出中）。

将记录阻止特性标帜(Feature Flag)或实验正常运行的事件（例如，初始化中的无效数据文件和无效的功能键）。用户可以采取措施进行更正。

eyeofcloudSDK.enums.LOG_LEVEL.警告

不会阻止特性标帜(Feature Flag)或实验正常运行，但可能会产生意外结果（例如，将来的 API 弃用、记录器或错误处理程序设置不正确）的事件将被记录下来。

eyeofcloudSDK.enums.LOG_LEVEL.INFO

记录重要事件（例如，决策已启动、决策成功、跟踪已启动和跟踪成功）。这有助于显示 API 调用的生命周期。

eyeofcloudSDK.enums.LOG_LEVEL.调试

将记录与可帮助我们调试问题的错误相关的任何信息（例如，特性标帜(Feature Flag)未运行、用户未包含在推出中）。

错误处理程序

在生产环境中，需要完全控制和查看应用程序中发生的错误，包括源自云眼特性标帜(Feature Flag)AB实验 JavaScript（节点）SDK 的错误。

功能实验 SDK 在 SDK 中提供错误处理程序的默认实现。 下面是使用 SDK 中的默认错误处理程序的示例：

节点

const EyeofcloudSdk = require("@eyeofcloud/eyeofcloud-sdk");   

// 3.0.0 SDK 
var defaultErrorHandler = require("@eyeofcloud/eyeofcloud-sdk/lib/plugins/error_handler");   

// 3.0.1 SDK and above 
var defaultErrorHandler = require("@eyeofcloud/eyeofcloud-sdk").errorHandler;   
EyeofcloudSdk.setLogger(EyeofcloudSdk.logging.createLogger())   
const eyeofcloudClient = EyeofcloudSdk.createInstance({   
    // No datafile will trigger the custom error handler,   
    // but the default error handler is a no-op   
    datafile: null,   
    errorHandler: defaultErrorHandler 
});

但是，为了进一步控制和查看来自 Eyeofcloud 功能实验 SDK 的错误，我们建议实现自己的自定义错误处理程序。

使用自定义错误处理程序，可以选择如何处理错误，无论是将错误记录到控制台还是将错误发送到另一个错误监视服务一样简单。

下面是使用自定义错误处理程序将错误记录到控制台的示例：

节点

const EyeofcloudSdk = require("@eyeofcloud/eyeofcloud-sdk");   

/**  
* customErrorHandler  
*  
* Object that has a property `handleError` which will be called  
* when an error is thrown in the SDK.  
*/ 
const customErrorHandler = {   
    /**    
    * handleError    
    *    
    * Function which gets called when an error is thrown in the SDK    
    * @param {Object} error - error object    
    * @param {String} error.message - message of the error    
    * @param {String} error.stack - stack trace for the error    
    */   
    handleError: function(error) {     
        console.log('CUSTOM_ERROR_HANDLER');     
        console.log('****');     
        console.log(`Error Message: ${error.message}`);     
        console.log(`Error Stack: ${error.stack}`);     
        console.log('****');   
    } 
}   

EyeofcloudSdk.setLogger(EyeofcloudSdk.logging.createLogger())   
const eyeofcloudClientInstance = EyeofcloudSdk.createInstance({   
    // No datafile will trigger the custom error handler,   
    datafile: null,   
    errorHandler: customErrorHandler, 
});

设置通知侦听器

通知侦听器触发您在 SDK 中触发某些操作时定义的回调函数。

最常见的用例是将所有特性标帜(Feature Flag)决策的流发送到分析提供商或内部数据仓库，以将其与您拥有的有关用户的其他数据联接。

通知侦听器类型

有关通知侦听器类型和用例的更多信息，请参阅通知侦听器。

有关代码示例，请参阅以下部分。

添加和删除所有通知侦听器

下面的示例代码演示如何添加侦听器、删除侦听器、删除特定类型的所有侦听器（例如所有决策侦听器）以及删除所有侦听器。

节点

import { enums } from '@eyeofcloud/eyeofcloud-sdk';  

// Remove Notification Listener 
eyeofcloudClient.notificationCenter.removeNotificationListener(notificationId);  

// Remove All Notification Listeners 
eyeofcloudClient.notificationCenter.clearAllNotificationListeners();  

// Remove all Notification Listeners of a certain type 
eyeofcloudClient.notificationCenter.clearNotificationListeners(enums.NOTIFICATION_TYPES.DECISION);

设置每种类型的通知侦听器

下面的示例代码演示如何设置每种类型的通知侦听器。

JavaScript

import { enums } from '@eyeofcloud/eyeofcloud-sdk'; 
// import your third-party analytics integration here  

/////////////////////////////////////////// 
// SET UP DECISION NOTIFICATION LISTENER // 
///////////////////////////////////////////  

const onDecision = ({ type, userId, attributes, decisionInfo }) => {   
    // Add a DECISION Notification Listener for type FLAG   
    if (type === 'flag') {     
        // Access information about feature, for example, key and enabled status     
        console.log(decisionInfo['flagKey']);     
        console.log(decisionInfo['enabled']);     
        console.log(decisionInfo['decisionEventDispatched']);     
        // Send data to analytics provider here   
    } 
}  

const notificationId = eyeofcloudClient.notificationCenter.addNotificationListener(
    enums.NOTIFICATION_TYPES.DECISION, onDecision
);  

//////////////////////////////////////////// 
// SET UP LOG EVENT NOTIFICATION LISTENER // 
////////////////////////////////////////////  
const onLogEvent = (logEvent) => {   
    // process the logEvent object here (send to analytics provider, audit/inspect data) 
}  

eyeofcloudClient.notificationCenter.addNotificationListener(
    enums.NOTIFICATION_TYPES.LOG_EVENT, onLogEvent
);  

//////////////////////////////////////////////////// 
// SET UP EYEOFCLOUD CONFIG NOTIFICATION LISTENER // 
////////////////////////////////////////////////////  

// listen to EYEOFCLOUD_CONFIG_UPDATE to get updated data 
const onConfigUpdateListener = () => {   
    const config = eyeofcloudClient.getEyeofcloudConfig() 
}  

eyeofcloudClient.notificationCenter.addNotificationListener(
    enums.NOTIFICATION_TYPES.EYEOFCLOUD_CONFIG_UPDATE, onConfigUpdateListener
); 

//////////////////////////////////////// 
// SET UP TRACK NOTIFICATION LISTENER // 
////////////////////////////////////////  

const onTrack = (event) => {   
    // process the event here (send to analytics provider, audit/inspect data) 
}  
eyeofcloudClient.notificationCenter.addNotificationListener(
    enums.NOTIFICATION_TYPES.TRACK, onTrack
);

更新旧版本API使用情况

本节提供了代码示例，说明我们建议如何利用新的决策和事件跟踪 API。所有现有方法和实现仍包含在内并受支持，并且只有在弃用标记和未来主要变体后才会删除。

我们建议采用新的“决定”、“全部决定”和“跟踪事件”方法，作为当前在实现中使用 isFeatureEnabled、getFeatureVariable、getAllFeatures或 Track 调用的更灵活、更易于使用的替代方法。

有关早期方法，请参阅 SDK 参考指南的早期变体。

下面是如何将旧方法迁移到较新方法的一些示例。

JavaScript

// ------------------------------- 
// Prereq for new methods: create a user 
// ------------------------------ 

var attributes = {   
    is_loggin_in: true 
}; 

var user = eyeofcloudClient.createUserContext('user123', attributes);  

// ------------------------------- 
// Is Feature Enabled  
// ------------------------------

Decision方法基于特性标帜(Feature Flag)键，不支持独立的A / B测试或多臂老虎机。我们正在努力长期统一应用程序的数据模型和接口，以减少维护多种不同访问方法的需求。同时，仍然可以在旧项目中使用“激活”和“获取变体”方法以及“决定”方法进行独立的 A/B 测试。

EyeofcloudUserContext

以下代码显示了 EyeofcloudUserContext 的对象定义：


interface EyeofcloudUserContext {
  // return user attributes
  getAttributes(): UserAttributes;
  // set an attribute for the user 
  setAttribute(key: string, value: unknown): void;
  // make a decision about which flag variation the user buckets into for the flag key
  decide(
    key: string,
    options?: EyeofcloudDecideOption[]
  ): EyeofcloudDecision;
  // make decisions about which flag variations the user buckets into for flag keys
  decideForKeys(
    keys: string[],
    options?: EyeofcloudDecideOption[],
  ): { [key: string]: EyeofcloudDecision };
  // make decisions about which flag variations the user buckets into for all flags
  decideAll(
    options?: EyeofcloudDecideOption[],
  ): { [key: string]: EyeofcloudDecision };
  // track user event
  trackEvent(eventName: string, eventTags?: EventTags): void;
  // Sets the forced decision (variationKey) for a given decision context
  setForcedDecision(context: EyeofcloudDecisionContext, decision: EyeofcloudForcedDecision): boolean;
  // Returns the forced decision for a given decision context
  getForcedDecision(context: EyeofcloudDecisionContext): EyeofcloudForcedDecision | null;
  // Removes the forced decision for a given decision context
  removeForcedDecision(context: EyeofcloudDecisionContext): boolean;
  // Removes all forced decisions bound to this user context
  removeAllForcedDecisions(): boolean;
}

性能

下表显示了 EyeofcloudUserContext 对象的属性：

属性类型评论
用户标识字符串用户的ID
（可选）属性Map自定义键值对的映射，用于指定用于受众群体定位的用户属性。创建用户时，可以使用用户 ID 传递映射。

方法

下表显示了 EyeofcloudUserContext 对象的方法：

方法评论
设置属性将自定义用户属性作为键值对传递给用户上下文。
决定返回用户的标帜键的决策结果。决策结果在 EyeofcloudDecision 对象中返回，并包含传递标帜规则所需的所有数据请参阅分桶方法decide
决定全部返回用户的所有活动（未存档）标帜的决策。请参阅分桶方法decide
决定键返回指定标帜键的标帜决策映射。
跟踪事件跟踪用户的转化事件（即用户执行的操作）。如果指定的事件键与任何现有事件不匹配，则记录错误消息。 查看跟踪事件
设置强制决策强制用户使用特定变体。 请参阅设置强制决策
getForcedDecision返回用户被强制进入的变体。 请参阅获取强制决策
删除强制决策从特定的强制变体中删除用户。 请参阅删除强制决策
删除所有强制决策从所有强制变体中移除用户。 请参阅删除所有强制决策

强制决策方法

下面描述了 Harmony SDK 将遵循的特定场景：

标记到决策

  • SDK 将在给定标帜的任何决策调用开始时查找。如果为该标帜找到匹配的标帜到决策强制决策，它将返回该决定。

从实验规则到决策

  • SDK 将在决策开始时查找给定实验规则（标帜键）。如果为标帜找到匹配的实验规则到决策强制决策，它将返回决策。

从交付规则到决策

  • SDK 将在决策开始时查找给定的传递规则（标帜键）。如果找到匹配的传递规则到决策强制决策，它将返回该决策。

❗️

警告

在调用任何强制决策方法之前，必须将变体关联到标帜规则。

对于强制决策，SDK 会像其他正常决策一样触发展示事件和通知（除非被 disableDecisionEvent 选项禁用）。

📘 注意

这些强制决策不是永久性的，将在重新初始化 EyeofcloudUserContext 时清除。

云眼分桶结果 EyeofcloudDecision上下文

export interface EyeofcloudDecisionContext {   flagKey: string;   ruleKey?: string; }

云眼强制决策

export interface EyeofcloudForcedDecision {   variationKey: string; }

设置强制决策方法- setForcedDecision()

描述

为给定的EyeofcloudDecisionContext设置强制决策（variationKey）。

参数

下表列出了 Harmony SDK 的必需参数和可选参数。

参数类型描述
所需的_上下文接口EyeofcloudDecisionContext的实例，其中包含要获取的强制决策的必需flagKey和可选ruleKey。
(必选)决定接口EyeofcloudForcedDecision的实例，其中包含要设置的强制variationKey决策所需的实例。

返回

一个布尔值，指示是否成功完成了强制决策（variationKey）的设置。

例子

查看完整鸿蒙SDK示例 here.

获取强制决策方法 - getForcedDecision（）

描述

返回给定EyeofcloudDecisionContext的强制决策 （variationKey）。返回EyeofcloudForcedDecision实例，如果没有匹配项，则返回 null。

参数

下表列出了 Android SDK 的必需参数和可选参数。

参数类型描述
所需的上下文结构EyeofcloudDecisionContext的实例，其中包含要获取的强制决策的必需flagKey和可选ruleKey。

返回

上下文的强制决策EyeofcloudForcedDecision实例，如果没有匹配项，则为 null。

例子

在此处查看完整的 Harmony SDK 示例。

删除强制决策方法 - 删除强制决策（）

描述

删除给定EyeofcloudDecisionContext的强制决策（variationKey）。

参数

下表列出了 Harmony SDK 的必需参数和可选参数。

参数类型描述
所需的上下文.classEyeofcloudDecisionContext的实例，其中包含要获取的强制决策的必需flagKey和可选ruleKey。

返回

删除强制决策（variationKey）时的成功/失败布尔状态。

例子

在此处查看完整的 Harmony SDK 示例。

删除所有强制决策方法 - 删除所有强制决策（）

描述

删除用户上下文的所有强制决策 （variationKey）。

参数

下表列出了 Harmony SDK 的必需参数和可选参数。

参数类型描述
没有不适用不适用

返回

一个成功/失败布尔状态

例子

查看完整鸿蒙SDK示例 here.

代码示例 

import { createInstance } from 'eyeofclouf/src/packages/eyeofcloud-sdk/lib/index.node'

const eyeofcloudClient = createInstance({sdk: 'sdk_key' //Provide the sdkKey of your desired environment here });
const user = eyeofcloudClient.createUserContext('test_user', attributes)
let success, decision, forcedDecision; 

// set a forced decision for a flag
success = user.setForcedDecision({flagKey: 'flag-1'}, {variationKey: 'variation-a'});
decision = user.decide('flag-1'); 

// set a forced decision for an ab-test rule
success = user.setForcedDecision({flagKey: 'flag-1', ruleKey: 'ab-test-1'}, {variationKey: 'variation-b'});
decision = user.decide('flag-1');

// set a forced variation for a delivery rule
success = user.setForcedDecision({flagKey: 'flag-1', ruleKey: 'delivery-1'}, {variationKey: 'on'});
decision = user.decide('flag-1');

//get foced variations 
forcedDecisoon = user.getForcedDecisoon({flagKey: 'flag-1'});

// remove forced variations
success = user.removeForcedDecision({flagKey: 'flag-1', ruleKey: 'ab-test-1'});
user.removeAllForcedDecisions();
Last update: 1/8/2025, 4:04:24 PM
Contributors: zhangweixue,刘天乐