# 集成指南

## 前置准备

- 权限开通：提供飞书账号，联系飞书项目经理开通权限，并获取服务域名
- 原生集成插件下载：[飞书原生集成工具IDE下载更新文档](http://feishu.feishu.cn/docx/OtX9dXCqYoA9njxawAKcnTd7nob)

## 工程创建指南

### 账号登录

1. 从上面列表中下载对应的飞书原生集成工具插件安装，并重启DevEco-Studio

![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/67f621dfd0379fb268b839fc3ff36b9c_dUDL1celgh.png?lazyload=true&width=1964&height=1424)

2. 打开DevEco-Studio，进入功能列表页
    1. 功能列表页展示当前账号所有的工程。
    1. 点击工程，可进入代码开发

![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/e5bf2f12557406926cb0e6ae50d6f3ee_R3ckdQYOv9.png?lazyload=true&width=1600&height=1324)

3. 在未登录的情况下，Harmony有两个入口可触发登录流程
    1. 工程列表页，点击「新建飞书工程」触发登录流程，
    2. 工程列表页，打开已有工程，Tab栏点击「File」->「New」->「新建飞书工程」触发登录流程

![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/0220f1f1157cd7a5fbd7c0103b4a46ac_pc4vaiSRYK.png?lazyload=true&width=1600&height=1324)
    <br>
    ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/923a7a749c4439937772f10724b31ede_wCymmgY8UC.png?lazyload=true&width=3456&height=2018)
4. 触发登录流程后，首先填写服务域名。具体域名可联系对应飞书技术支持同学获取
5. 域名填写后，点击「校验域名」
    1. 校验成功后可进行下一步；
    2. 校验失败时，需要重新填写正确的域名

![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/2d04da2eeadce100f2d509295fbebe66_yMkfG4fOkf.png?lazyload=true&width=2400&height=1658)
    <br>
    ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/5f2c35744643a722850248ec0272c535_3C02KkWwLe.png?lazyload=true&width=2400&height=1658)
    <br>
    ![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/6d8ead1576043bc03fe40a92a6dfe354_RaiKa7pOvC.png?lazyload=true&width=2400&height=1658)

6. 域名校验通过后，登录开通权限的飞书账号。飞书账号登录成功后点击“下一步”

![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/0e108469f3254d80cd079071a3a5704d_lC9vui4Xm0.png?lazyload=true&width=2400&height=1658)

7. 下拉选择对应要交付的客户名称及客户channel。

![](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/1e7ac1cd80a53409ac4b8a69228e9e5d_a6ddR78khw.png?lazyload=true&width=2400&height=1658)

### 新工程创建

1. 登录完成后，在工程列表页，点击「新建飞书工程」新建工程
    1. 工程列表页展示当前域名+飞书账号下的所有工程。
    1. 同一个工程可以推送给多个客户（channel)，以当前登录的客户为准。可在右上角点击切换客户
    1. 点击具体存储路径，可查看具体文件夹中的工程内容。点击可进入DevEco-Studio中进行代码开发

2. 第一步：填写名称、选择基线版本、项目路径，点击下一步

![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/e43852ecf8fe71ae61b995905a10c5d1_4Bw5KSRn7M.png?lazyload=true&width=2400&height=1658)

3. 创建完成后进入工程内
	1. 左侧展示已经创建出来的工程内容；
    2. 点击右侧「飞书原生集成工具」，可以查看具体的组件能力

![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/2e058b7474ae620089c01b2c59273a05_mFcIO577DJ.png?lazyload=true&width=3456&height=2024)

4. 工程创建完成后，支持切换客户及channel，支持退出登录

![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/a74aa10d9d72306d0dac83a0ea6df105_wqsSVMnaFB.png?lazyload=true&width=3456&height=2024)warning
注意：飞书原生集成开发模式分为在线模式、离线模式两种，根据登录的账号、域名、客户判断。**离线模式和在线模式不可混用。**
- 不可在离线工程里面，切换在线模式的客户及channel
- 不可在在线工程里面，切换离线模式的客户及channel

## 在线模式构建

### **【组件列表】**

1. 组件分为协议组件、能力组件
    1. 协议组件：客户提供实现，飞书调用。此组件可以获取，并发布
    2. 能力组件：飞书提供实现，客户调用 **。** 此组件不可发布

![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/dd1cb0d84eac259961b72e0aaaf766db_UihGHOpT6C.png?lazyload=true&width=3456&height=2018)

2. 组件支持 **模块管理** ，可以将组件关联到本地模块中，整体一起集成构建

1. 默认为空，点击 **添加本地模块** 可创建模块
    1. **勾选** 模块并确认保存，即可将组件关联到本地模块上；**取消勾选**，则组件不再关联到对应的本地模块上。组件与本地模块的关联关系为多对多
    1. 此处不支持删除已创建的本地模块。若有删除诉求，可直接在代码里面操作删除，从而避免在此处直接删除影响代码开发

![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/7e73b365a87674e12d939fb2f71e8937_sF2qWefBqa.png?lazyload=true&width=3456&height=2018)

3. 点击 **查看本地模块，** 可以查看所有创建完成的本地模块，以及模块下关联的所有组件

![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/b93c4455004d14ec76c0ec765e773ffe_eUfANYc7Ak.png?lazyload=true&width=3456&height=2018)

4. 点击 **集成** 可以将所有已经开发的一个或多个本地模块、远端组件创建为集成单。本质为一组模块的版本组合，后续可基于该组合完成构建
    1. 输入集成单名称，选择兼容的飞书版本范围，选择要集成的本地模块、远端组件
    1. 支持自定义已选择的本地模块名称，支持删除已选择的本地模块
    1. 集成单创建完成后，可直接 **去构建**，进入**集成单列表** - **构建详情**页；也可取消，后续按需构建

![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/fde3ae10c350822790c48a03e63de029_Pwyx3L2E5O.png?lazyload=true&width=3456&height=2018)
    <br>
	![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/ce7fe9c13578928fca457648154861e1_bsUSfIbhRu.png?lazyload=true&width=3456&height=2018)

### 【集成单列表】

1. 所有创建的集成单，都会进入到 **集成单列表**
1. 点击 **集成单详情**，可以查看集成单内容，包含集成单名称、兼容的飞书版本、集成的远端组件
    1. 支持基于集成单内的组件，去构建测试包。点击 **去构建**，进入 **构建详情** 页面
    1. 点击 **编辑**，支持编辑修改集成单名称、兼容飞书版本、远端组件
    1. 验证通过的集成单组件，可以点击 **发布** 去发布所有组件。发布成功的组件会进入到 **发布列表**，同时会进入到[原生集成控制台](https://delivery.feishu.cn/page/console/micro-app/alchemy-web/product-list/list?pageNum=1)，用于后续的出包配置测试交付

![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/7a6250dccccbf861f86296e1a73a6b48_77fnRSWCgk.png?lazyload=true&width=3456&height=2018)
    <br>
	![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/7164dfa54afbc4ff09564f645c222e35_QGQGN67oV0.png?lazyload=true&width=3456&height=2018)

3. 点击 **构建详情** ，可选择参数发起构建测试包
    1. 包版本：构建的组件支持的飞书测试包版本
    1. 包类型：arm64架构包、arm64架构包（自带测试签名）
    1. 构建环境：选择所需要构建测试包的客户环境
    1. 其他SDK：客户会集成其他家的SDK，可能与当前厂商功能互斥。可通过构建带客户所有SDK的测试包验证
    1. 加速构建：
        1. 开启加速构建时，会使用老代码构建，但是会提升构建速度到分钟级别
        1. 关闭加速构建时，会使用最新代码构建，但是会降低构建速度到小时级别

所有参数选择完成后，点击 **本地构建** 触发构建测试包。构建列表会缓存最近两周构建的测试包数据，开发者可按需下载；点击 **查看详情** 可查看构建的测试包的具体参数配置

![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/026b697c1b267f0d78fb4f8ac9523ed4_uOJVYF70Ys.png?lazyload=true&width=3456&height=2018)
    <br>
	![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/3d360e11de58ffbf8632c01b5aa97e6b_QiG1TdOiAi.png?lazyload=true&width=3456&height=2018)

### **【发布列表】**

1. **集成单详情** 页面里点击 **发布** 并发布成功的组件，会进入到 **发布列表**，支持按照发布状态筛选
    1. 发布成功：安全合规、兼容性检测通过的组件，显示发布成功；
    1. 发布中：操作发布的组件，飞书侧会进行自动化安全合规、兼容性检测，检测过程中为发布中状态
    1. 发布失败：安全合规、兼容性检测不通过的组件，显示发布失败，点击发布详情里的「检测不通过」支持查看具体不通过的代码原因

### 【调试】
本地构建包为可调试的包。通过 DevEco-Studio 的 Attach to Process by Name 功能可断点调试本地的代码。在 Process name 里选中相应进程即可。
  ![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/1c4b82f69171c4ad24704287c873c998_qRk8Y04cbu.png?lazyload=true&width=3456&height=2018)

## 离线模式构建

离线模式面向私有化客户，如有需要，请联系飞书项目经理
1. 组件列表分为协议组件、能力组件
    1. 协议组件：客户提供实现，飞书调用。
    2. 能力组件：飞书提供实现，客户调用 **。**

![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/9327c34a6fe7d7eb1c81077d323e9200_vFEOfJlfSX.png?lazyload=true&width=3456&height=2024)

2. 组件支持 模块管理 ，可以将组件关联到本地模块中，整体一起集成构建
    1. 默认为空，点击 **添加本地模块** 可创建模块
    2. **勾选** 模块并确认保存，即可将组件关联到本地模块上；**取消勾选**，则组件不再关联到对应的本地模块上。组件与本地模块的关联关系为多对多
    3. 此处不支持删除已创建的本地模块。若有删除诉求，可直接在代码里面操作删除，从而避免在此处直接删除影响代码开发

![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/df2f207b62ee822c80dc2aa4ae81114e_r0W4YMrZlR.png?lazyload=true&width=3456&height=2024)

3. 组件获取并开发完成后，可以根据包类型（Debug包/Release包）构建飞书母包

![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/36dd3bce32c0eb69c8dce0583a9fc15a_szI593YPPn.png?lazyload=true&width=3456&height=2024)