You need to enable JavaScript to run this app.
导航

PHP SDK

最近更新时间2023.09.06 21:25:53

首次发布时间2022.08.03 10:10:15

1.使用说明:

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.配置初始化

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,具体的参数为

模式参数名是否为必须说明
Http模式saveHttp模式下为false
domainDataRangers的域名或ip,支持http和https
headersHttp的header头。私有化需要配置Host,Host 为私有化环境Host的配置在安装部署的那台机器上,查看/home/{INSTALL_USER}/DataRangersDeploy/conf_rangers.yml中配置项sdk.report.host。 INSTALL_USER 为安装用户,一般是datarangers或者minibase。Host 注意没有 http://,https:// ,一般为 sdk 上报的域名去掉http://,https://
http_timeoutHttp请求超时时间,单位为毫秒。默认为1000
LogAgent模式saveLogAgent模式下为true,只支持私有化
logger_file_prefix日志存储路径
logger_file_name日志存储文件名
log_max_bytes日志的最大大小,超过该值日志会进行切分
3.接口说明

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.使用样例
// 需要先初始化配置再使用,这里以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"]]
);
5.注意事项
  1. 生成的日志文件不会自动删除,请自行删除。

  2. Saas 上用户属性需要先在系统中创建之后再上报,参考<<User Profile API (服务端-SAAS)>>

  3. Item属性需要先在系统中创建之后再上报,参考<<业务对象(Item)数据接入(SAAS查看>>

  4. 业务对象内置的id属性,对应的字段名称为item_id,因此不需要再定义一个 id 属性