PHP SDK 使用指南

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

**最新版本为:**1.3.0

更新时间为: 2020-02-10

注意：1.1.1 版本，1.2.0 版本可能会出现极少量数据不上报的 bug，建议使用最新版本

## 1. 安装 SDK

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

• 您也可以使用 composer 集成

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

2. 初始化 SDK

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

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

在引入 SDK 后，您需要获得 SDK 实例，可以获取三种不同的 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://数据采集地址

注：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
$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 中所有事件（包括自动采集事件）都会带有的预置属性

属性名	中文名	说明
#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 的版本