PHP SDK

PHP 版本要求 >= 7.4

1.1 composer方式安装

1.1.1 添加依赖

在composer.json中添加依赖：（>=1.0.7 的版本才支持saas，^1.0 表示使用最新的版本 ）

{
"require": {
        "datarangers/datarangers": "^1.0"
    }
}

1.2.2安装依赖

执行命令：

composer require datarangers/datarangers

1.2 源码安装方式

为了您更好地理解和使用我们的sdk，我们已经将SDK进行了开源，具体地址为https://github.com/volcengine/datarangers-sdk-php。您可以直接将SDK源码下载并使用。

2.1 saas初始化

// 初始化
CollectorConfig::init_datarangers_collector([
    "domain" => "https://xxxx",
    "save" => false,
    "headers" => [
        "Content-Type" => "application/json"
    ],
    // 配置 app_id => app_key, 1001 是举例的应用id，需要替换成实际的应用id
    "app_keys" => [
        1001 => getenv("APP_KEY")
    ],
    // 配置 openapi
    "openapi" => [
        "domain" => "https://xxxx",
        "ak" => getenv("OPENAPI_AK"),
        "sk" => getenv("OPENAPI_SK")
    ]
]);

配置说明

• domain，根据接入的环境配置不同的地址：
  • SaaS版国内站: https://mcs.ctobsnssdk.com
  • SaaS版国际站: https://mcs.tobsnssdk.com
• Saas 只支持save为false的
• app_keys， 应用的APP Key，获取位置请参考 “集团设置”->“应用列表”->“详情”：
  
• SAAS环境，如果需要上报 item 和用户属性，需要设置openapi：
  • domain
    • SaaS版国内站: https://analytics.volcengineapi.com
    • SaaS版国际站: https://analytics.byteplusapi.com
  • ak/sk 请联系客户经理获取

2.2 私有化初始化

2.2.1 logagent 模式

需要配合loagent一起使用

CollectorConfig::init_datarangers_collector([
    "save" => true,
    "logger_file_prefix" => "sdk/log/",
    "logger_file_name" => "datarangers.log",
    "log_max_bytes" => 1024 * 10
]);
$rc = new AppEventCollector();

2.2.2 http 模式

// 初始化
CollectorConfig::init_datarangers_collector([
    "domain" => "https://xxxx",
    "save" => false,
    "headers" => [
        "Host" => "xxxx",
        "Content-Type" => "application/json"
    ],
    "http_timeout"=> 10000
]);
$rc = new AppEventCollector();

2.3 配置说明

init_datarangers_collector方法的入参为一个array，具体的参数为

SDK提供了Collector接口，具体的接口为：

/**
 * @param $userUniqueId string uuid
 * @param $appId int appid
 * @param $custom array 自定义属性
 * @param $eventName object 事件名,可以为array
 * @param $eventParams object 事件参数,可以为array,与$eventName 长度相同
 * 例如 $eventName $eventParams 分别为
 * $eventName = "launch" $eventParams = ["param1"=>"param1","param2"=>"param2"]
 * $eventName = ["launch1","launch2"] $eventParams = [["param1"=>"param1","param2"=>"param2"],["param3"=>"param3","param4"=>"param4"]]
 */
public function sendEvent($userUniqueId, $appId, $custom, $eventName, $eventParams);

/**
 * set user profile
 * @param $userUniqueId string
 * @param $appId int
 * @param $eventParams array set profile example ["php_version"=>"1.3.0"]
 * @return mixed
 */
public function profileSet($userUniqueId, $appId, $eventParams);

/**
 * @param $userUniqueId string
 * @param $appId int
 * @param $eventParams array unset profile example ["php_version"=>""]. unset php_version
 * @return mixed
 */
public function profileUnset($userUniqueId, $appId, $eventParams);

/**
 * @param $userUniqueId string
 * @param $appId int
 * @param $eventParams array set once profile example ["php_version"=>"1.1"]. set php_version only once
 * @return mixed
 */
public function profileSetOnce($userUniqueId, $appId, $eventParams);

/**
 * @param $userUniqueId string
 * @param $appId int
 * @param $eventParams array increment profile example ["php_example"=>10]. php_example=php_example+10
 * @return mixed
 */
public function profileIncrement($userUniqueId, $appId, $eventParams);

/**
 * @param $userUniqueId string
 * @param $appId int
 * @param $eventParams array append profile example ["php_version"=>["1.1","1.2"]]. append php_version
 * @return mixed
 */
public function profileAppend($userUniqueId, $appId, $eventParams);

/**
 * @param $appId int app id
 * @param $itemName string item name
 * @param $items array item example:["item_id"=>"0001","item_name"=>"book","item_price"=>5.0]
 * @return mixed
 */
public function itemSet($appId, $itemName, $items);

/**
 * @param $appId int
 * @param $itemName string
 * @param $itemId string
 * @param $items array example: ["param1","param2","param3"]
 * @return mixed
 */
public function itemUnset($appId, $itemName, $itemId, $items);

4.1 通用用法

// 需要先初始化配置再使用,这里以saas的初始化为例子，私有化的环境下，请使用私有化的相关配置
CollectorConfig::init_datarangers_collector([
    "domain" => "https://xxxx",
    "save" => false,
    "headers" => [
        "Content-Type" => "application/json"
    ],
    // 配置 app_id => app_key, 1001 是举例的应用id，需要替换成实际的应用id
    "app_keys" => [
        1001 => getenv("APP_KEY")
    ],
    // 配置 openapi
    "openapi" => [
        "domain" => "https://xxxx",
        "ak" => getenv("OPENAPI_AK"),
        "sk" => getenv("OPENAPI_SK")
    ]
]);


$rc = new AppEventCollector();
# 上报事件
$rc->sendEvent("test-uuidsdk1", 1001, null, ["php_event"],
    [["php_name" => "php", "php_version" => "5.6"]]);

# 上报单个事件
$rc->sendEvent("test-uuidsdk1", 1001, null, "php_single_event",
    ["php_name" => "php", "php_version" => "5.6"]);

# 上报用户属性
$rc->profileSet("test-uuidsdk1", 1001, ["profile_php_name" => "php7", "profile_php_version" => "7.4", "profile_int" => 1]);

# 上报 item 属性
$rc->itemIdSet(1001, "book", "book3", ["author" => "吴承恩", "name" => "西游记", "price" => 59.90, "category" => 1]);
$rc->itemIdSet(1001, "book", "book4", ["author" => "Guanzhong Luo", "name" => "SanGuoYanYi", "price" => 69.90, "category" => 1]);

# 在事件中上报 item
$rc->sendEvent("test-uuidsdk1", 1001, null, ["php_event_with_item"],
    [["php_name" => "php", "php_version" => "5.6"]], [
        [["item_name" => "book", "item_id" => "book3"], ["item_name" => "book", "item_id" => "book4"]]
    ]);
    
# 在单个事件中上报 item
$rc->sendEvent("test-uuidsdk1", 1001, null, "php_single_event_with_item",
    ["php_name" => "php", "php_version" => "5.6"],
    [["item_name" => "book", "item_id" => "book3"], ["item_name" => "book", "item_id" => "book4"]]
);

4.2 特殊用法

// 使用 device_id 匿名上报
$header2 = new Header();
$header2->setAppId(10000000);
$header2->setUserUniqueId("");
$header2->setDeviceId(7033713549469860107);
$rc->profileSetWithHeader($header2, ["profile_php_name" => "php7", "profile_php_version" => "7.4", "profile_int" => 2, "testdate"=>"2023-05-16"]);

// 使用 anonymousId 匿名上报
$webRc = new WebEventCollector();
$header3 = new Header();
$header3->setAppId(10000000);
$header3->setUserUniqueId("");
$header3->setAnonymousId("test_anonymousId1");
$webRc->sendUserDefineEvent($header3, "", 10000000, null, "php_event_with_anonymous_id",
    ["php_name" => "php", "php_version" => "5.6", "float_param" => floatval(5), "session_id" => "1234567890"]);

// 使用 user_unique_id_type 进行多口径上报
$appRc = new AppEventCollector();
$header3 = new Header();
$header3->setAppId(10000000);
$header3->setUserUniqueIdType("phone_id");
$appRc->sendUserDefineEvent($header3, "test_sdk_phone_id1", 10000000, null, "php_event_with_anonymous_id",
    ["php_name" => "php", "php_version" => "5.6", "float_param" => floatval(5), "session_id" => "1234567890"]);

1. 生成的日志文件不会自动删除，请自行删除。
2. Saas 上用户属性需要先在系统中创建之后再上报，参考<<User Profile API (服务端-SAAS)>>
3. Item属性需要先在系统中创建之后再上报，参考<<业务对象（Item）数据接入（SAAS查看>>
4. 业务对象内置的id属性，对应的字段名称为item_id，因此不需要再定义一个 id 属性