README

A/B Smartly PHP SDK

兼容性

A/B Smartly PHP SDK 兼容 PHP 7.4 及以上版本。为了最佳性能和代码可读性，建议使用 PHP 8.1 或更高版本。此 SDK 正在持续与 PHP 的每日构建进行测试，以确保与最新版本的 PHP 兼容。

入门指南

安装 SDK

A/B Smartly PHP SDK 可以使用 composer 进行安装

composer require absmartly/php-sdk

导入和初始化 SDK

SDK 安装完成后，可以在您的项目中初始化。

您可以使用从 A/B Smartly 获得的 API 密钥、应用程序名称、环境以及端点 URL 创建 SDK 实例。

use \ABSmartly\SDK\SDK;

$sdk = SDK::createWithDefaults(  
  endpoint: $endpoint,
  apiKey: $apiKey,
  environment: $environment,
  application: $application
);

请注意，上述示例使用了 PHP 8.0 中引入的命名参数。虽然强烈建议使用最新版本的 PHP，但 PHP 7.4 也能支持。在 PHP 7.4 上，参数按顺序传递，因为不支持命名参数。

示例

use \ABSmartly\SDK\SDK;

$sdk = SDK::createWithDefaults(  
  $endpoint, $apiKey, $environment, $application, 
);

上述是通过使用默认值快速创建 SDK 实例的快捷方式。如果您希望对各个组件（如自定义事件记录器）进行更细致的选择，可以按照以下方式进行

use ABSmartly\SDK\Client\ClientConfig;  
use ABSmartly\SDK\Client\Client;  
use ABSmartly\SDK\Config;  
use ABSmartly\SDK\SDK;  
use ABSmartly\SDK\Context\ContextConfig;
use ABSmartly\SDK\Context\ContextEventLoggerCallback;
  
$clientConfig = new ClientConfig('', '', '', '');  
$client = new Client($clientConfig);  
$config = new Config($client);  
  
$sdk = new SDK($config);  
  
$contextConfig = new ContextConfig();
$contextConfig->setEventLogger(new ContextEventLoggerCallback(  
    function (string $event, ?object $data) {  
        // Custom callback
    }
));

$context = $sdk->createContext($contextConfig);

SDK 选项

使用自定义事件记录器

A/B Smartly SDK 可以使用适用于所有上下文的事件记录器进行实例化。此外，在创建 ContextConfig 中的特定上下文时，还可以指定事件记录器。

use ABSmartly\SDK\Client\ClientConfig;
use ABSmartly\SDK\Context\ContextEventLoggerCallback;

$contextConfig = new ContextConfig();
$contextConfig->setEventLogger(new ContextEventLoggerCallback(  
    function (string $event, ?object $data) {  
        // Custom callback
    }
));

或者，您可以实现 \ABSmartly\SDK\Context\ContextEventLogger 接口，其中包含接收 Context 对象本身以及 ContextEventLoggerEvent 对象的 handleEvent() 方法，如下所示

use \ABSmartly\SDK\Context\ContextEventLoggerCallback;  
  
class CustomLogger implements ContextEventLogger {
    public function handleEvent(Context $context, ContextEventLoggerEvent $event): void {  
        // Process the log event
        // e.g
        // myLogFunction($event->getEvent(), $event->getData());
    }
}
  
$contextConfig = new ContextConfig();  
$contextConfig->setEventLogger(CustomLogger());

数据参数取决于事件类型。目前，SDK 记录以下事件

创建新上下文请求

同步

$contextConfig = new ContextConfig(); 
$contextConfig->setUnit('session_id', 'session_id5ebf06d8cb5d8137290c4abb64155584fbdb64d8'); // a unique id identifying the user

$context = $sdk->createContext($contextConfig);

带有预取数据

$contextConfig = new ContextConfig(); 
$contextConfig->setUnit('session_id', 'session_id5ebf06d8cb5d8137290c4abb64155584fbdb64d8'); // a unique id identifying the user

$context = $sdk->createContext($contextConfig);

$anotherContextConfig = new ContextConfig();
$anotherContextConfig->setUnit('session_id', 'session_id5ebf06d8cb5d8137290c4abb64155584fbdb64d8'); // a unique id identifying the user

$anotherContext = $sdk->createContextWithData($anotherContextConfig, $context->getContextData());

使用新鲜实验数据刷新上下文

对于长时间运行的上下文，上下文通常在应用程序首次启动时创建一次。
但是，在生产代码中跟踪但创建上下文之后开始的任何实验都不会被触发。

为了减轻这种情况，我们可以在 Context 上使用 refresh() 方法。

$context->refresh();

Context->refresh() 方法从 A/B Smartly 汇集器拉取更新后的实验数据，并在再次调用 Context->getTreatment 时触发最近开始的经验。

设置额外单位

您可以通过调用 Context->setUnit 或 Context->setUnits 方法向上下文中添加额外的单位。这些方法可以在用户登录到您的应用程序时使用，您想在上下文中使用新的单位类型。

请注意，您不能覆盖已设置的单位类型，因为这会改变身份并抛出异常。在这种情况下，您必须创建一个新的上下文。在上下文准备好之前，可以调用 Context->setUnit 和
Context->setUnits 方法。

$context->setUnit('user_id', 143432);

基本用法

选择治疗方案

$treatment = $context->getTreatment('exp_test_experiment');

if ($treatment === 0) {
    // user is in control group (variant 0)
}
else {
    // user is in treatment group
}

治疗方案变量

$defaultButtonColorValue = 'red';
$buttonColor = $context->getVariableValue('button.color');

查看治疗方案变体

尽管通常不推荐，但在某些情况下，查看治疗或变量而不触发曝光是必要的。A/B Smartly SDK 提供了 Context->peekTreatment() 方法来满足这一需求。

$treatment = $context->peekTreatment('exp_test_experiment');

if ($treatment === 0) {
    // user is in control group (variant 0)
}
else {
    // user is in treatment group
}

查看变量

$buttonColor = $context->peekVariableValue('button.color', 'red');

覆盖治疗方案变体

在开发过程中，例如，强制为某个
实验。这可以通过调用Context->setOverride()和/或Context->setOverrides()方法实现。这些方法可以在上下文准备好之前调用。

$context->setOverride("exp_test_experiment", 1); // force variant 1 of treatment

$context->setOverrides(
    [
        'exp_test_experiment' => 1,
        'exp_another_experiment' => 0,
    ]
);

高级

上下文属性

属性用于传递关于用户和/或请求的元数据。
它们可以在Web控制台中稍后用于创建细分市场或受众。
可以使用Context->setAttribute()或Context->setAttributes()方法设置属性，无论是在上下文准备好之前还是之后。

$context->setAttribute('session_id', \session_id());
$context->setAttributes(
    [
        'customer_age' => 'new_customer'
    ]
);

自定义分配

有时可能需要覆盖变体的自动选择。例如，如果您希望变体根据API调用中的数据来选择。这可以通过使用Context->setCustomAssignment()方法实现。

$chosenVariant = 1;
$context->setCustomAssignment("experiment_name", $chosenVariant);

如果您正在运行多个实验并且需要为每个实验选择不同的自定义分配，您可以使用Context->setCustomAssignments()方法。

$assignments = [
    "experiment_name" => 1,
    "another_experiment_name" => 0,
    "a_third_experiment_name" => 2
];

$context->setCustomAssignments($assignments);

发布

有时在继续之前确保所有事件都已发布到A/B Smartly收集器是必要的。您可以显式调用Context->publish()方法。

$context->publish();

最终化

close()方法将确保所有事件都像Context->publish()一样发布到A/B Smartly收集器，并且还会“密封”上下文，如果在调用可能生成事件的任何方法时将抛出错误。

$context->close();

跟踪目标

$context->track(
    'payment',
    (object) ['item_count' => 1, 'total_amount' => 1999.99]
);

absmartly / php-sdk

维护者

详细信息