概述

此页面是云眼SDK的使用参考。

以下内容将指导安装云眼SDK以及在代码中运行优化方案。 可以通过右上角的按钮来切换及查看其他语言的使用参考。

如果刚开始使用云眼平台,建议对以下内容进行预览:

  • 请阅读云眼入门指南: 介绍如何安装SDK并在几分钟内运行优化方案。

  • 请参阅下面的使用示例: 了解SDK的关键组件。

  • 查看常见问题: 得到一些常见问题的解决方案。


使用示例

SDK在代码中运行优化方案的基本用法请参考右侧的代码。

首先,需要根据云眼应用的数据文件来进行Eyeofcloud对象的初始化。

首先激活优化方案,然后进行分流,最后追踪目标事件的转化。注意,只有在 activate 已经被调用的情况下,才可进行分流,以及调用track函数用于跟踪一个或多个试验的目标事件的转化

请注意,SDK要求调用activatetrack方法时提供唯一用户ID 。

安装

数据文件

SDK 在初始化时需要读取和解析数据文件。

数据文件采用JSON格式,包含了运行优化方案的所有信息,因此在调用activatetrack方法时无需进行任何网络请求。

除非正在对云眼SDK进行二次开发,否则不需要直接与数据文件进行交互,云眼SDK会在解析数据文件后提供与云眼交互所需的所有接口。

数据文件位置

同步

为了接收试验更新的通知,SDK需要定期同步云眼服务器上的数据文件。


Webhooks

如果正在用服务器端应用程序管理数据文件,建议配置webhooks来维护最新版本的数据文件。只要相应的项目被修改,提供的端点将被发送一个POST请求。只要数据文件被更新,必须重新实例化SDK中的Eyeofcloud对象,以使更改生效。

可以通过“设置”>“ Webhooks”来设置 webhook,并添加webhook服务应响应的URL。

webhook有效负载结构如下。

{
    "idSite": 1234,
    "timestamp": 1590196904,
    "event": "project.datafile_updated",
    "data": {
        "revision": 1,
        "origin_url": "/editor/config/json/fullstack/1234.json"
    }
}

目前,云眼平台只支持project.datafile_updated一种事件类型.


初始化Eyeofcloud实例


初始化选项

有关如何自定义Eyeofcloud实例的完整详细信息,请参阅: SDK配置


优化方案

调用activate方法即可在代码中激活及运行优化方案。

如果需要在激活优化方案时向云眼发送一个PageView的话,可以调用activate方法。调用activate方法需要两个参数:优化方案的名称和用户ID。

调用该函数时,首先判断用户是否满足优化方案的受众条件。如果满足,优化方案就会开始运行,然后基于分流情况抽选优化方案的优化版本,并向云眼发送一次PageView。最后函数返回被抽中的优化版本的名称。

在使用SDK的接口编写代码时,请确保代码满足没有任何优化方案被激活的情况,比如执行默认的优化版本。

注意: 应该在需要云眼记录优化方案的运行及用户的信息的情况下,调用activate方法。在用户满足优化方案的受众条件的情况下,SDK会发送一次PageView事件到云眼服务器,以记录优化方案的运行及用户的信息。在用户不满足优化方案的受众条件的情况下,SDK不会发送任何记录。

用户属性

如果希望能够根据用户的属性对优化方案结果进行分段,那么在激活优化方案时包含参数attributes即可。在向云眼发送记录时,云眼将记录这些属性值,以便可以在优化结果页面上通过这些属性对结果进行分段。

使用用户属性还可以将优化方案定位到在云眼控制台预先定义的特定受众群体中。如果优化方案定义了受众条件,云眼将会在激活优化方案时通过属性值评估用户是否满足受众条件,从而决定是否激活优化方案。

  • 即使API里使用了attributes,如果试验里没有添加受众(表示所有用户都可以激活试验),这时attributes对是否激活试验不起任何作用,但是attributes仍可以传到云眼后台用于分段。
  • 即使API里使用了attributes,如果试验里添加的受众只使用了一部分用户属性,没有被使用的用户属性对是否激活试验不起任何作用,但是仍可以传到云眼后台用于分段。
  • 获取版本

    在已经调用activate方法根据用户ID激活了优化方案的情况下,如果想再次获取该优化方案中被抽中的版本名称而不向云眼发送重复的跟踪请求,可以参照右侧所示的代码。

    事件

    如右图所示,可以轻松地编写代码来跟踪事件的转化。

    跟踪事件不需要优化方案和优化版本的名称作为参数:云眼后台只会对已被使用的事件进行跟踪。

    要在优化结果页面上对结果进行分段,需要向track方法传递在activate方法中使用的相同用户属性。

    注意: 云眼只会在activate方法被调用后对事件进行记录。如果在优化结果页面上没有看到期望的事件转化结果,请检查代码,确保在调用track方法之前,已调用activate方法激活优化方案。

    使用其他语言的SDK跟踪同一事件

    可以使用云眼任何SDK跟踪同一事件,因此可以运行跨多个应用程序,服务或设备的优化方案。所有的SDK都具有相同的版本抽选和分流逻辑,所以如果使用相同的数据文件和用户ID,在任何SDK中,都将获得相同的优化方案运行结果和事件跟踪效果。

    例如,如果在服务器上运行试验,可以使用云眼Python,Java,Ruby或Node SDK 激活优化方案,同时,可以使用云眼JavaScript,Objective-C或Android SDK 跟踪客户端的用户操作。

    如果计划在同一个项目中使用多个SDK,请确保所有SDK都使用相同的数据文件和用户ID。

    事件标签

    事件标签是跟踪的获得转化的事件的上下文信息。例如,可以使用标签来描述产品被购买了、文章被阅读了或航班被预定了等事件转化的信息。

    保留关键字

    除了作为eventFeatures参数时,以下关键字被保留,并将映射到事件的有效载荷:

    • revenue - 作为试验指标计算中需要使用的整型值。
    注意: 事件标签eventTags暂时用不到,可以忽略此部分文档。


    变量

    使用变量来使应用程序参数化,从而实时进行AB测试。

    变量可以在应用程序中声明和初始化一次。将这些变量部署到生产环境后,可以随后对这些变量的不同值执行无限制的试验,而无需执行额外的代码部署。可以在编辑优化方案时控制变量,以便可以实时推出功能并调整应用程序的行为。


    可以使用优化方案组来保持优化方案互斥,并消除交互效应。

    作为组的一部分的优化方案在SDK中具有完全相同的接口:像任何其他试验一样可以调用 activate方法 和 track方法。SDK将确保同一组中的两个优化方案将不会以同一用户ID被激活。

    白名单

    可以使用白名单强制分配用户到特定的优化版本中,从而进行QA。

    白名单信息包含在数据文件的forcedVariations内容中。设置白名单后,不需要在代码中做额外的事情;如果设置了白名单,则激活优化方案时将基于白名单强制抽中特定优化版本。白名单的优先级高于受众条件和流量分配。但如果优化方案未激活运行,则白名单不起作用。

    匿名IP

    在某些国家/地区,需要删除IP地址的最后一个区块,以保护访问者的身份,云眼提供匿名IP功能。

    注意: 匿名IP功能目前仅适用于iOS,tvOS和Android项目。


    SDK配置

    可以为Eyeofcloud实例提供参数,以配置SDK的行为:

    SDK提供了默认的Event dispatcher、Logger和Error handler实现,但是如果生产应用程序中有不同的要求,建议重写默认的实现。如果只是想对默认实现作出修改,请参阅SDK源代码中的参考实现示例。


    Event dispatcher

    可以通过提供请求分发方法来更改SDK如何将事件发送到云眼。如果SDK默认的Event dispatcher实现不满足开发需求,可以提供自己的Event dispatcher作为Eyeofcloud实例的参数。

    事件调度函数接受具有以下三个属性的事件对象: httpVerburlparams,这三个参数是实例化EventBuilder类时需要的。POST请求应该包含url与将params放在body中(请确保格式为JSON),并在header包含{content-type: 'application/json'}

    Logger

    日志级别在SDK之间可能略有不同:

    日志级别            描述
    CRITICAL 记录导致应用崩溃的事件。
    ERROR 记录导致激活和运行优化方案失败的错误事件。
    (例如,无效的数据文件、无效的优化方案名称等)
    用户可以采取行动纠正。
    WARNING 记录可能导致激活和运行优化方案失败的事件。
    (例如,调用已被弃用的API、getter方法返回nil等)
    DEBUG 记录任何可能跟错误有关的信息,以帮助进行调试。
    INFO 记录常规事件(例如,开始激活优化方案、激活成功等)。
    这有助于显示API调用的生命周期。


    Error handler

    可以提供自定义的错误处理程序逻辑,以便在整个生产环境中进行标准化。在以下情况下将调用此错误处理程序:

    • 未知的优化方案名称被引用
    • 未知的事件名称被引用

    如果错误处理程序未被重写,默认情况下将使用无操作错误处理程序。


    User profile


    数据文件版本控制


    调试

    以下是使用SDK进行调试的选项。

    设置事件监听

    可以设置监听事件来获得各种SDK事件发生的通知。