# PHP

提示

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

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

最新版本：2.0.0

更新时间：2022-05-09

# 一、集成SDK

使用 composer 集成

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

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

安装Logbus

我们推荐使用SDK+LogBus的形式，完成服务端数据的采集上报.您可以参考以下文档完成Logbus的安装:LogBus使用指南

# 二、初始化

以下是SDK初始化的示例代码:

require "TaPhpSdk.php";
$ta = new ThinkingDataAnalytics(new FileConsumer(LOG_DIRECTORY));

LOG_DIRECTORY为写入本地的文件夹地址。您只需将 LogBus 的监听文件夹地址设置为此处的地址，即可使用 LogBus 进行数据的监听上传。

# 三、常用功能

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

# 3.1 发送事件

您可以调用track来上传事件，建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件，以下是发送事件的示例代码:

//用户在登录状态下的账号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;
}

事件的名称是字符串类型，只能以字母开头，可包含数字，字母和下划线 "_"，长度最大为 50 个字符。
Key 为该属性的名称，为字符串类型，规定只能以字母开头，包含数字，字母和下划线 "_"，长度最大为 50 个字符，对字母大小写不敏感,TA会统一转化为小写字母
Value 为该属性的值，支持字符串、数字、布尔、时间、对象、对象组、数组

用户属性的要求与事件属性保持一致

# 3.2 设置用户属性

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

$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;
}

# 四、最佳实践

以下示例代码包含以上所有操作，我们推荐按照如下步骤使用:

require "TaPhpSdk.php";
$ta = new ThinkingDataAnalytics(new FileConsumer(LOG_DIRECTORY));

//用户在登录状态下的账号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;
}

$user_properties = array();

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

//调用flush接口数据会立即写入文件，生产环境注意避免频繁调用flush引发IO或网络开销问题
$ta->flush();