PHP SDK使用指南

本指南将会为您介绍如何使用PHP SDK接入您的项目，您可以在访问GitHub获取PHP SDK的源代码。

最新版本为：1.4.0

更新时间为：2020-08-27

1. 安装SDK

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

• 您也可以使用 composer 集成

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

2. 初始化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));
?>

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

(2)BatchConsumer：批量实时地向TA服务器传输数据，不需要搭配传输工具，不建议在生产环境中使用，不支持多线程

<?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://数据采集地址

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
$debugConsumer->setDebugOnly(false);
$ta = new ThinkingDataAnalytics($debugConsumer);
?>

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

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

http://receiver.ta.thinkingdata.cn

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

http://数据采集地址

3. 发送事件

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

a) 发送事件

您可以调用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

b) 设置公共事件属性

对于一些需要出现在所有事件中的属性属性，您可以调用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();
?>

3. 用户属性

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

a) 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

b) 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一致。

c) 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一致，但只对数值型的用户属性有效。

d) 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;
}
?>

e) user_del

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

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

f) 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;
}
?>

4. 其他操作

a) 立即提交数据

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

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

b) 关闭sdk

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

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

5. 相关预置属性

5.1 所有事件带有的预置属性

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

6. 进阶功能

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

6.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();
$properties['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;
}

6.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();
$properties['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.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)

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