README

Segment.io 是一个强大的平台，可以将所有分析集成到一个易于使用的 API 中。您可以将 GTM 和 Google Universal Analytics 等内容从 Zendesk 和 Uservoice 等内容附加到 Segment.io 账户，并开始一次性将数据推送到所有内容。这就像为分析而设的 Bit API Hub。

Segment.io for FuelPHP 通过提供统一的 PHP 体验，帮助简化了 PHP 开发者客户端/服务器端库。您可以根据您要完成的事情调用服务器端和客户端（浏览器）端函数，而无需单独集成 Analytics.js。由于 Analytics.js 库是此包的要求，您仍然可以在 UX 中调用 Analytics.js，用于点击事件或其他服务器端无法访问的需求。

有关 Segment.io 分析系统的最佳实践，请参阅 Segment.io 的文档。

Segment.io for FuelPHP 为您的公司提供了以下优势。

• 您的程序员需要编写的代码更少。
• 提供统一的客户端/服务器端包
• "一次编写" 方法（见下文 "使用"）
• Bit API Hub 使用此相同的包来跟踪我们的操作。
• 在 "注意事项" 部分查看我们为您处理的特殊问题，这些问题在处理 Segment.io 时可能并不明显。
• Segment.io for FuelPHP 是一个以 analytics.js 为首的包，因为 analytics.js 更灵活，因此通常更准确。

先决条件

• PHP 5.3.3+
• FuelPHP 1.7.2（可能与其他版本兼容，但当前只支持 1.7.2 版本。）
• 一个 Segment.io 账户

安装和配置

1. 编辑您的 FuelPHP 根目录中的 composer.json 文件，并在 "require" 部分添加以下行。 "bitapihub/fuelphp-segment-io": "master"
2. 如 Segment.io 文档中所述安装 Analytics.js 代码。在代码片段中将 "flush" 令牌添加到 analytics.methods 列表。如果您打算使用调试模式，请确保将 "debug" 令牌也添加到列表中。
3. 将 segment/config/segment.php 配置文件复制到您的 APPPATH/config 目录，并在那里编辑您的设置。
4. 编辑您的 config.php 并将 "segment" 添加到自动加载的包列表中，或使用 \Package::load('segment'); 在实时中加载它。
5. 为下文描述的 $analytics->render() 方法创建一个模板变量。确保您的模板中的变量出现在 Analytics.js 代码片段 之后。

使用方法

要运行任何函数，请编写以下内容。

$analytics = \Segment\Analytics::instance();

设置用户 ID

当您创建上面的 \Segment\Analytics 对象时，匿名 ID 将自动生成并存储在会话变量中。（segment.identity 的一部分）您有两种方法设置 userId 参数，这样您就无需再次设置它。您可以通过调用 identify() 方法或直接使用 set_user_id() 方法来设置它，后者在未为该用户设置时依赖它。

$user_id - 设置您希望传递给依赖于userId参数的任何方法的标识符。

$analytics->set_user_id($user_id);

页面

Segment.io要求每个页面至少有一个页面视图。Segment代码已经包含了analytics.page()调用，您必须删除此调用，以避免浪费对Segment.io的调用。只有当您没有通过调用$analytics->page()方法命名页面时，Segment.io for FuelPHP才会自动生成原始页面视图的代码。

请注意，由于Segment.io的限制，即使您通过PHP发送，也始终会通过Analytics.js发送页面视图。如果您只想通过PHP创建页面视图，请勿运行render()方法。如果需要两者，请将render()方法的第二个参数传递为布尔值false以禁用JS页面视图，仅留下PHP页面视图。

为了帮助在Mix Panel中可靠地调用，JS输出会在analytics.alias()之后自动调用analytics.flush()。

$page_data - 如在PHP实现中指定的数据数组。 (JS版本将从这个数组中提取适当的属性，通过Analytics.js版本发送。)
$js - 将此设置为true以创建指定参数的JS代码。生成的代码将排队并准备好由render()方法使用。您只能通过此包调用一次page()，因此后续的page()调用将替换之前的代码。直接在模板文件中添加analytics.page()调用以进行虚拟页面视图。将其设置为false以在服务器端进行处理。
$js_options - Analytics.js允许您将选项作为参数传递。文档明确指出，“integrations”对象可以是选项，因此默认情况下，如果$page_data包含该对象，则它将出现在选项参数中。您可以通过设置此为数组来添加额外的“integrations”属性、覆盖它们或添加不同的对象或参数到选项列表。
$js_callback - 如果您想使用JS回调函数，请指定用于该参数的确切原始JS代码。

$analytics->page($page_data = array(), $js = true, $js_options = array(), $js_callback = null);

别名

别名允许您跟踪匿名访客到他们新的系统内身份。请注意，Mix Panel存在一个竞争条件，您的活动必须与Mix Panel队列竞争。 了解有关此问题的更多信息以及为什么最好在客户端别名您的客户。出于同样的原因，如果您决定在服务器端别名，Mix Panel要求您在服务器端别名之前在客户端别名。

由于最好在客户端别名您的客户，您需要将系统内的标识符发送到浏览器。这可能会产生安全漏洞，尤其是如果您正在使用数据库中ID列的通用名称。出于这个原因，请考虑在数据库中为分析跟踪创建一个新的列。为新列命名，以便黑客可能无法猜到。

$alias - 如在PHP实现中指定的数据数组。 (JS版本将从这个数组中提取适当的属性，通过Analytics.js版本发送。) 您可以省略previousId以使用包在用户的会话中设置的匿名Id。如果您已调用identify()或set_user_id()方法，则可以省略JS和PHP中的userId字段。通过alias()设置userId时，也会调用set_user_id()方法，以确保您的脚本保持同步。
$js - 将此设置为true，以创建指定参数的JS代码。生成的代码将被排队并准备好由render()方法渲染。您只能通过此包调用一次alias()，因此后续的alias()调用将替换之前的代码。将其设置为false以在服务器端处理。
$js_options - Analytics.js允许您将选项作为参数传递。文档中特别指出，“integrations”对象可以是选项之一，因此默认情况下，如果$alias包含该对象，则它将出现在选项参数中。您可以通过将此设置为数组来添加额外的“integrations”属性、覆盖它们或向选项列表添加不同的对象或参数。
$js_callback - 如果您想使用JS回调函数，请指定用于该参数的确切原始JS代码。

$analytics->alias($alias = array(), $js = true, $js_options = array(), $js_callback = null);

识别

通过PHP或JS识别您的客户。

$identification - 根据PHP实现指定的数据数组。（JS版本将从该数组中提取适当的属性，并通过Analytics.js版本发送。）
$js - 将此设置为true以创建指定参数的JS代码。生成的代码将被排队并准备好由render()方法渲染。您只能调用一次identify()，因此后续的identify()调用将替换之前的代码。将其设置为false以在服务器端处理调用。
$js_options - Analytics.js允许您将选项作为参数传递。文档中特别指出，“integrations”对象可以是选项之一，因此默认情况下，如果$identification包含该对象，则它将出现在选项参数中。您可以通过将此设置为数组来添加额外的“integrations”属性、覆盖它们或向选项列表添加不同的对象或参数。
$js_callback - 如果您想使用JS回调函数，请指定用于该参数的确切原始JS代码。

$analytics->identify($identification = array(), $js = true, $render_safe = false, $js_options = array(), $js_callback = null);

分组

group()方法允许您将人与公司、项目或其他您定义的组结构连接起来。

$group - 根据PHP实现指定的数据数组。（JS版本将从该数组中提取适当的属性，并通过Analytics.js版本发送。）
$js - 将此设置为true以创建指定参数的JS代码。生成的代码将被排队并准备好由render()方法渲染。您只能通过此包调用一次group()，因此后续的group()调用将替换之前的代码。将其设置为false以在服务器端处理。
$js_options - Analytics.js允许您将选项作为参数传递。文档中特别指出，“integrations”对象可以是选项之一，因此默认情况下，如果$group包含该对象，则它将出现在选项参数中。您可以通过将此参数设置为数组来添加额外的“integrations”属性、覆盖它们或向选项列表添加不同的对象或参数。
$js_callback - 如果您想使用JS回调函数，请指定用于该参数的确切原始JS代码。

$analytics->group($group = array(), $js = true, $js_options = array(), $js_callback = null);

跟踪

跟踪您的客户所做的每一项移动。O.O 只是要确保在您的隐私政策中让他们知道您正在这样做。

$track - 根据PHP实现指定的数据数组。（JS版本将从该数组中提取适当的属性，并通过Analytics.js版本发送。）
$js - 将此参数设置为 true 以创建指定参数的 JS 代码。生成的代码将被排队并准备用于 render() 方法。您可以多次调用 track()，每个调用都会按设置的顺序添加到队列中。将此参数设置为 false 以在服务器端处理。
$js_options - Analytics.js 允许您将选项作为参数传递。文档中特别指出，“integrations”对象可以是选项之一，因此默认情况下，如果 $track 包含该对象，则它将出现在选项参数中。您可以通过设置此参数为数组来添加额外的“integrations”属性、覆盖它们或向选项列表添加不同的对象或参数。
$js_callback - 如果您想使用JS回调函数，请指定用于该参数的确切原始JS代码。
$noninteraction - 与 Google Analytics 的交互表示用户已触发事件。由于我们正在生成与页面一起加载的代码，因此我们正在生成非交互代码，因此默认情况下设置为非交互。将其更改为 false 以将调用作为交互性调用发送。

$analytics->track($track, $js = true, $js_options = array(), $js_callback = null, $noninteraction = true);

自定义函数

您可以为 analytics.js 添加自定义调用。使用此代码设置您想要的任意数量的原始 JS 函数。

$custom_js_function - 在此处设置您的 JS 字符串。从技术上讲，您可以在一次设置中设置尽可能多的函数，因为这个变量只是一个任意字符串。通过多次调用 custom() 方法来排队更多的 JS 函数。

$analytics->custom($custom_js_function);

渲染您的 JS

如果您已为 Analytics.js 排队 JS 调用，则需要运行以下代码来渲染输出。除“跟踪”之外，每个代码只能有一个调用。render 函数将按照以下顺序生成您已添加到队列的每个函数的 JS 代码：页面、别名、识别、分组、跟踪。如果此顺序不适合您，请使用以下参数指定顺序，该参数是一个包含上述列表的正确顺序的数组。示例显示了默认值。

此参数是 可选的，它显示了默认显示顺序。$analytics->render($order = array('page', 'alias', 'identify', 'group', 'track', 'custom'));

注意事项

1. Google Universal Analytics 本地支持，但过时的 Classic Analytics 不支持。（尽管 Classic Analytics 可能仍然适用于您）如果存在 _ga cookie，则将自动开启 UA 的特殊考虑，例如将 nonInteraction 设置为 1，并将 _ga cookie 传递到服务器端的 Segment.io。_ga cookie 只在客户第一次查看页面时存在，PHP 不会访问客户第一次查看的页面的 cookie。
2. 所有服务器端请求都支持“context”对象来传递数据，例如 User Agent 到 Segment.io。如果您需要，您可以手动传递以下特殊上下文值：“app”、“device”、“location”、“network”、“screen”、“traits”和未记录的“referrer”对象。
3. 当您在服务器端进行调用时，它将立即发送到 Segment.io。当您在客户端进行调用时，它将在您调用 render() 方法时将 JS 函数排队发送到浏览器。
4. Segment.io for FuelPHP 自动生成一个匿名 ID 并将其传递到 analytics.js，以保持服务器和客户端脚本同步。

故障排除

当您的设置不起作用或无法找到文件/类时，请清除您的 FuelPHP 缓存。（APPPATH/cache）

致谢

此包参考了 Segment.io 编写的第三方代码。（请参阅“安装和配置”中的“require”指令以下载他们的 SDK 代码。）Segment.io 在 MIT 许可下许可其 PHP SDK。Bit API Hub 与 Segment.io 没有任何关联，除了我们是他们的客户。

该包“Segment.io for FuelPHP”由Bit API Hub按照Apache 2.0许可证授权，该许可证的副本已包含在本存储库中。