Download the PHP package fengxinyhyl/datatester-php-sdk without Composer

DataTester PHP SDK

Limitation

This SDK is only supported on PHP 7.1 and later versions.

Prerequisite

Obtain your project's App Key:

1. Go to the BytePlus console and sign in to your account.
2. Under the Products section, click BytePlus Data Intelligence.
3. On the Project List page, for the project you want to integrate the SDK with, under the Actions column, click Details.
4. On the Social Media Details pop-up window, copy the App Key.

Adding dependency

1. Download this sdk to your project's path: git clone https://github.com/volcengine/datatester-php-sdk.git

2. Modify the composer.json file by adding the "repositories" structure.

3. Install the package locally by running the code below.

Changing the domain name

The default domain name must be changed as follows.Source file is [Urls.php].

Using the SDK

The following is a code example of using the PHP SDK.

API reference

AbClient

A class for traffic allocation during initialization.

Parameter description

activate

Obtain a specific experiment version's configuration after traffic allocation and automatically track the exposed events.

Make sure you fill in the trackId field if you want to track events.

Parameter description

Returned value

Parameters of the version that a user enters or the default value when a user/device is not in any version. Can be string, number, boolean, and json type. The following is an example:

activateWithoutImpression

Obtain a specific experiment version's configuration after traffic allocation but not track the exposed events.

Parameter description

Returned value

Parameters of the version or empty array. The following is an example:

getExperimentVariantName

Obtain the version's name of an experiment that a user enters:

Parameter description

Returned value

Name of the version that a user enters or "None" when a user/device is not in any version.

getExperimentConfigs

Obtain detailed information about the version that a user enters:

Parameter description

Returned value

The detailed information about the version that a user enters or 'None' when a user/device is not in any version. The following is an example:

getAllExperimentConfigs

Obtain detailed information about all the versions in all experiments.

Parameter description

Returned value

The detailed information about versions that a user enters or empty array when a user/device is not in any version. The following is an example:

getFeatureConfigs

Obtain detailed information about a feature that a user joins.

Parameter description

Returned value

The detailed information about a feature's variant that a user joins. 'None' when a user/device is not in this feature or the feature is disabled. The following is an example:

getAllFeatureConfigs

Obtain detailed information about all features that a user joins.

Parameter description

Returned value

The detailed information about all feature variants that a user joins. The following is an example:

getExperimentVariantNameWithImpression

Obtain the version's name of the experiment that a user enters.

Interfaces with WithImpression automatically track events. Meanwhile, make sure you fill in the trackId field in the activate interface if you want to track events.

Parameter description

Returned value

Name of the version that a user enters or "None" when a user/device is not in any version.

getExperimentConfigsWithImpression

Obtain detailed information about the version that a user enters.

Interfaces with WithImpression automatically track events. Meanwhile, make sure you fill in the trackId field in the activate interface if you want to track events.

Parameter description

Returned value

The detailed information about the version that a user enters or 'None' when a user/device is not in this version. The following is an example:

getFeatureConfigsWithImpression

Obtain detailed information about a feature that a user joins.

Interfaces with WithImpression automatically track events. Meanwhile, make sure you fill in the trackId field in the activate interface if you want to track events.

Parameter description

Returned value

The detailed information about a feature's variant that a user joins. 'None' when a user/device is not in this feature or the feature is disabled. The following is an example:

Others

In order to better use the sdk, some suggestions are provided.

LoggerInterface

The log interface provides a default implementation; if there is a business need, you can customize the implementation class processing and use it when instantiating AbClient.

ProductConfigManagerInterface

Meta management interface: request the meta service to pull the experiment and feature information under the application. Default implementation pull it in real time every time AbClient is instantiated; if there is a business need, you can customize the implementation class processing, and use it in when instantiating AbClient.

Suggestion

It is recommended to use redis to cache meta information to avoid pulling every time AbClient is initialized.

The following is an example:

EventDispatcherInterface

Event tracking interface: which track exposure events, provides a default implementation, and track in real time when 'activate' and 'WithImpression' interfaces are called; if there are business needs, you can customize the implementation class processing, and use it in when instantiating AbClient.

Suggestion

It is recommended to use mq(kafka/rocketmq) to track events to avoid tracking events by http every time interfaces are called.

1. Send msg to mq when events happen
2. Use other services to consume kafka and track events

The following is an example:

UserAbInfoHandler

Maintain user historical decision information; If you need to use the function of 'freezing experiment' or 'Traffic changes will not affect exposed users', you can customize the implementation class processing, and use it in when instantiating AbClient.

Suggestion

It is recommended to use redis to cache decision information.

The following is an example:

Anonymously tracking

If there is no user_unique_id as trackId, you can use device_id, web_id, bddid（only onpremise） for anonymous tracking.

1. set event builder config

2. append device_id, web_id, bddid to $attributes when trackId is empty string

3. call activate or 'WithImpression' interfaces

DataTester PHP SDK

版本需求

php7.1及更高版本

准备工作

获取应用的App Key（即SDK使用的token）:

1. 访问火山引擎并登录您的账号
2. 进入集团设置页面，找到应用列表-应用ID列
3. 鼠标悬停在应用ID后的感叹号上获取App Key

依赖导入

1. 将SDK下载至项目路径下: git clone https://github.com/volcengine/datatester-php-sdk.git

2. 修改项目的composer.json文件，添加repositories结构

3. 安装本地包

域名修改

SaaS-国内: 默认使用的是SaaS国内环境的域名，无需修改

SaaS-海外: 海外环境需要修改BASE_URL和EVENT_URL，替换为BASE_URL_I18N与EVENT_URL_I18N即可

私有化: 私有化部署时会有产品域名和上报域名，如下图所示，BASE_URL替换为产品域名，EVENT_URL替换为上报域名

代码示例

接口描述

AbClient

初始化ABTest分流类

参数

activate

获取特定key的分流结果，并上报曝光事件

参数

返回值

该函数返回命中版本的参数值，未命中时返回默认值

activateWithoutImpression

获取特定key的分流结果，且不上报曝光事件

参数

返回值

该函数返回命中版本的参数值，未命中时返回空数组

getExperimentVariantName

获取用户命中的特定实验的变体名称

参数

返回值

该函数返回用户命中的特定实验的变体名称

getExperimentConfigs

获取用户命中的特定实验的变体详情

参数

返回值

该函数返回命中变体的array对象，表明用户命中某个实验的变体详情，通常仅能命中一个变体

getAllExperimentConfigs

获取用户命中的所有实验的变体详情

参数

返回值

该函数返回命中变体的array对象，表明用户命中所有实验的变体详情，通常命中多个变体

getFeatureConfigs

获取用户命中的特定feature的变体详情

参数

返回值

该函数返回命中变体的array对象，表明用户命中某个feature的变体详情，通常仅能命中一个变体

getAllFeatureConfigs

获取用户命中的所有feature的变体详情

参数

返回值

该函数返回命中变体的array对象，表明用户命中所有feature的变体详情，通常命中多个变体

1、含有“WithImpression”字样的接口均会自动上报曝光事件

2、请务必填写trackId字段，否则会导致上报失效

getExperimentVariantNameWithImpression

同接口“getExperimentVariantName”

getExperimentConfigsWithImpression

同接口“getExperimentConfigs”

getFeatureConfigsWithImpression

同接口“getFeatureConfigs”

其他

LoggerInterface

日志打印接口，提供默认实现；如有业务需要，可自定义实现类处理，实例化AbClient时传入

ProductConfigManagerInterface

配置管理接口，请求meta服务拉取应用下的实验信息，提供默认实现，每次实例化AbClient时实时拉取；如有业务需要，可自定义实现类处理，实例化AbClient时传入

PHP本身不支持内存级别的缓存，可以通过文件(大多数第三方库的选择)或者借助Redis等进行缓存，通过定时任务去拉取meta信息，避免实时拉取

使用Redis缓存示例（仅供参考）

EventDispatcherInterface

事件上报接口，上报进组曝光事件，提供默认实现，调用activate与WithImpression接口时实时上报；如有业务需要，可自定义实现类处理，实例化AbClient时传入

不使用扩展PHP并不支持多线程，可以通过第三方库或者使用mq等进行异步发送，避免实时上报

基于kafka等消息队列，在实例化AbClient对象时传入EventDispatcherInterface的实现类;事件直接写入kafka，通过其他服务去消费kafka并上报（上报可参考 DefaultEventDispatcher的实现），写入和消费kafka的逻辑需自行实现

UserAbInfoHandler

用户信息处理接口，冻结实验、进组不出组场景下使用

冻结实验和进组不出组需要持久化用户的进组信息，SDK提供的默认实现不进行数据持久化； 如有业务需要，则实现UserAbInfoHandler接口，结合Redis或其他外部存储对用户进组信息进行持久化处理，初始化AbClient时传入。 使用方式：

1. 初始化AbClient时不传入UserAbInfoHandler，则默认使用空实现，不启用“进组不出组”功能
2. 继承UserAbInfoHandler接口，自行实现持久化存储；初始化AbClient时通过构造函数传入

使用Redis缓存示例（仅供参考）

匿名上报

获取不到uuid的用户，可以通过填充device_id或者web_id进行事件上报（私有化场景下也支持bddid）

1. 实例化AbClient后修改事件上报相关配置，setEventBuilderConfig第一个参数（true/开启，false/关闭）匿名上报，第二个参数（true/saas，false/私有化）

2. 添加device_id, web_id, bddid到用户属性$attributes，trackId固定传入空字符串""

3. 请求activate或其他'WithImpression'接口即可匿名上报