[TOC] ***** # Linkflow对接指南 # 一、 概述 Linkflow是一个对接不同App的PaaS平台。Linkflow不仅可以主动调用其他App的API实现集成场景，还可以通过API让其他App写入数据实现集成场景。 在介绍Linkflow API之前，先介绍一下Linkflow的数据模型，在理解这些数据模型之后，可以更好的帮助您实现您的集成场景。在Linkflow的数据模型中，一共包含如下的业务对象： * 渠道类型，渠道类型是指一个App的类型，比如微信服务号就是一种App的类型，又比如自建网站也是一种App的类型 * 渠道，渠道是指一个App类型的实例，比如"Linkflow联否"微信服务号就是微信服务号的一个实例，www.linkflowtech.com就是自建网站的一个实例 * 渠道账号，渠道账号是指客户在这个App里面的账号，比如在某个微信服务号里面的渠道账号就是一个个的微信粉丝。渠道账号一定是挂靠在某个渠道下面的，一般来说渠道账号的id就是这个客户在这个App里面的id * 联系人，联系人是Linkflow特有的业务对象。联系人是渠道账号的聚合，也就是如果一个客户可以在多个App里面有渠道账号，那么这些账号就可以聚合成一个Linkflow里面的联系人。在系统刚刚创建的时候，在创建第一个渠道账号之后就会自动创建一个联系人，之后当一个渠道账号被创建之后，如果该渠道账号无法合并到一个已有的联系人，那么就会创建一个新的联系人。  * 标签组，标签组是联系人的客户画像之一。可以通过标签组来给联系人分组和打标签，比如VIP客户、沉睡客户等等。标签组也可以与其他系统的标签进行同步，比如Linkflow已经实现了与微信公众号里面的标签同步。 * 事件类型，事件类型是事件的Metadata，是描述一个事件的数据结构的。在Linkflow里面所有已经对接好的App的事件类型都是由Linkflow定义的，这些事件类型称为系统事件类型。在自定义的渠道类型中，所有的事件类型都是可以自己定义的，Linkflow提供UI来创建这些自定义事件类型。 * 事件，事件是指联系人在某个App里面产生行为，这个行为既包含客户对这个App做的行为，比如在微信服务号里面的关注和点击菜单行为，也包含App对客户做的行为，比如微信服务号推送文本或者模版消息给客户。一个事件是挂在渠道账号上的，但是在Linkflow中展现的时候是挂靠在联系人身上的，这是因为联系人是渠道账号的聚合。 下面的业务对象关系图展示了几个业务对象之间的关系：  业务对象之间的关系 # 二、对接类型 按照概述中的模式，Linkflow提供了多种类型的应用对接。按照用户是否可以创建自定义事件，我们将对接分为两种类型：第三方应用对接和自定义对接 ## 1.第三方应用对接 如微信公众号、云片网、sendcloud此类对接，参见[连接管理](https://help.linkflowtech.com/lfcs/977660)。Linkflow已经帮助用户处理好渠道账号、事件类型、事件的业务逻辑，可以覆盖主要的运营场景，用户只需创建连接，无单独处理渠道、渠道账号、事件类型、事件这些数据，即可直接在系统中使用此连接和连接事件。 ## 2.自定义对接 当用户有自建网站、移动端APP、小程序需要对接时，Linkflow无法预知用户的主要运营场景，所以需要用户自己处理渠道、渠道账号、事件类型、事件这些数据。处理流程如下： 1、创建连接：自定义渠道/小程序渠道，参见[自定义渠道](https://help.linkflowtech.com/lfcs/977739)、[微信小程序](https://help.linkflowtech.com/lfcs/977681) 2、创建自定义事件：参见[自定义事件管理](https://help.linkflowtech.com/lfcs/1770909) 3、在应用中引入SDK：参见SDK接入指南 4、埋点：识别联系人 5、埋点：发送自定义事件 ### 2.1识别联系人 识别联系人是指在Linkflow中创建自定义对接的渠道账号。 除了在SDK中调用接口或者使用Open API接口识别联系人，用户也可使用csv文件上传渠道账号识别联系人。 #### 2.1.1调用识别联系人接口 调用一次识别联系人接口，或者系统处理一行渠道账号数据，系统会在当前连接下找是否有与externalId相同的渠道账号，如果有就更新联系人信息，如果没有，就创建一个此连接的渠道账号，同时创建一个联系人，将渠道账号关联到这个联系人上。 如果APP在发生事件的时候，无法确定产生此事件的联系人是谁（externalId无法获取），Linkflow的SDK会自动使用cookie创建一个匿名渠道账号，将事件关联到这个匿名渠道账号上，等用户可以获得externalId和渠道账号信息进行联系人识别时，如果此时匿名渠道账号没有清除应用缓存，Linkflow会自动将之前产生的匿名用户和用externalId识别的渠道账号合并成一个渠道账号。 联系人属性 | 属性名 | 是否必填 | 格式 | 说明 | | --- | --- | --- | --- | | externalId | 是 | 字符串 | | | name | 否 | 字符串 | | | birthday | 否 | 日期型 | 生日，格式YYYY-MM-DD ，SDK支持更新此字段，Open Api不支持更新此字段 | | avatar | 否 | 字符串 | 头像路径 | | city | 否 | 字符串 | 城市 | | company | 否 | 字符串 | 公司 | | country | 否 | 字符串 | 国家 | | department | 否 | 字符串 | 部门 | | email | 否 | 字符串 | 邮箱 | | gender | 否 | 字符串 | 性别，只接受三种值，male,female,unknown | | homePhone | 否 | 字符串 | 座机 | | idCard | 否 | 字符串 | 身份证号码 | | industry | 否 | 字符串 | 行业 | | mobilePhone | 否 | 字符串 | 手机号码 | | nickname | 否 | 字符串 | 昵称 | | postalCode | 否 | 字符串 | 邮编 | | state | 否 | 字符串 | 省份 | | street | 否 | 字符串 | 街道 | | title | 否 | 字符串 | 职位 | | website | 否 | 字符串 | 网站 | | utm | 否 | 结构体 | 广告追踪utm | | props | 否 | 结构体 | 自定义字段 | 联系人数据结构： ~~~ { "externalId":"7", "name":"UBS渠道联系人7", "birthday": "1990-01-01", "avatar": "联系人头像地址", "city": "上海", "company": "上海源犀", "country": "中国" , "department": "市场部", "email": "zhangsan@linkflow.com", "gender": "male", "homePhone": "021-89006745", "idCard": "320987739XXXXXXXX", "industry": "互联网", "mobilePhone": "18908882802", "nickname": "李四", "postalCode": "20000", "state": "上海市", "street": "徐家汇", "title": "市场总监", "website": "www.baidu.com", "utm":{ "campaign":"推广", "content": "CDP", "medium": "SEM", "source": "baidu", "term": "数据中台" }, "props":{ "attr1": "string", "attr2": 2, ... }, "channel":{ "channelId":"udc_150QSaXlsu" } } ~~~ **2.1.1.1识别联系人时，与微信公众号粉丝合并** 前提：已经创建公众号连接，同步微信粉丝 用户在调用识别联系人接口时，可以传入WeChatInfo，包含appid（公众号的appid）、openid（渠道账号对应公众号的openid）、unionId这三个信息，系统就会按照WeChatInfo查找微信公众号的渠道账号对应的联系人，将当前连接的渠道账号关联到这个联系人上。（代码示例见各SDK识别联系人代码示例） **WeChatInfo合并联系人逻辑**  #### 2.1.2通过渠道账号csv文件识别联系人 通过渠道账号csv文件识别联系人的方式有两种：自动同步、手动导入 2.1.2.1**自动同步**： 设置自动同步的前提有两个： 1、已在Linkflow创建可连接站点，参见[站点设置](https://help.linkflowtech.com/lfcs/1609909) 2、站点已上传使用Linkflow渠道联系人模板创建的渠道联系人信息csv文件，文件名格式：channelid\_date\_\* （示例：udc\_158ZAeRqJA\_20190107 或udc\_158ZAeRqJA\_20190107\_1） * **channelid**：自定义连接可从连接详情页复制，如果是小程序连接则为小程序的appid * **date**：为文件中数据的生成日期，如果今天是1月11日，Linkflow会在1月11日凌晨2点从站点取数据，取的是命名规则日期为1月10日的文件。所以请确保在当天凌晨1点30分前上传前一天的更新数据。 * \*：表示当天的第几份文件 确定以上前提后，您就可在小程序连接、自定义渠道连接的连接设置页面，选择“同步渠道联系人”，进行每天同步文件的设置，设置完之后，Linkflow每天都会在所选站点所选文件夹中取当前连接对应的渠道联系人信息csv文件进行联系人识别。 **自动导入设置** 1、选择站点（参见“[站点设置](https://help.linkflowtech.com/lfcs/1609909)”）----希望从哪个SFTP服务器上获取当前连接渠道联系人信息csv文件 2、填写文件夹路径---保存当前连接渠道联系人信息csv文件的文件夹路径 **编辑自动导入** 可重新编辑自动导入设置时配置的站点和文件夹路径。  **删除自动导入设置** 如果您想停止此连接每天的识别联系人，点击删除即可。此后Linkflow不再自动同步此连接的渠道联系人信息。  2.1.2.2**手动导入**： 如果没有SFTP站点定期上传csv文件，您可在小程序连接、自定义渠道连接的连接设置页面，选择“同步渠道联系人”，进入页面后选择“手动导入”，手动上传csv文件导入连接用户。  2.1.2.3 **csv文件导入用户utm优先级** 如果导入时更新为实名用户，则会将utm记为用户的创建utm，utm优先级：导入文件中每个连接用户的utm>设置导入时在弹框填写的utm 2.1.2.4 **微信用户合并** 如果在csv文件中填写了openid或unionid，会查找系统中相同openid或unionid的用户，并将导入用户与之合并 #### 2.1.3识别连接人系统字段 externalId：渠道账号的唯一识别标识。可使用userId，loginId，手机号，unionid等信息，如果是小程序连接，可将unionid作为externalId，如果获取不到unionid，并且并没有计划使用unionid同微信公众号粉丝进行合并，则可将openid作为externalId，进行联系人识别。 comment：备注，格式字符串 avatar：头像，格式字符串 city：城市，格式字符串 company：公司，格式字符串 country：国家，格式字符串 dateOfBirthday：生日，格式YYYY-MM-DD，如1990-10-01 department：部门，格式字符串 email：邮箱，格式字符串 gender：性别，只接受三种值，male,female,unknown homePhone：座机，格式字符串 idCard：身份证号码，格式字符串 industry：行业，格式字符串 mobilePhone：手机号码，格式字符串 name：姓名，格式字符串 nickname：昵称，格式字符串 postalCode：邮政编码，格式字符串 state：省份，格式字符串 street：街道，格式字符串 title：职位，格式字符串 website：网站，格式字符串 utm.campaign：创建活动，格式字符串 utm.content：创建内容，格式字符串 utm.medium：创建媒介，格式字符串 utm.source：创建来源，格式字符串 utm.term：创建关键字，格式字符串 #### 2.1.3识别联系人自定义字段 如果系统字段无法满足业务要求，用户可在设置-->自定义字段中创建联系人自定义字段，参见“[自定义字段](https://help.linkflowtech.com/lfcs/977805)”。 调用识别联系人接口更新自定义字段时，字段名为“attr1”、“attr2”... ### 2.2发送事件 #### 2.2.1系统事件 Linkflow提供自定义连接和小程序连接的系统事件。参见各SDK的接入指南。 #### 2.2.2自定义事件 如果系统事件无法满足业务需求，用户可在设置中创建自定义事件。创建自定义事件时，只需要添加业务上需要使用的事件扩展属性，不需要额外添加系统已经预置的事件属性，这些系统预置的事件属性，在SDK中会进行自动获取，无需开发人员手动赋值。详细信息参见“[自定义事件](https://help.linkflowtech.com/lfcs/1770909)” # 二、 对接场景 因为Linkflow是一个对接的PaaS平台，所以会有许多种的对接场景，下面就选取两个典型的场景进行详细描述。 ## 1、 电商网站场景 在电商网站的集成中，包含两部分的对接，一部分是前端页面行为的对接，一部分是后台订单行为的对接，整个的流程如下：  ### 创建渠道 Linkflow会自动为您的自建电商网站创建渠道，您需要先引入网页追踪JS SDK，您的第一个用户访问电商网站页面时候，Linkflow就会用您电商网站域名作为channelId在Linkflow创建渠道。 ### 创建自定义事件类型 如，创建一个提交订单事件类型 ### 前端网页埋点 在前端网页埋点中分为两大类，一类是PV的捕获，一类是特定行为的捕获，比如浏览商品页面或者加入购物车。 **网页PV捕获** 对于网页PV的捕获，只需要将一行JS脚本放置在网页的Head模块。 具体做法是在Linkflow系统的"设置-网页埋点-追踪代码"菜单中拷贝追踪脚本，然后放置在网页的Head里面,如下： ~~~js <script src="http://static.leadswarp.com/linkflow.min.js?token=MTAtYzdlNGMzMzItZDkyNC00M2MyLWI3NDctZjE0ZmI2MDQ5NDNh&baseDomain=http://app.leadswarp.com"></script> ~~~ 示例 ~~~html <!DOCTYPE html> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> <link href="./static/style.css" rel="stylesheet"> <title>Page Title</title> <!-- 追踪代码： --> <script src="http://static.leadswarp.com/linkflow.min.js?token=MTAtYzdlNGMzMzItZDkyNC00M2MyLWI3NDctZjE0ZmI2MDQ5NDNh&baseDomain=http://app.leadswarp.com"></script> </head> <body> <div class="main"></div> </body> </html> ~~~ **特定行为捕获** 对于特定行为的捕获，则是要写JS代码完成集成的。比如，要捕获客户提交订单的行为，则可以根据在第二步创建的自定义事件类型进行自定义事件的代码植入。 1、创建自定义事件-提交订单  2、您创建的自定义事件-提交订单  提交订单JS代码示例： ~~~js window.linkflow.sendEvent({ submitOrder: { orderId:"UHo3uuoy49984075097", orderAmount:78 } }, function() { // success callback }, function(){ // fail callback }); ~~~ ### 后端订单集成 后端订单集成需要在Linkflow创建一个授权应用，获取Linkflow的授权Key和Secret，然后获取access token，最后通过这个API实现订单的集成。具体做法如下： **创建私有APP** 请去"设置-App集成设置-私有App设置"中创建一个私有App，获取App Key和App Secret。 **通过App Key和App Secret获取Access Token** 在获取App Key和App Secret之后，就可以来获取Access Token来访问Linkflow的资源了，具体访问方式参见[获取Access TokenAPI](https://docs.linkflowtech.com/api/#tong-guo-App-Key-he-App-Secret-huo-qu-Access-Token) **了解"提交订单"事件的数据结构** 进入【Linkflow】-【设置】-【自定义设置】-【自定义事件】 在该页面选择"行业"为【电商】，"所属APP"为【网站追踪】，此时就可以看到电商网站追踪的事件类型列表   **调用API实现订单的集成** 可根据事件类型的数据，进行创建事件接口调用。 请求示例如下： ~~~js { "channelId":// 电商网站域名, "channelType":// WEBSIT（channelType可由获取channelType列表接口获取）", "externalId":// 电商网站的用户唯一标识, "eventDate"：//事件发生时间，毫秒 "parentEventcode": // 父事件事件编码，如WEBSITE__ECOMMERCE__SUBMIT_ORDER, "attr1": // 事件属性值1，如”支付id“, "attr2": // 事件属性值2，如”订单id“, "attr3": // 事件属性值3，如"店铺id", "attr4": // 事件属性值4，如 "店铺名称", "attr5": // 事件属性值5，如"总金额", "attr6": // 事件属性值6，如"收货人姓名", "attr7": // 事件属性值7，如"收货人电话", "attr8": // 事件属性值8，如"收货人省份", "attr9": // 事件属性值9，如"收货人城市", "attr10": // 事件属性值10，如"收货人区域", "attr11": // 事件属性值11，如"收货人地址", "attr12": // 事件属性值12，如"运费", "attr13": // 事件属性值13，如"折扣", "attr14": // 事件属性值14，如"优惠券id", "attr15": // 事件属性值15，如"优惠券名称", "attr16": // 事件属性值16，如"是否使用积分", "attr17": // 事件属性值17，如"使用积分数量", "attr18": // 事件属性值18，如"积分抵扣金额", "attr19": // 事件属性值19，如"订单状态", "items": [{ "subEventcode": // 子事件编码，如" WEBSITE__ECOMMERCE__SUBMIT_ORDER_ITEM", "attr1": // 事件属性值1，如" 订单id", "attr2": // 事件属性值2，如" 商品id", "attr3": // 事件属性值3，如" 一级类目", "attr4": // 事件属性值4，如" 二级类目", "attr5": // 事件属性值5，如" 三级类目", "attr6": // 事件属性值6，如" 商品名称", "attr7": // 事件属性值7，如" 商品品牌", "attr8": // 事件属性值8，如" 价格", "attr9": // 事件属性值9，如" 数量", "attr10": // 事件属性值10，如" 优惠卷", "attr11": // 事件属性值11，如" 订单行总金额", "attr12": // 事件属性值12，如" 订单总金额" }] } ~~~ ## 2、 微信场景 微信场景中的集成，主要包含两部分，一部分是微页面的浏览行为，一部分是微页面中的特别行为，比如按钮的点击和表单的提交等等。 ### 微页面浏览行为集成 如果您需要把用户访问信息与 openid 关联, 则需要先选择公众号，然后将在Linkflow里面生成的一段javascript代码放置在贵公司微信页面的 Head 里面。  示例代码： ~~~html <!DOCTYPE html> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> <link href="./static/style.css" rel="stylesheet"> <title>Page Title</title> <!-- 追踪代码： --> <script src="http://static-dev.leadswarp.com/linkflow.min.js?token=MS1hMGEyNDkwYy01ZGZmLTQxNzItYWQ2OS0xZmQ3YWQwZGRhNjU%3D&baseDomain=http://devtest.leadswarp.com"></script> <!-- 用户通过微信访问页面，如果需要把用户访问信息与 openid 关联的话，则添加下面这段： --> <script src="http://static-dev.leadswarp.com/linkflow.min.js?token=MS1hMGEyNDkwYy01ZGZmLTQxNzItYWQ2OS0xZmQ3YWQwZGRhNjU%3D&baseDomain=http://devtest.leadswarp.com&appId=wx1f7fbd28ac009cd0"></script> </head> <body> <div class="main"></div> </body> </html> ~~~ ### 识别访问微页面联系人 然后在用户访问页面时，调用JS SDK识别联系人方法，识别访问页面联系人。 示例代码： ~~~js window.LFAPP.identify({ externalId: 'u1391231', mobilePhone: '138xxxxxxxx', // mobilePhone, name, email有且至少有一项有值 name: "demo", email: "demo@example.com", city: "南京", country: "中国", state: "江苏", company: "LF", industry: "IT", title: "dev", department: "RD", weChatInfo: { // 如果填写该参数，微信粉丝将会与Identify之前的匿名用户合并 openId: window.LFAPP.openId, // Linkflow会在用户打开网页时发起微信授权从而获得用户openId, 前提条件: 用户必须在微信中打开网页 appId: window.LFAPP.appId // 公众号appId，前提条件: 该公众号必须已在Linkflow绑定 } }, function() { // success callback }, function() { // fail callback }); ~~~ ### 微页面特定行为集成 对于特定行为的捕获，则是要写JS代码完成集成的。（参见电商网站场景-特定行为捕获） # 三、 对接API 渠道 1、[获取channelType列表](https://docs.linkflowtech.com/api/#huo-qu-ChannelType-lie-biao) 2、[创建自定义渠道](https://docs.linkflowtech.com/api/#chuang-jian-zi-ding-yi-qu-dao) 联系人 1、[获取联系人自定义字段](https://docs.linkflowtech.com/api/#huo-qu-lian-xi-ren-zi-ding-yi-zi-duan) 2、[识别联系人账号](https://docs.linkflowtech.com/api/#shi-bie-lian-xi-ren) 3、[查询联系人详情](https://docs.linkflowtech.com/api/#huo-qu-lian-xi-ren-xiang-qing) 4、[批量获取联系人详情](https://docs.linkflowtech.com/api/#pi-liang-huo-qu-lian-xi-ren-xiang-qing) 5、[获取联系人列表](https://docs.linkflowtech.com/api/#pi-liang-huo-qu-lian-xi-ren-ID) 6、 批量获取联系人open ID 7、[更新联系人](https://docs.linkflowtech.com/api/#geng-xin-lian-xi-ren) 标签 1、[创建标签组](https://docs.linkflowtech.com/api/#chuang-jian-biao-qian-zu) 2、[查询标签组](https://docs.linkflowtech.com/api/#cha-xun-biao-qian-zu) 3、[查询联系人的标签组](https://docs.linkflowtech.com/api/#cha-xun-lian-xi-ren-de-biao-qian-zu) 4、[查询标签组联系人](https://docs.linkflowtech.com/api/#cha-xun-biao-qian-zu-lian-xi-ren) 5、[添加标签组联系人](https://docs.linkflowtech.com/api/#tian-jia-biao-qian-zu-lian-xi-ren) 6、[删除标签组联系人](https://docs.linkflowtech.com/api/#shan-chu-biao-qian-zu-lian-xi-ren) 事件 1、 获取系统事件和自定义事件类型 2、[获取事件列表](https://docs.linkflowtech.com/api/#huo-qu-shi-jian-lie-biao) 3、[创建自定义事件](https://docs.linkflowtech.com/api/#chuang-jian-zi-ding-yi-shi-jian)