1. PHP SDK 使用说明

在使用前,请先阅读 数据模型 的介绍。

1.1. 集成神策分析 SDK

在 PHP 脚本中集成 神策分析 SDK ,使用神策分析采集并分析用户数据。SDK 最低兼容 PHP 5.X,部分功能依赖 curl 扩展。有两种集成方式:

使用 composer 集成。

{
	"require": {
		"sensorsdata/sa-sdk-php": "v1.10.5"
	}
}
JS

直接从 GitHub  获取 SDK 的源码并集成到项目中。

1.2. 初始化神策分析 SDK

1.2.1. 获取配置信息

首先从神策分析的主页中,获取数据接收的 URL 和 Token(Cloud 版)。

如果使用神策分析 Cloud 服务,需获取的配置信息为:

数据接收地址,建议使用不带端口号的: http://{$service_name}.datasink.sensorsdata.cn/sa?project={$project_name}&token={$project_token}
数据接收地址,带端口号的: http://{$service_name}.cloud.sensorsdata.cn:8106/sa?project={$project_name}&token={$project_token}


如果用户使用单机版私有部署的神策分析,默认的配置信息为:

数据接收地址: http://{$host_name}:8106/sa?project={$project_name}(注:神策分析 1.7 及之前的版本,单机版私有部署默认端口号为 8006)


如果用户使用集群版私有部署的神策分析,默认的配置信息为:

数据接收地址: http://{$host_name}:8106/sa?project={$project_name}


其中 {$host_name} 可以是集群中任意一台机器。

如果私有部署的过程中修改了 Nginx 的默认配置,或通过 CDN 等访问神策分析,则请咨询相关人员获得配置信息。

1.2.2. 在程序中初始化 SDK

在程序中初始化的代码段中构造神策分析 SDK 的实例:

<?php
	require_once("SensorsAnalytics.php");

	# 从神策分析配置页面中获取的数据接收的 URL
	$SA_SERVER_URL = 'YOUR_SERVER_URL';

	# 初始化一个 Consumer,用于数据发送
	# BatchConsumer 是同步发送数据,因此不要在任何线上的服务中使用此 Consumer
	$consumer = new BatchConsumer($SA_SERVER_URL);
	# 使用 Consumer 来构造 SensorsAnalytics 对象
	$sa = new SensorsAnalytics($consumer);
	# 支持在构造SensorsAnalytics对象时指定project, 后续所有通过这个SensorsAnalytics对象发送的数据都将发往这个project
	# $sa = new SensorsAnalytics($consumer, "project_name");

	# 记录用户登录事件
	$distinct_id = 'ABCDEF123456789';
	$sa->track($distinct_id, true, 'UserLogin');

	$sa->close();
?>
PHP


其中 YOUR_SERVER_URL 是前文中从神策分析获取的数据接收的 URL。用户程序应该一直持有该实例,直到程序结束。程序退出前,需要使用 `close()` 方法显式关闭,否则可能丢失部分缓存的数据。

至此,我们已经可以正常使用神策分析 SDK 了。需了解更多关于 SDK 的使用方法,可以跳到本文末尾的 设置神策分析 SDK 一节。

1.3. 追踪事件

第一次接入神策分析时,建议先追踪 3~5 个关键的事件,只需要几行代码,便能体验神策分析的分析功能。例如:

图片社交产品,可以追踪用户浏览图片和评论事件
电商产品,可以追踪用户注册、浏览商品和下订单等事件


用户通过 track() 接口记录事件,对于任何事件,必须包含用户标志符distinct_id)、用户标识是否为登录 ID (is_login_id)和事件名event_name)这三个参数。同时,用户可以在 track() 的第四个参数传入一个 object 对象,为事件添加自定义事件属性。以电商产品为例,可以这样追踪一次购物行为:

<?php
	$distinct_id = 'ABCDEF123456789';

	$properties = array(
		# '$time' 属性是系统预置属性,传入毫秒表示的 Timestamp,表示事件发生的时间,如果不填入该属性,则默认使用系统当前时间
		'$time' => (int)(microtime(true) * 1000), # 对于windows用户需要这样定义 '$time' => substr((microtime(true) * 1000), 0, 13)
		# '$ip' 属性是系统预置属性,如果服务端中能获取用户 IP 地址,并填入该属性,神策分析会自动根据 IP 地址解析用户的省份、城市信息
		'$ip' => '123.123.123.123',
		# 商品 ID
		'ProductId' => '123456',
		# 商品类别
		'ProductCatalog' => 'Laptop Computer',
		# 是否加入收藏夹,Boolean 类型的属性
		'IsAddedToFav' => true,
	);

	# 记录用户浏览商品事件
	$sa->track($distinct_id, true, 'ViewProduct', $properties);

	$properties = array(
		# 用户 IP 地址
		'$ip' => '123.123.123.123',
		# 商品 ID 列表,list<str> 类型的属性
		'ProductIdList' => array('123456', '234567', '345678'),
		# 订单价格
		'OrderPaid' => 12.10,
	);

	# 记录用户订单付款事件
	$sa->track($distinct_id, true, 'PaidOrder', $properties);
?>
PHP


1.3.1. 事件属性

如前文中的样例,追踪的事件可以设置自定义的事件属性,例如浏览商品事件中,将商品 ID、商品分类等信息作为事件属性。在后续的分析工作中,事件属性可以作为统计过滤条件使用,也可以作为维度进行多维分析。对于事件属性,神策分析有一些约束:

事件属性是一个 array 对象
array 中每个元素描述一个属性,Key 为属性名称,必需是 string 类型
array 中,每个元素的 Value 是属性的值,支持 string、int、float、array 和 DateTime


对于神策分析中事件属性的更多约束,请参考 数据格式

1.3.1.1. 系统预置属性

如前文中样例,事件属性中以 '$' 开头的属性为系统预置属性,在自定义事件属性中填入对应 '$' 开头的属性值可以覆盖这些预置属性:

$ip - 填入该属性,神策分析会自动根据 IP 地址解析用户的省份、城市信息,该属性值为 string 类型;
$time - 填入该属性,神策分析将事件时间设置为属性值的时间,该属性值必须为 DateTime 类型。请注意,神策分析默认会过滤忽略 365 天前或 3 天后的数据,如需修改请联系我们。


关于其他更多预置属性,请参考 数据格式 中 '预置属性' 一节。

1.3.1.2. 事件公共属性

特别地,如果某个事件的属性,在所有事件中都会出现,可以通过 register_super_properties() 将该属性设置为事件公共属性。例如将服务器的应用版本及机房地址设置为事件的公共属性,设置方法如下:

<?php
	$properties = array(
		# 服务器应用版本
		'ServerVersion' => '1.2',
		# 服务器机房地址
		'Location' => 'BeiJing',
	);

	# 设置事件公共属性
	$sa->register_super_properties($properties);
?>
PHP


成功设置事件公共属性后,再通过 track() 追踪事件时,事件公共属性会被添加进每个事件中。

使用 clear_super_properties() 会删除所有已设置的事件公共属性。

当事件公共属性和事件属性的 Key 冲突时,事件属性优先级最高,它会覆盖事件公共属性。

1.4. 用户识别

在服务端应用中,神策分析也要求为每个事件设置用户的 Distinct Id,这有助于神策分析提供更准确的留存率等数据。

对于注册用户,推荐使用系统中的用户 ID 作为 Distinct Id,不建议使用用户名、Email、手机号码等可以被修改的信息。

所有的 track 和 profile 系列方法都必须同时指定用户 ID 及用户 ID 是否为登录 ID 这两个参数,以便明确告知神策分析用户 ID 的类型。

1.4.1. 用户注册/登录

当同一个用户的 Distinct Id 发生变化时(一般情况为匿名用户注册行为),可以通过 track_signup() 将旧的 Distinct Id 和新的 Distinct Id 关联,以保证用户分析的准确性。例如:

<?php
	$anonymous_id = '9771C579-71F0-4650-8EE8-8999FA717761';# 匿名 ID 由前端传过来
	$register_id = '0012345678';
	# 用户注册/登录时,将用户注册 ID 与 匿名 ID 关联
	$sa->track_signup($register_id, $anonymous_id);
?>
PHP


注意,对同一个用户,track_signup() 一般情况下建议只调用一次(通常在用户 注册 时调用),用户 登录 前后的行为的关联建议在业务端实现。在神策分析 1.13 版本之前,多次调用 track_signup() 时,只有第一次关联行为是有效的。神策分析 1.13 版本之后提供了多设备 id 关联的方法。更详细的说明请参考 2019-12-03_22-18-28_如何准确的标识用户,并在必要时联系我们的技术支持人员。

1.5. 设置用户属性

为了更准确地提供针对人群的分析服务,神策分析 SDK 可以设置用户属性,如年龄、性别等。用户可以在留存分析、分布分析等功能中,使用用户属性作为过滤条件或以用户属性作为维度进行多维分析。

使用 profile_set() 设置用户属性:

<?php
	$distinct_id = 'ABCDEF123456789';

	$properties = array(
		# 用户性别属性(Sex)为男性
		'Sex' => 'Male',
		# 用户等级属性(Level)为 VIP
	'UserLevel' => 'Elite VIP',
);

	# 设置用户属性
	$sa->profile_set($distinct_id, true, $properties);
?>
PHP


对于不再需要的用户属性,可以通过 `profile_unset()` 接口将属性删除。

用户属性中,属性名称与属性值的约束条件与事件属性相同,详细说明请参考 数据格式

1.5.1. 记录初次设定的属性

对于只在首次设置时有效的属性,我们可以使用 profile_set_once() 记录这些属性。与 profile_set() 接口不同的是,如果被设置的用户属性已存在,则这条记录会被忽略而不会覆盖已有数据>,如果属性不存在则会自动创建。因此,profile_set_once() 比较适用于为用户设置首次激活时间、首次注册时间等属性。例如:

<?php
	$distinct_id = 'ABCDEF123456789';

	# 设置用户渠道属性(AdSource)为 "App Store"
	$sa->profile_set_once($distinct_id, true, array('AdSource' => 'App Store'));

	# 再次设置用户渠道属性(AdSource),设定无效,属性 "AdSource" 的值仍为 "App Store"
	$sa->profile_set_once($distinct_id, true, array('AdSource' => 'Search Engine'));
?>
PHP


1.5.2. 数值类型的属性

对于数值型的用户属性,可以使用 profile_increment() 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。例如:

<?php
	$distinct_id = 'ABCDEF123456789';

	# 设置用户游戏次数属性(GamePlayed),将次数累加1次
	$sa->profile_increment($distinct_id, true, array('GamePlayed' => 1));
?>
PHP


1.5.3. 列表类型的属性

对于用户喜爱的电影、用户点评过的餐厅等属性,可以记录列表型属性。需要注意的是,列表型属性中的元素必须为 string 类型,且元素的值会自动去重。关于列表类型限制请见 数据格式

<?php
	$distinct_id = 'ABCDEF123456789';

	$properties = array(
		# 电影列表
		'Movies' => array('Sicario', 'Love Letter'),
		# 游戏列表
		'Games' => array('Call of Duty', 'Halo'),
	);

	# 传入properties,设置用户喜欢的电影属性(movies)和喜欢的游戏属性(games)
	# 设置成功后,"Movies" 属性值为 ["Sicario", "Love Letter"];"Games" 属性值为 ["Call of Duty", "Halo"]
	$sa->profile_append($distinct_id, true, $properties);

	# 传入属性名称和需要插入属性的值,设置用户喜欢的电影属性(Movies)
	# 设置成功后 "Movies" 属性值为 ["Sicario", "Love Letter", "Dead Poets Society"]
	$sa->profile_append($distinct_id, true, array('Movie' => array('Dead Poets Society')));

	# 传入属性名称和需要插入属性的值,设置用户喜欢的电影属性(Movies),
	# 但属性值 "Love Letter" 与已列表中已有元素重复,操作无效,
	# "Movies" 属性值仍然为 ["Sicario", "Love Letter", "Dead Poets Society"]
	$sa->profile_append($distinct_id, true, array('Movie' => array('Love Letter')));
?>
PHP


1.6. 物品元数据上报

在神策推荐项目中,客户需要将物品元数据上报,以开展后续推荐业务的开发与维护。神策分析SDK提供了设置与删除物品元数据的方法。

item_id(物品 ID )item_type (物品所属类型)共同组成了一个物品的唯一标识。所有的 item 系列方法都必须同时指定物品 ID 及物品所属类型这两个参数,来完成对物品的操作。

1.6.1. 设置物品

直接设置一个物品,如果已存在则覆盖。除物品 ID 与 物品所属类型外,其他物品属性需在 $properties 中定义。

物品属性中,属性名称与属性值的约束条件与事件属性相同,详细说明请参考 数据格式

<?php
	function item_set($item_type, $item_id, $properties = array())

	# 例如
	$item_type = 'fruit';
	$item_id = 'ABCDEF123456789';
	$sa->item_set($item_type, $item_id, array('apple' => 1));
?>
PHP


1.6.2. 删除一个物品

如果物品不可被推荐需要下线,删除该物品即可,如不存在则忽略。

除物品 ID 与 物品所属类型外,不解析其他物品属性。

<?php
	function item_delete($item_type, $item_id, $properties = array())

	#例如:
	$item_type = 'fruit';
	$item_id = 'ABCDEF123456789';
	$sa->item_delete($item_type, $item_id, null);
?>
PHP


1.7. 设置神策分析 SDK

PHP SDK 主要由以下两个组件构成:

SensorsAnalytics: 用于发送数据的接口对象,构造函数需要传入一个 Consumer 实例。
Consumer: Consumer 会进行实际的数据发送


为了让开发者更灵活的接入数据,神策分析 SDK 实现了以下 Consumer:

FileConsumer: 将待发送的数据写入指定的本地文件,后续可以使用 LogAgent 或者 BatchImporter 来进行导入。

<?php
	require_once("SensorsAnalytics.php");
	# 初始化一个 Consumer,用于数据发送
	$consumer = new FileConsumer("sa.log." . date('Y-m-d'));
	# 使用 Consumer 来构造 SensorsAnalytics 对象
	$sa = new SensorsAnalytics($consumer);

	# 程序结束前调用 close() ,通知 Consumer 发送所有缓存数据
	$sa->close();
?>
PHP


BatchConsumer: 通常用于导入小规模历史数据,或者离线 / 旁路导入数据的场景。由于是网络直接发送数据,如果网络出现异常可能会导致数据重发或丢失,因此不要用在任何线上服务中 。使用 CURL 批量发送数据的 Consumer,当且仅当数据达到指定的量时,才将数据进行发送。

<?php
	require_once("SensorsAnalytics.php");

	# 从神策分析配置页面中获取的数据接收的 URL
	$SA_SERVER_URL = 'YOUR_SERVER_URL';
	# 可选参数,当缓存的数据量达到参数值时,批量发送数据
	$SA_BULK_SIZE = 100;
	# 可选参数,发送数据的超时时间,单位毫秒
	$SA_REQUEST_TIMEOUT = 100000;

	# 初始化一个 Consumer,用于数据发送
	# BatchConsumer 是同步发送数据,因此不要在任何线上的服务中使用此 Consumer
	$consumer = new BatchConsumer($SA_SERVER_URL, $SA_BULK_SIZE, $SA_REQUEST_TIMEOUT);
	# 使用 Consumer 来构造 SensorsAnalytics 对象
	$sa = new SensorsAnalytics($consumer);

	# 程序结束前调用 close() ,通知 Consumer 发送所有缓存数据
	$sa->close();
?>
PHP


DebugConsumer: 用于校验数据导入是否正确,关于 调试模式 的详细信息,请进入相关页面查看。

请注意:Debug 模式是为方便开发者调试而设置的模式,该模式会逐条校验数据并在校验失败时抛出异常,性能远低于正常模式。线上环境使用 Debug 模式会严重影响性能并存在崩溃风险,产品上线前请务必替换掉/关闭 Debug 模式。

<?php
	require_once("SensorsAnalytics.php");

	# 从神策分析配置页面中获取的数据接收的 URL
	$SA_SERVER_URL = 'YOUR_SERVER_URL';
	# 可选参数,Debug 模式下,是否将数据导入神策分析
	# True - 校验数据,并将数据导入到神策分析中
	# False - 校验数据,但不进行数据导入
	$SA_DEBUG_WRITE_DATA = True;
	# 可选参数,发送数据的超时时间,单位毫秒
	$SA_REQUEST_TIMEOUT = 100000;

	# 初始化一个 Consumer,用于数据发送
	$consumer = new DebugConsumer($SA_SERVER_URL, $SA_DEBUG_WRITE_DATA, $SA_REQUEST_TIMEOUT);
	# 使用 Consumer 来构造 SensorsAnalytics 对象
	$sa = new SensorsAnalytics($consumer);
?>
PHP