# PHP SDK 使用指南

提示

在接入前, 请先阅读接入前准备。

您可以在 GitHub (opens new window) 获取 PHP SDK 源码。

最新版本为：1.7.0

更新时间为：2021-06-01

# 一、安装 SDK

您可以从GitHub (opens new window)中获取 SDK 的源码，并集成到您的项目中。只需要将 TaPhpSdk.php 放到你项目所在的目录即可。本 SDK 兼容 PHP >5.5，部分功能依赖 curl 扩展。
您也可以使用 composer 集成

{
    "require": {
        "thinkinggame/ta-php-sdk": "v1.6.0"
    }
}

# 二、初始化 SDK

在程序中写入以下代码引入 SDK：

<?php
require "TaPhpSdk.php";
?>

在引入 SDK 后，您需要获得 SDK 实例

//初始化SDK两种方式，Consumer包括下列(FileConsumer,BatchConsumer,DebugConsumer
//（1）默认
$ta = ThinkingDataAnalytics(Consumer);
//（2）添加UUID去重
$enableUUID = true;
$ta = new ThinkingDataAnalytics(Consumer,$enableUUID);

可以获取三种不同的 SDK 实例，建议使用FileConsumer：

(1)FileConsumer： 批量实时写本地文件，需要与 LogBus 搭配使用进行数据上传，建议使用，不支持多线程，生成实例时可通过传参调整文件切割规则。初始化 TA：

<?php
//按默认按天切分文件
$ta = new ThinkingDataAnalytics(new FileConsumer("/log_dir"));
?>

如果您想按大小切分文件，可如下初始化：

<?php
//设置文件切割的大小,单位是MB,这里设置是1024MB，文件名类似：log.日期_数值（log.2020-01-03_0），数值是文件切分的索引
$ta = new ThinkingDataAnalytics(new FileConsumer("/log_dir", 1024));
?>

如果您想按小时切分文件，可如下初始化：

<?php
//按小时切分，文件名类似：log.日期-小时_数值（log.2019-09-12-15_0）
$ta = new ThinkingDataAnalytics(new FileConsumer("/log_dir", 0, true));
?>

如果需要设置生成的日志文件前缀，可如下初始化：

<?php
//按小时切分，文件名类似：a.log.日期-小时_数值（log.2019-09-12-15_0）
$ta = new ThinkingDataAnalytics(new FileConsumer("/log_dir", 0, true,"a"));
?>

传入的第一个参数为写入本地的文件夹地址，您只需将 LogBus 的监听文件夹地址设置为此处的地址，即可使用 LogBus 进行数据的监听上传。第二个参数是文件的切割大小，默认不限制大小，单位为 MB。第三个参数设置是否按小时切分，默认为 false，即不开启。

(2)BatchConsumer： 批量实时地向 TA 服务器传输数据，不需要搭配传输工具，可设置每次最大上传数据量（默认20条）和缓存最大批次（默认50批），即默认最大缓存数据量为20*50条。在长时间网络中断情况下，有数据丢失的风险。

<?php
$ta = new ThinkingDataAnalytics(new BatchConsumer("SERVER_URI","APP_ID"));
?>

如果您想内网传输数据，可如下初始化：

<?php
$batchConsumer = new BatchConsumer("SERVER_URI","APP_ID")
//是否压缩,默认压缩gzip，如果是内网传输，推荐false
$batchConsumer -> setCompress(false);
$ta = new ThinkingDataAnalytics($batchConsumer);
?>

SERVER_URI为传输数据的 URL，APP_ID为您的项目的 APP ID

如果您使用的是云服务，请输入以下 URL:

http://receiver.ta.thinkingdata.cn

如果您使用的是私有化部署的版本，请输入以下 URL:

http://数据采集地址

注：1.2.0 版本之前输入以下 URL:

http://receiver.ta.thinkingdata.cn/logagent
http://数据采集地址/logagent

(3)DebugConsumer： 逐条实时地向 TA 服务器传输数据，不需要搭配传输工具，如果数据出现错误，整条数据都将不会入库，并且返回详细的错误说明，不建议在生产环境中使用，不支持多线程

<?php
$ta = new ThinkingDataAnalytics(new DebugConsumer("SERVER_URI","APP_ID"));
?>

如果您希望DebugConsumer只校验数据，不写入 TA 库，可如下初始化：

<?php
$debugConsumer = new DebugConsumer("SERVER_URI","APP_ID");
//debugConsumer是否写入TA库,true-写入，false-不写入。默认值为true
$debugConsumer->setDebugOnly(false);
$ta = new ThinkingDataAnalytics($debugConsumer);
?>

SERVER_URI为传输数据的 URL，APP_ID为您的项目的 APP ID

如果您使用的是云服务，请输入以下 URL:

http://receiver.ta.thinkingdata.cn

如果您使用的是私有化部署的版本，请输入以下 URL:

http://数据采集地址

# 三、发送事件

在 SDK 初始化完成之后，您就可以调用track来上传事件，一般情况下，您可能需要上传十几到上百个不同的事件，如果您是第一次使用 TA 后台，我们推荐您先上传几个关键事件。

# 3.1 发送事件

您可以调用track来上传事件，建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件，此处以用户付费作为范例：

<?php
//用户在登录状态下的账号ID
$account_id = "ABC12345";

//用户未登录时，可以使用产品自己生成的cookieId等唯一标识符来标注用户
$distinct_id = "SDIF21dEJWsI232IdSJ232d2332";

$properties = array();

//设置本条数据的时间，如不设置，则默认取当前时间，格式为"Y-m-d H:i:s"
$properties["#time"] = date("Y-m-d H:i:s",time());

//设置客户端IP，TA将会自动根据该IP地址解析其地理位置信息
$properties["#ip"] = "123.123.123.123";

//设置事件的其他属性
$properties["Product_Name"] ="商品名";
$properties["Price"] = 30;
$properties["OrderId"] ="abc_123";

//传入参数分别为，访客ID，账号ID，事件名与事件属性
try{
  $ta->track($distinct_id,$account_id,"Payment",$properties);
}catch (Exception $e){
   //异常处理
    echo $e;
}

//您可以只上传其中一个ID，SDK中其他需要上传用户ID的接口也可以只上传一个ID
//try{
//$ta->track(null,$account_id,"Payment",$properties);
//$ta->track($distinct_id,null,"Payment",$properties);
//}catch (Exception $e){
//异常处理
//echo $e;
}

?>

注：为了保证访客 ID 与账号 ID 能够顺利进行绑定，如果您的产品中会用到访客 ID 与账号 ID，我们极力建议您同时上传这两个 ID，否则将会出现账号无法匹配的情况，导致用户重复计算，具体的 ID 绑定规则可参考用户识别规则一章。

事件的名称只能以字母开头，可包含数字，字母和下划线“_”，长度最大为 50 个字符，对字母大小写不敏感。
事件的属性是一个关联数组，其中每个元素代表一个属性。
数组元素的 Key 值为属性的名称，为string类型，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为 50 个字符，对字母大小写不敏感。
数组元素的 Value 值为该属性的值，支持string、integer、float、boolean、DataTime、array

# 3.2 设置公共事件属性

对于一些需要出现在所有事件中的属性属性，您可以调用register_public_properties来设置公共事件属性，我们推荐您在发送事件前，先设置公共事件属性。

<?php
$public_properties = array();
$public_properties["server_version"] ="1.2.3";
$public_properties["server_name"] = "A1001";
$ta->register_public_properties($public_properties);
?>

在调用register_public_properties设置完公共属性后，之后上传的所有事件中都会带有这些属性

公共事件属性同样也是一个关联数组，其中每个元素代表一个属性。
数组元素的 Key 值为属性的名称，为string类型，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为 50 个字符，对字母大小写不敏感。
数组元素的 Value 值为该属性的值，支持string、integer、float、boolean、DataTime、array

如果调用register_public_properties设置先前已设置过的公共事件属性，则会覆盖之前的属性值，以新设置的公共属性为准。如果公共事件属性和track上传事件中的某个属性的 Key 重复，则该事件的属性会覆盖公共事件属性，即以上传事件时的属性为准。

如果您想要清空所有公共事件属性，可以调用clear_public_properties。

<?php
$ta->clear_public_properties();
?>

# 四、用户属性

TA 平台目前支持的用户属性设置接口为 user_set、user_setOnce、user_add、user_del。

# 4.1 user_set

对于一般的用户属性，您可以调用user_set来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建并写入该用户属性，属性类型与传入时的类型一致：

<?php
$properties = array();

//上传用户属性，新建属性"user_name"，值为"ABC"
$properties["user_name"] = "ABC";
try{
  $ta->user_set($distinct_id,$account_id,$properties);
}catch (Exception $e){
   //异常处理
    echo $e;
}
//再次上传用户属性，此时"user_name"的值会被覆盖为"XYZ"
$properties["user_name"] = "XYZ";
try{
  $ta->user_set($distinct_id,$account_id,$properties);
}catch (Exception $e){
   //异常处理
    echo $e;
}
?>

user_set设置的用户属性是一个关联数组，其中每个元素代表一个属性。
数组元素的 Key 值为属性的名称，为string类型，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为 50 个字符，对字母大小写不敏感。
数组元素的 Value 值为该属性的值，支持支持string、integer、float、boolean、DataTime、array

# 4.2 user_setOnce

如果您要上传的用户属性只要设置一次，则可以调用user_setOnce来进行设置，当该属性之前已经有值的时候，将会忽略这条信息：

<?php
$properties = array();

//同样的，上传用户属性，新建属性"user_name"，值为"ABC"
$properties["user_name"] = "ABC";
try{
  $ta->user_setOnce($distinct_id,$account_id,$properties);
}catch (Exception $e){
   //异常处理
    echo $e;
}

//再次上传用户属性，此时"user_name"已存在值，因此不进行修改，仍为"ABC"；"user_age"的值为18
$properties["user_name"] = "XYZ";
$properties["user_age"] = 18;
try{
  $ta->user_setOnce($distinct_id,$account_id,$properties);
}catch (Exception $e){
   //异常处理
    echo $e;
}
?>

user_setOnce设置的用户属性类型及限制条件与user_set一致。

# 4.3 user_add

当您要上传数值型的属性时，您可以调用user_add来对该属性进行累加操作，如果该属性还未被设置，则会赋值 0 后再进行计算，可传入负值，等同于相减操作。

<?php

//上传用户属性，此时"total_revenue"的值为30,"vip_level"的值为1
$properties = array();
$properties["total_revenue"] = 30;
$properties["vip_level"] = 1;
try{
  $ta->user_add($distinct_id,$account_id,$properties);
}catch (Exception $e){
   //异常处理
    echo $e;
}

//再次上传用户属性，此时"total_revenue"的值为90,"vip_level"的值为1
$properties_other = array();
$properties_other["total_revenue"] = 60;
try{
  $ta->user_add($distinct_id,$account_id,$properties_other);
}catch (Exception $e){
   //异常处理
    echo $e;
}
?>

user_add设置的用户属性类型及限制条件与user_set一致，但只对数值型的用户属性有效。

# 4.4 user_append

当您要为 array 类型追加用户属性值时，您可以调用user_append来对指定属性进行追加操作，如果该属性还未在集群中被创建，则user_append创建该属性

<?php
//user_append 追加一个用户的某一个或者多个集合
try{
    $properties = array();
    $properties['arr'] = ['str3','str4'];//为集合类型追加多个值，key-array形式，array里面都是字符串类型
    $ta->user_append($distinct_id, $account_id, $properties);
}catch (Exception $e){
    //handle except
    echo $e;
}
?>

# 4.5 user_del

如果您要删除某个用户，可以调用user_del将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到

<?php
try{
  $ta->user_del($distinct_id,$account_id);
}catch (Exception $e){
   //异常处理
    echo $e;
}
?>

# 4.6 user_unset

当您要清空用户的用户属性值时，您可以调用user_unset来对指定属性进行清空操作，如果该属性还未在集群中被创建，则user_unset不会创建该属性

<?php
$properties = array(
    'user_age', "vip_level"
);
try{
 $ta->user_unset($distinct_id,$account_id, $properties);
}catch (Exception $e){
   //异常处理
    echo $e;
}
?>

# 五、其他操作

# 5.1 立即提交数据

<?php
$ta->flush();
?>

立即提交数据到相应的接收器

# 5.2 关闭 sdk

<?php
try{
  $ta->close();
}catch (Exception $e){
   //异常处理
    echo $e;
}
?>

关闭并退出 sdk，请在关闭服务器前调用本接口，以避免缓存内的数据丢失

# 六、相关预置属性

# 6.1 所有事件带有的预置属性

以下预置属性，是 PHP SDK 中所有事件（包括自动采集事件）都会带有的预置属性

属性名	中文名	说明
#ip	IP 地址	用户的 IP 地址，需要进行手动设置，TA 将以此获取用户的地理位置信息
#country	国家	用户所在国家，根据 IP 地址生成
#country_code	国家代码	用户所在国家的国家代码(ISO 3166-1 alpha-2，即两位大写英文字母)，根据 IP 地址生成
#province	省份	用户所在省份，根据 IP 地址生成
#city	城市	用户所在城市，根据 IP 地址生成
#lib	SDK 类型	您接入 SDK 的类型，如 PHP 等
#lib_version	SDK 版本	您接入 PHP SDK 的版本

# 七、其他功能

# 7.1 指定文件前缀

从 v1.5.0 开始，SDK 的 FileConsumer 支持指定生成的文件前缀，并且指定的目录不存在时将会自动创建，使用方法如下：

<?php
// 最后一个参数即为指定的文件前缀，生成的文件名为：test.log.2020-12-07
$debugConsumer = new FileConsumer("/Users/sunzeyu/Work/test/test/", 0, false, "test");
$ta = new ThinkingDataAnalytics($debugConsumer);
?>

# 八、进阶功能

从 v1.4.0 开始，SDK 支持上报两种特殊类型事件: 可更新事件、可重写事件。这两种事件需要配合 TA 系统 2.8 及之后的版本使用。由于特殊事件只在某些特定场景下适用，所以请在数数科技的客户成功和分析师的帮助下使用特殊事件上报数据。

# 8.1 可更新事件

您可以通过可更新事件实现特定场景下需要修改事件数据的需求。可更新事件需要指定标识该事件的 ID，并在创建可更新事件对象时传入。TA 后台将根据事件名和事件 ID 来确定需要更新的数据。

$account_id = "2121";
$distinct_id = "SJ232d233243";
try{
// 示例： 上报可被更新的事件，假设事件名为 UPDATABLE_EVENT
$event_name = "UPDATABLE_EVENT";
$event_id = "test_event_id";
$properties = array();
$properties['price'] = 100;
$properties['status'] = 3;
// 上报后事件属性 status 为 3, price 为 100
$ta->track_update($distinct_id, $account_id,$event_name, $event_id,$properties);

$protertiesNew = array();
$protertiesNew['status'] = 5;
// 上报后同样 $event_name + $event_id 的事件属性 status 被更新为 5, price 不变
$ta->track_update($distinct_id, $account_id, $event_name, $event_id, $protertiesNew);

$ta->flush();
}catch (Exception $e){
    //handle except
    echo $e;
}

# 8.2 可重写事件

可重写事件与可更新事件类似，区别在于可重写事件会用最新的数据完全覆盖历史数据，从效果上看相当于删除前一条数据，并入库最新的数据。TA 后台将根据事件名和事件 ID 来确定需要更新的数据。

$account_id = "2121";
$distinct_id = "SJ232d233243";
try{
// 示例： 上报可被重写的事件，假设事件名为 OVERWRITE_EVENT
$event_name = "OVERWRITE_EVENT";
$event_id = "test_event_id";
$properties = array();
$properties['price'] = 100;
$properties['status'] = 3;
// 上报后事件属性 status 为 3, price 为 100
$ta->track_overwrite($distinct_id, $account_id,$event_name, $event_id,$properties);

$protertiesNew = array();
$protertiesNew['status'] = 5;
// 上报后同样$event_name + $event_id  的事件属性 上报后事件属性 status 被更新为 5, price 属性被删除
$ta->track_overwrite($distinct_id, $account_id, $event_name, $event_id, $protertiesNew);

$ta->flush();
}catch (Exception $e){
    //handle except
    echo $e;
}

# ChangeLog

v1.7.0 (2021/06/01)

修复公共属性覆盖的bug
修复user_del()方法无法调用的问题

v1.6.0 (2021/03/12)

BatchConsumer 增加上传失败缓存

v1.5.0 (2020/12/07)

LoggerConsumer 增加指定目录不存在时自动创建
LoggerConsumer 增加文件锁配置
LoggerConsumer 增加指定生成文件前缀

v1.4.0 (2020/08/27)

新增 track_update 接口，支持可更新事件
新增 track_overwrite 接口，支持可重写事件
新增 UUID 初始化方式

v1.3.0 (2020/02/10)

支持 array 类型
新增 user_append 接口，支持用户的数组类型的属性追加

v1.2.1 (2020/01/15)

修复 v1.1.1#time 精确毫秒时出现的格式不正确

v1.2.0 (2020-01-03)

新增 user_unset 接口，支持删除用户属性
LoggerConsumer 优化：增加稳定性，去除默认文件大小 1G 上限. 用户可自行配置按天，小时，大小切分
DebugConsumer 优化: 在服务端对数据进行更完备准确地校验
BatchConsumer 性能优化：支持配置压缩模式；移除 Base64 编码

v1.1.1 (2019/12/05)

支持#time 精确到毫秒

v1.1.0 (2019/09/12)

支持 DebugConsumer
支持日志文件按小时切分

v1.0.4 (2019/09/04)

修复 BatchConsumer 的错误返回码
添加 BatchConsumer 析构函数

v1.0.3 (2019/08/30)

新增按文件大小切分文件功能.

← Node.js SDK 使用指南 Python SDK 使用指南 →