打字机

打字机是一种用于基于预定义的强类型段分析库的工具跟踪计划规格。

在高层次上,Typewriter可以像这样从跟踪计划中获取事件“订单完成”事件:

在协议跟踪计划中订购已完成的事件

并使用它生成不同语言的类型化分析调用:

// Web应用程序中的示例客户端常量打字机=要求'./分析'打字机orderCompleted({orderid.'CK-F306FE0E-CC21-445A-9CAA-08245A9AA52C'全部的39.99.})
//在你的iOS应用程序中的示例客户端SEGTypewriterAnalyticsorderCompletedorderid.“CK-F306FE0E-CC21-445A-9CAA-08245A9AA52C”全部的3999

笔记:打字机当前可以为Analytics.js.analytics-nodeanalytics-iosAnalytics-android.

这些生成的客户端嵌入了从跟踪计划中的元数据,这些计划上下上下上下上下上下规范了您的分析仪表,并减少了(或完全消除了!)生产环境中的错误仪器。在您的编辑器中,您可以访问事件名称,描述,属性名称,类型等:

事件名智能感知

物业名称IntelliSense.

您还可以配置打字机以验证运行时的分析事件,可以在开发和测试期间提醒您仪器错误。打字机可以警告您缺少所需的属性,无效的枚举值,Regex不匹配以及任何其他高级的JSON模式您在跟踪计划中配置。

示例运行时验证警告

如果仪器生成任何违规行为,则可以使用测试套件使用测试套件自动失败,以便自动使用单元测试:

示例单元测试因违规而失败

如果你使用的是一种静态类型的语言(如TypeScript, Java, Objective-C, Swift等),那么你也可以访问关于你的插装的编译时警告:

编译时验证警告示例

打字机还有助于团队采用分析最佳实践,比如避免自动生成事件名,并仔细考虑要跟踪哪些属性。

要开始,请查看以下QuickStart导轨之一:

有关于打字机的反馈?考虑开放A.GitHub的问题

先决条件

打字机使用node.js.,需要node@8.x或者以后,npm@5.2.x.或以后的功能。

您可以通过在命令行窗口中运行以下命令来检查是否有节点和npm:

$节点- 版本v10.15.3$npm- 版本6.9.0.$npx- 版本6.9.0.

如果你没有这些您需要安装节点。安装节点也安装npmnpx为你。如果您在麦斯科斯芯片上,可以安装它家用

$酿造安装节点

一旦安装了节点和NPM,运行- 版本命令,以验证它们是否已正确安装。

浏览器QuickStart.

在你开始之前,确保你有节点使用该说明安装先决条件以上。

接下来,安装Analytics.js.在您的应用程序中。现在,你只需要完成步骤1:复制Snippet来自Analytics.js.快速入门指南

一旦你得到了Analytics.js.安装,将打字机添加为项目中的开发人员依赖项:

$npm安装-  save-dev.打字机

打字机附带一个生成的QuickStart向导打字机.Yml.配置,以及您的第一个打字机客户机。要使用此向导,请运行:

$npx打字机init

笔记:您可以通过运行重新生成打字机客户端NPX打字机。每次更新跟踪计划时,你都需要这样做。

运行命令创建一个打字机.Yml.在您的回购中的文件。有关此文件格式的更多信息,请参阅打字机配置参考

该命令还添加了一个新的Typewriter客户机./分析(或您配置的任何路径)。您可以将此客户端导入项目,如下所示:

//导入自动生成的typewriter客户端:常量打字机=要求'./分析'//发出您的第一个打字机跟踪!打字机orderCompleted({orderid.'CK-F306FE0E-CC21-445A-9CAA-08245A9AA52C'全部的39.99.})

为了帮助你最小化捆绑包的大小,打字机支持树摇使用命名的出口。所有生成的分析调用都会自动直接导出,所以你可以像这样导入它们:

//导入自动生成的typewriter客户端:常量{orderCompleted}=要求'./分析'//发出您的第一个打字机跟踪!orderCompleted({orderid.'CK-F306FE0E-CC21-445A-9CAA-08245A9AA52C'全部的39.99.})

打字机在呼叫中包装了您的分析ES6代理,这有助于防止您的应用程序崩溃,如果您使用一个不存在的生成函数进行分析调用。例如,如果订单完成在上面的第一个示例中跟踪计划中的事件不存在,那么您的应用程序将崩溃TypeError:打字机.OrderCompleted不是函数。但是,从那以后打字机动态地代理底层函数调用,它可以检测函数是否不存在,并为您处理它。打字机记录警告消息,然后触发未知分析呼叫被触发进入你的来源。我们的团队在将JavaScript项目迁移到批量打字机时,我们的团队发现这种有用,因为它给了我们信心我们不会引入崩溃我们的应用的回归。请记住,代理不适用于名为Exports。

你现在可以出发了!要了解更多有关Typewriter支持的一些高级配置选项的信息,请继续阅读。

nodejs QuickStart.

在你开始之前,确保你有节点使用该说明安装先决条件以上。

接下来,安装analytics-node在您的应用程序中。现在,你只需要完成步骤2:安装模块来自analytics-node快速入门指南

一旦你有了analytics-node安装,将打字机添加为项目中的开发人员依赖项:

$npm安装-  save-dev.打字机

打字机附带一个生成的QuickStart向导打字机.Yml.配置,以及您的第一个打字机客户机。要使用此向导,请运行:

$npx打字机init

笔记:您可以通过运行重新生成打字机客户端NPX打字机。每次更新跟踪计划时,你都需要这样做。

运行命令创建一个打字机.Yml.在您的回购中的文件。有关此文件格式的更多信息,请参阅打字机配置参考

该命令还添加了一个新的Typewriter客户机./分析(或您配置的任何路径)。您可以将此客户端导入项目,如下所示:

//根据上面的Analytics-Node指南初始化Analytics-Node。常量分析=要求'analytics-node'常量分析=分析'YOUR_WRITE_KEY'//导入自动生成的打字机客户端。常量打字机=要求'./分析'//通过您的Analytics-node实例到打字机。打字机setTypewriterOptions({分析分析})//发出您的第一个打字机跟踪!打字机orderCompleted({orderid.'CK-F306FE0E-CC21-445A-9CAA-08245A9AA52C'全部的39.99.})

打字机在呼叫中包装了您的分析ES6代理,这有助于防止您的应用程序崩溃,如果您使用一个不存在的生成函数进行分析调用。例如,如果订单完成在上面的第一个示例中跟踪计划中的事件不存在,那么您的应用程序将崩溃TypeError:打字机.OrderCompleted不是函数。但是,从那以后打字机动态地代理底层函数调用,它可以检测函数是否不存在,并为您处理它。打字机记录警告消息,然后触发未知分析呼叫被触发进入你的来源。我们的团队在将JavaScript项目迁移到批量打字机时,我们的团队发现这种有用,因为它给了我们信心我们不会引入崩溃我们的应用的回归。请记住,代理不适用于名为Exports。

你现在可以出发了!要了解更多有关Typewriter支持的一些高级配置选项的信息,请继续阅读。

ios QuickStart.

在你开始之前,确保你有节点使用该说明安装先决条件以上。

接下来,安装analytics-ios在您的应用程序中。现在,你只需要完成第1步:安装SDK来自analytics-ios快速入门指南

打字机附带一个生成的QuickStart向导打字机.Yml.配置,以及您的第一个打字机客户机。要使用此向导,请运行:

$npx打字机init

笔记:您可以通过运行重新生成打字机客户端NPX打字机。每次更新跟踪计划时,你都需要这样做。

运行命令创建一个打字机.Yml.在您的回购中的文件。有关此文件格式的更多信息,请参阅打字机配置参考

您现在可以使用Xcode将新打字机客户端导入项目中。如果将生成的文件放入项目中的文件夹中,请将项目导入作为组不是文件夹引用。

在Objective-C应用中使用它:

//导入自动生成的typewriter客户端:#import“segtypewriteranalytics.h”//发出您的第一个打字机跟踪![SEGTypewriterAnalyticsOrderCompletedWithOrderId.“CK-F306FE0E-CC21-445A-9CAA-08245A9AA52C”全部的@ 39.99];

要在SWIFT应用程序中使用它,请添加一个桥商标题就像下面的例子一样:

/ / TypewriterSwiftExample-Bridging-Header.h////确保包含所有从你的打字机客户端生成的头文件:#import "Analytics/ segverse .h" #import "Analytics/ segverse .h" #import "Analytics/ segverse .h" #import "Analytics/ segverse .h" #import "Analytics/ segverse .h" #import "Analytics/ segverse .h"

然后,你可以在Swift中使用你的打字机客户端:

//发出您的第一个打字机跟踪!SEGTypewriterAnalyticsorderCompletedorderid.“CK-F306FE0E-CC21-445A-9CAA-08245A9AA52C”全部的3999

你现在可以出发了!要了解更多有关Typewriter支持的一些高级配置选项的信息,请继续阅读。

Android快速入门

在你开始之前,确保你有节点安装了。使用说明先决条件以上。

接下来,安装Analytics-android.在您的应用程序中,通过以下三个步骤配置Singleton Analytics实例Android快速入门

打字机附带一个生成的QuickStart向导打字机.Yml.配置,以及您的第一个打字机客户机。要使用此向导,请运行:

$npx打字机init

笔记:您可以通过运行重新生成打字机客户端NPX打字机。每次更新跟踪计划时,你都需要这样做。

运行命令创建一个打字机.Yml.在您的回购中的文件。有关此文件格式的更多信息,请参阅打字机配置参考

你现在可以在你的Android Java应用程序中使用你的打字机客户端了:

//导入自动生成的typewriter客户端:进口com.segment.generated。*//发出您的第一个打字机跟踪!typewriterAnalytics.)。orderCompletedOrderCompleted构建器()orderid.“CK-F306FE0E-CC21-445A-9CAA-08245A9AA52C”全部的39.99.建造());

恭喜你,你准备好出发了!要了解更多有关Typewriter支持的一些高级配置选项的信息,请继续阅读。

添加事件

要向打字机客户端更新或添加新事件,首先将更改应用到跟踪计划。然后执行如下命令:

#使用repo的`typewriter.yml`运行它的目录。$NPX打字机

API令牌配置

对象中获取跟踪计划需要一个段API令牌段配置API.

只有工作区所有者可以创建段API令牌。要创建API令牌,请打开令牌选项卡上的访问管理页面,点击创建令牌。打字机只需要协议只读角色。

例子打字机令牌

Typewriter以以下两种方式查找API令牌:

  1. 控件中执行令牌脚本打字机.Yml.。看令牌脚本为更多的信息。
  2. 读取一个内容〜/ .typewriter.文件。

QuickStart向导会提示您输入API令牌并将其存储在内〜/ .typewriter.为你。

细分建议您使用a令牌脚本与您的团队共享API令牌。使用令牌脚本时,可以将API令牌作为环境变量提供(echo $ TYPEWRITER_TOKEN),来自a.env。文件(.env来源;echo $ TYPEWRITER_TOKEN)或使用任何其他CLI工具提供机密信息。

编辑器配置

要使大多数打字机,Segment建议安装一些扩展:

JavaScript

打字机客户端包括遵守的功能文档JSDoc规格。在编辑器中安装下面的相关扩展名为JSDoC支持:

类型签字

对于RiceStrick客户端中的IntelliSense,请在编辑器中安装以下相关扩展名。如果您的项目是JavaScript和TypeScript的组合,那么您还应在上面的JavaScript部分中安装插件,以便您的编辑器也将支持JSDoC IntelliSense。

iOS.

XCode不需要任何额外的配置,并且显示了开箱即用的智能感知。

安卓

Android Studio不需要任何额外的配置,并显示出框外的Intellisense。

最佳实践

我们强烈推荐储存追踪计划(plan.json)在一个版本控制系统中。这保证打字机将生成相同的客户端,无论您在段应用程序中对跟踪计划所做的任何更改。否则,对跟踪计划的更改可能导致破碎的构建。

我们建议您只需办理登机手续plan.json,并在应用程序构建步骤期间生成打字机客户端(通过调用NPX打字机)。你可以这样做git用下面的.gitignore

#确保将`Analytics`更新到打字机客户端的完整路径。分析/*!!分析/ plan.json

如果这是不可能的可以还要检入完整生成的客户机。我们不推荐这种方法。

配置参考

类型中存储其配置打字机.Yml.文件在你的回购的根。一个示例配置看起来像这样:

#段打字机配置参考(https://github.com/segmentio/typewriter)#只需运行`npx typewriter`以重新生成带有这些事件的最新版本的客户端。脚本#您可以使用“script.token`命令”提供分段API令牌。请参阅下面的“令牌脚本”脚本。令牌.env来源;echo $ TYPEWRITER_TOKEN#您可以使用`script.After`命令格式化任何打字机的自动生成文件。#见下面的“格式生成的文件”。。/ node_modules / plan.json。bin /漂亮——写分析客户#哪个部分SDK你生成。#有效值:analytics.js, analytics-node, analytics-ios, analytics-android。SDK.analytics-node#打字机客户端的目标语言。#有效值:JavaScript,Cypescript,Java,Objective-C,Swift。类型签字TrackingPlans.#您正在为之生成客户端的部分协议跟踪计划。#提供你的工作空间和跟踪计划id,这两个都可以找到#在查看跟踪计划编辑器时在URL中。例如:# https://app.www.asianminres.com/segment-demo/protocols/tracking-plans/rs_QhWHOgp7xg8wkYxilH3scd2uRID#您还需要提供一个目录的路径来保存您的打字机客户端。-IDrs_QhWHOgp7xg8wkYxilH3scd2uRIDWorkspacesLug.分部演示小路./分析

在任何时候,你都可以通过运行Typewriter快速启动向导重新生成这个文件:

$npx打字机init

令牌脚本

如果您的团队有一种在开发环境中提供秘密(密码和令牌)的标准方法,无论这是否简单.env您可以配置Typewriter来使用它来获得一个Segment API令牌。

您可以通过创建名为的令牌脚本来对此进行配置scripts.token在你的打字机.Yml.。此脚本是包含shell命令的字符串,该命令在执行时输出有效的段API令牌。这是一个微不足道的,但是不安全, 例子:

脚本#注意:切勿将段API令牌提交到版本控制系统。令牌Echo“Oiego $ * HF83HFH034FNOSNFIOFOWIENFOWNFNOWEUNFOIWENF ...”

举个例子,在Segment,我们把秘密藏在里面分段/室内这是支持的AWS参数存储。提供对令牌的访问是这样的:

脚本令牌Aws-okta exec dev-privileged——chamber export typewriter | jq -r .typewriter_token

了解更多关于的信息打字机.Yml.配置格式,请参见配置参考以上。

格式化生成的文件

在你的打字机.Yml.,您可以配置脚本(scripts.After.)在生成打字机客户端后会开火。您可以使用此功能将您的团队的样式指南应用于任何打字机的自动生成文件。

例如,如果你想申请你的漂亮格式化plan.json(跟踪计划的本地快照),您可以使用脚本如下:

脚本/ node_modules /。bin /漂亮——写。/分析/ plan.json

了解更多关于的信息打字机.Yml.配置格式,请参见配置参考以上。

连接到CI.

如上所述最佳实践上文部分,细分建议您只需检查plan.json,而不是生成的客户端,进入您的版本控件。相反,我们建议将这些客户端作为应用程序的构建步骤构建。

在您的CI环境中,这通常涉及构建打字机客户端的步骤。如下所示,请务必在部署应用程序之前构建生产客户端跟踪计划违规处理下面的部分。

#示例(简化)circleci配置:职位测试脚步-NPX打字机开发-纱线运行测试部署脚步-NPX打字机生产-纱线运行部署

跟踪计划违规处理

您还可以配置打字机以验证运行时的分析事件,可以在开发和测试期间提醒您仪器错误。默认情况下,打字机会生成“开发”构建,这意味着它包含此逻辑。您可以生成“生产”构建,以省略此逻辑:

#构建开发客户端(默认,如果没有提供):$NPX打字机开发#构建生产客户端:$NPX打字机生产

笔记:并非所有语言都支持运行时验证。现在,Analytics.js.analytics-node支持它AJV.(JavaScript和TypeScript项目)analytics-iosAnalytics-android.尚未支持运行时验证。打字机还不支持使用常用JSON架构的运行时验证。对于尚未支持运行时验证的语言,开发和生产客户端是相同的。

Segment建议在本地测试应用程序或运行测试时使用开发构建。我们一般建议反对使用生产中的开发版本,因为这包括跟踪计划的完整副本,可以增加应用程序的大小。

您可以提供一个自定义处理程序,每当看到违规时就触发它。默认情况下,这个处理程序记录一个警告。

为了Analytics.js.analytics-node客户端,您可以将此处理程序配置为setTypewriterOptions

常量打字机=要求'./分析'功能yourviolationHandler.信息违反{安慰错误`打字机违反了$ {信息事件}`违反}打字机setTypewriterOptions({onviroation.yourviolationHandler.})

此处理程序的常用情况是配置打字机以检测您的测试运行何时运行,如果是,则抛出错误以使您的单元测试失败。例如:

常量打字机=要求'./分析'功能yourviolationHandler.信息违反{如果过程env.IS_TESTING===.'真的'{错误`打字机违反了$ {信息事件}`}}打字机setTypewriterOptions({onviroation.yourviolationHandler.})

笔记:打字机是预先配置的analytics-node如果。环境抛出错误NODE_ENV =测试,它是由大多数Node.js测试库设置的,比如艾娃笑话

另一个常见用例是自定义对您的团队报告的违规行为。例如,在段,我们自定义此处理程序来显示烤面包的通知到我们的开发人员应用程序:

例如在app.www.asianminres.com上的烤面包机通知

常量打字机=要求'./分析'常量{烤面包机}=要求'evergreen-ui'打字机setTypewriterOptions({//请注意,此处理程序仅在开发模式下触发,因为我们运送生产构建//打字机给客户。manbetx客户端应用下载onviroation.味精违反= >{烤面包机警告`“$ {味精事件}“因违反跟踪计划而被解雇”{描述违反[0.]。信息})}})

已知的限制

打字机目前只支持跟踪呼叫,但是您可以继续使用底层(untyped)分析实例执行确认团体页面屏幕, 和别名调用。

并非所有语言都支持运行时验证。现在,Analytics.js.analytics-node支持它AJV.(JavaScript和TypeScript项目)analytics-iosAnalytics-android.尚未支持运行时验证。打字机还不支持使用常用JSON架构的运行时验证。

贡献

如果你有兴趣参与,在GitHub上打开一个问题我们可以帮助您提供指针即可开始!

反馈

我们总是很好奇您对您使用打字机的经验的任何反馈!与我们联系,在GitHub上打开一个问题

最后修改:2020年8月6日



开始使用细分

细分是将你的网站和手机应用数据整合到300多个分析和增长工具中的最简单方法。
或者
创建免费帐户