Linkflow是一个对接不同App的PaaS平台。Linkflow不仅可以主动调用其他App的API实现集成场景，还可以通过API让其他App写入数据实现集成场景。
在介绍Linkflow API之前，先介绍一下Linkflow的数据模型，在理解这些数据模型之后，可以更好的帮助您实现您的集成场景。在Linkflow的数据模型中，一共包含如下的业务对象：

• 渠道/连接类型：渠道是指一种与用户交互的App类型，比如微信服务号就是一个渠道，又比如自建网站是一个渠道。
• 连接：连接是指一个渠道的实例，比如"CDP联否"微信服务号就是微信服务号的一个实例，www.CDPtech.com就是自建网站的一个实例。

• 用户身份ID：用户身份ID是指用户在这个连接里面的账号，比如在某个微信服务号里面的用户身份就是一个个的微信粉丝账号。一般来说一个用户在一个连接中可能有1-N种身份ID，例如微信OpenID、微信UnionID等；不同连接的身份ID可以合并，例如来自不同连接获取的手机号。

• 用户：用户是CDP核心的业务对象。用户通常是一个自然人，用户是身份ID的聚合，也就是如果一个用户可以在多个连接里面有身份ID，那么这些身份ID就可以聚合成一个CDP里面的用户。在系统刚刚创建的时候，在创建第一个身份ID之后就会自动创建一个用户，之后当一个身份ID被创建之后，如果该身份ID无法合并到一个已有的用户，那么就会创建一个新的用户。

• 群组：群组是用户的集合，用户对群组而言只有在群组/不在群组两种状态。相对于标签而言，群组往往只是短时生效的，例如新的营销活动就需要圈选新的受众人群。

• 标签：标签是对个体用户的属性值，每个用户会有不同的标签值，该标签值也有可能变化。标签可以用做圈选动态群组的条件、或者分析的维度/指标/条件。

• 事件类型：事件类型是事件的元数据Metadata，是描述一个事件的数据结构。在CDP里面所有已经对接好的渠道的事件类型都是由系统定义的，这些事件类型称为系统事件类型。在自定义的渠道类型中，所有的事件类型都是可以自己定义的，系统提供UI来创建这些自定义事件类型。

• 事件：事件是指用户在某个渠道里面产生的行为，这个行为既包含客户对这个渠道做的行为，比如在微信服务号里面的关注和点击菜单行为，也包含渠道对客户做的行为，比如微信服务号推送文本或者模版消息给客户。一个事件是挂在用户上的。

下面的业务对象关系图展示了几个业务对象之间的关系：

按照概述中的模式，Linkflow提供了多种类型的应用对接。按照用户是否可以创建自定义事件，我们将对接分为两种类型：第三方应用对接和自定义对接

1.第三方应用对接

如微信公众号、云片网、sendcloud此类对接，参见连接管理。Linkflow已经帮助用户处理好渠道账号、事件类型、事件的业务逻辑，可以覆盖主要的运营场景，用户只需创建连接，无单独处理渠道、渠道账号、事件类型、事件这些数据，即可直接在系统中使用此连接和连接事件。

2.自定义对接

当用户有自建网站、移动端APP、小程序需要对接时，Linkflow无法预知用户的主要运营场景，所以需要用户自己处理渠道、渠道账号、事件类型、事件这些数据。处理流程如下：
1、创建连接：自定义渠道/小程序渠道，参见自定义渠道、微信小程序
2、创建自定义事件：参见自定义事件管理
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":"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创建可连接站点，参见站点设置
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、选择站点（参见“站点设置”）----希望从哪个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识别联系人自定义字段

如果系统字段无法满足业务要求，用户可在设置-->自定义字段中创建联系人自定义字段，参见“自定义字段”。
调用识别联系人接口更新自定义字段时，字段名为“attr1”、“attr2”...

2.2发送事件

2.2.1系统事件

Linkflow提供自定义连接和小程序连接的系统事件。参见各SDK的接入指南。

2.2.2自定义事件

如果系统事件无法满足业务需求，用户可在设置中创建自定义事件。创建自定义事件时，只需要添加业务上需要使用的事件扩展属性，不需要额外添加系统已经预置的事件属性，这些系统预置的事件属性，在SDK中会进行自动获取，无需开发人员手动赋值。详细信息参见“自定义事件”

因为Linkflow是一个对接的PaaS平台，所以会有许多种的对接场景，下面就选取两个典型的场景进行详细描述。

1、 电商网站场景

在电商网站的集成中，包含两部分的对接，一部分是前端页面行为的对接，一部分是后台订单行为的对接，整个的流程如下：

创建渠道

Linkflow会自动为您的自建电商网站创建渠道，您需要先引入网页追踪JS SDK，您的第一个用户访问电商网站页面时候，Linkflow就会用您电商网站域名作为channelId在Linkflow创建渠道。

创建自定义事件类型

如，创建一个提交订单事件类型

前端网页埋点

在前端网页埋点中分为两大类，一类是PV的捕获，一类是特定行为的捕获，比如浏览商品页面或者加入购物车。

网页PV捕获
对于网页PV的捕获，只需要将一行JS脚本放置在网页的Head模块。
具体做法是在Linkflow系统的"设置-网页埋点-追踪代码"菜单中拷贝追踪脚本，然后放置在网页的Head里面,如下：

<script src="http://static.leadswarp.com/linkflow.min.js?token=MTAtYzdlNGMzMzItZDkyNC00M2MyLWI3NDctZjE0ZmI2MDQ5NDNh&baseDomain=http://app.leadswarp.com"></script>

示例

<!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代码示例：

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
了解"提交订单"事件的数据结构
进入【Linkflow】-【设置】-【自定义设置】-【自定义事件】
在该页面选择"行业"为【电商】，"所属APP"为【网站追踪】，此时就可以看到电商网站追踪的事件类型列表


调用API实现订单的集成
可根据事件类型的数据，进行创建事件接口调用。
请求示例如下：

{
	"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 里面。

示例代码：

<!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识别联系人方法，识别访问页面联系人。
示例代码：

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代码完成集成的。（参见电商网站场景-特定行为捕获）

渠道
1、获取channelType列表
2、创建自定义渠道

联系人
1、获取联系人自定义字段
2、识别联系人账号
3、查询联系人详情
4、批量获取联系人详情
5、获取联系人列表
6、 批量获取联系人open ID
7、更新联系人

标签
1、创建标签组
2、查询标签组
3、查询联系人的标签组
4、查询标签组联系人
5、添加标签组联系人
6、删除标签组联系人

事件
1、 获取系统事件和自定义事件类型
2、获取事件列表
3、创建自定义事件