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，仅SaaS-非云原生版需要配置，SaaS-云原生和私有化版本无需配置
    "openapi" => [
        "domain" => "https://xxxx",
        "ak" => getenv("OPENAPI_AK"),
        "sk" => getenv("OPENAPI_SK")
    ]
]);

配置说明

• domain，根据接入的环境配置不同的地址：

  • SaaS-非云原生版国内站: https://mcs.ctobsnssdk.com
  • SaaS-非云原生版国际站: https://mcs.tobsnssdk.com
  • SaaS-云原生版：https://gator.volces.com

• SaaS环境只支持save为false的

• app_keys， 应用的APP Key。
  在开始集成前，首先需要在集团中拥有一个应用，进行SDK集成前，您需要获取对应应用的appid信息。

  • SaaS-云原生场景下，您可以在「项目中心」->「项目管理」->「项目详情」-> 接入应用的「详情」->「应用ID」中可查看您的appid，详情请参见项目管理。
    
  • SaaS-非云原生场景下，您可以在「应用列表」-> 接入应用的「详情」->「应用ID」中可查看您的appid，详情请参见应用列表。
    

• SAAS-非云原生环境，如果需要上报 item 和用户属性，需要设置openapi；SaaS-云原生版无需设置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" => [
        "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 应用id
 * @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);

设置用户属性

/**
 * 功能描述: 设置用户的属性
 * @param $userUniqueId string 用户uuid
 * @param $appId int  应用id
 * @param $eventParams array 需要设置的用户属性 example ["php_version"=>"1.3.0"]
 * @return mixed
 */
public function profileSet($userUniqueId, $appId, $eventParams);

删除用户的属性

/**
 * 功能描述: 删除用户的属性
 * @param $userUniqueId string
 * @param $appId int
 * @param $eventParams array 需要删除的用户属性 example ["php_version"=>""]. unset php_version
 * @return mixed
 */
public function profileUnset($userUniqueId, $appId, $eventParams);

设置用户属性（set once）

/**
 * 功能描述: 设置用户属性，存在则不设置，不存在则创建，适合首次相关的用户属性，比如首次访问时间等。
 * @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);

设置用户属性（Increment）

/**
 * 功能描述: 设置数值类型的用户属性，可进行累加
 * @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);

设置用户属性（append）

/**
 * 功能描述: 设置用户属性，可持续添加用户属性
 * @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);

设置业务对象（item）

/**
 * 功能描述: 对业务对象进行设置
 * @param $appId int app id
 * @param $itemName string 业务对象的名称
 * @param $items array 业务对象的类，需要继承Items类,注意 example:["item_id"=>"0001","item_name"=>"book","item_price"=>5.0]
 * @return mixed
 */
public function itemSet($appId, $itemName, $items);

删除业务对象（item）

/**
 * 功能描述: 删除item的属性
 * @param $appId int
 * @param $itemName string
 * @param $itemId string
 * @param $items 需要删除的item属性 example: ["param1","param2","param3"]
 * @return mixed
 */
public function itemUnset($appId, $itemName, $itemId, $items);

设置用户属性（WithHeader）

/**
 * set user profile
 * @param $header Header
 * @param $eventParams array set profile example ["php_version"=>"1.3.0"]
 * @return mixed
 */
public function profileSetWithHeader($header, $eventParams);

删除用户属性（WithHeader）

/**
 * @param $header Header
 * @param $eventParams array unset profile example ["php_version"=>""]. unset php_version
 * @return mixed
 */
public function profileUnsetWithHeader($header, $eventParams);

设置用户属性（SetOnceWithHeader）

/**
 * @param $header Header
 * @param $eventParams array set once profile example ["php_version"=>"1.1"]. set php_version only once
 * @return mixed
 */
public function profileSetOnceWithHeader($header, $eventParams);

设置用户属性（IncrementWithHeader）

/**
 * @param $header Header
 * @param $eventParams array increment profile example ["php_example"=>10]. php_example=php_example+10
 * @return mixed
 */
public function profileIncrementWithHeader($header, $eventParams);

设置用户属性（AppendWithHeader）

/**
 * @param $header Header
 * @param $eventParams array append profile example ["php_version"=>["1.1","1.2"]]. append php_version
 * @return mixed
 */
public function profileAppendWithHeader($header, $eventParams);

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属性

# 上报 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

# 在事件中上报 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

# 在单个事件中上报 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 匿名上报

// 使用 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 匿名上报

// 使用 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 进行多口径上报

// 使用 user_unique_id_type 进行多口径上报，版本要求： >= 1.0.12
$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 属性