移动模板嵌入 App 开发对接文档

版权声明

       本文档版权归论客科技（广州）有限公司所有，并保留一切权利。未经书面许可，任何公司和个人不得将此文档中的任何部分公开、转载或以其他方式散发给第三方。否则，必将追究其法律责任。

免责声明

       本文档仅提供阶段性信息，所含内容可根据产品的实际情况随时更新，恕不另行通知。如因文档使用不当造成的直接或间接损失，本公司不承担任何责任。

文档更新

       本文档由论客科技（广州）有限公司于2019年1月最后修订。

相关信息

  • 公司网站：http://www.coremail.cn
  • 联系方式
    • 销售咨询热线：400-000-1631
    • 技术支持热线：800-830-5422

产品简介

       Coremail 移动模板是 Coremail 自主研发的基于 Coremail 邮件系统的手机邮件模板。Coremail 移动模板邮件收发功能均采用 HTML5 开发，并支持嵌入到 Native App 中，在 Webview 中运行。

       Coremail 移动模板可内嵌至第三方 App。第三方 App，是指采用 Coremail 邮件系统客户的内部应用，如 OA、CRM、ERP 等 App 应用。

       嵌入后，可通过单点登录等方式，在第三方 App 内部直接使用移动模板的全部功能，包括邮件收发、组织通讯录等。嵌入时，Coremail 移动模板仅提供标准版本，及交互、界面设计等需按照 Coremail 标准，暂不支持大范围定制。

对接指南

一、第三方 App 接入 Coremail 移动模板方式

方式一：加载远程 web 页面

       将 Coremail 移动模板资源部署在服务器端，第三方 App 使用 WebView 加载服务器端移动模板资源。简单地说，第三方 App 相当于一个浏览器，用户打开 Coremail 移动模板就像在浏览器上打开一个网页。

方式二：加载 assets 目录下的本地文件

       第三方 App 将移动模板的相关资源保存在 App 内即将移动模板资源文件本地化，将所需的 html、css、js 等文件放在 assets 目录下，WebView 调用 assets 目录下的本地网页和图片等资源，用户在使用移动模板时只需加载部分内容，如 index.html。

注意事项

  • 1、访问本地文件可能会存在加载文件跨域问题。
    设置是否允许通过 File Url 加载的 JavaScript 可以访问其他的源，包括其他的文件和 http、https 等其他的源。

  • 2、由于访问的是本地文件，移动模板 Ajax 请求数据时，需要第三方 APP 端告知模板当前的 Coremail 服务器地址：

    • 方式一、WebView 将服务器地址设置在 window 对象下。
      如：window.coremailurl = "http://ip/coremail/"

    • 方式二、WebView 加载本地资源页面时，带上服务器地址。
      如：webview.loadUrl("file:///android_asset/www/index.html?coremailurl=xxx")

  • 3、通过访问本地文件加载的方式有 cookie 设置的问题

    • A. 请通过原生代码的 CookieManager 自行响应服务器端通过 header 里 set-cookies 方式设置的 cookie
      • B. Android 系统请开启 file 协议的 cookie 设置权限 CookieManager.setAcceptFileSchemeCookies(true);

二、单点登录解决方案

方案

Coremail 提供单点登录接口 API

       Coremail 提供单点登录接口 API，第三方 App 调用 Coremail 接口（java 或 webservice 接口）生成 sid（单点登录凭证，需传入用户邮箱地址），向移动模板发送请求并传入 sid，实现单点登录。 另外建议单点时主动传入 cookiecheck 的值，可以有效解决页面 cookie 传递的问题及减少大量的单点排错时间, 推荐使用此方案。 单点登录入口由原来的 sso.html 变成 sso.jsp, 注意需要移动模板 v4.5.5 才支持。如果移动模板 < v4.5.5 需要手工部署 main.jsp。举例：

原来单点到收件箱的入口是：

http://service_ip/coremail/hxphone/sso.html#/frame/folder/1?sid=%sid%

调整成：

http://service_ip/coremail/hxphone/main.jsp?sid=%sid%&Cookie.Coremail=%cookiecheck%#/frame/folder/1

即将原来的url hash 后面的 url param 参数改为标准格式，后面的 url hash 值不变。入口文件改为 main.jsp

移动模板支持模块以及各模块入口

这里假设资源路径：location_path

  • 在线资源时假设 location_path 路径为 http://service_ip/coremail/hxphone
  • 本地资源时假设 location_path 路径为 file:///android_asset/www
  • 收件箱入口：location_path/#/frame/folder/1
  • 读信页入口：location_path/#/frame/read/-2/%mid%
  • 通讯录入口：location_path/#/frame/contactList//
  • 写信页入口：location_path/#/frame/compose/// 其中写信页入口支持传递初始化参数，目前支持传递 to（收件人）参数 示例：location_path/#/frame/compose///?to=admin@hx.cn
注意事项
  • 变量 %mid% 需替换为实际的值
  • sid 传入参考第三点
  • 资源本地化时，初始化 WebView 时需设置 Coremail 邮件服务器地址

方案三：利用 jsp 页面实现单点登录（该方案资源本地化时不支持）

       第三方 App 点击 Coremail 移动模板模块时提供账号信息，跳转至单点登录 jsp 页面，jsp 页面单点成功后，重定向至移动模板页面相关界面。这种情况一般使用场景为由 Coremail 团队提供 JSP 单点支持

       若开启 Cookie 检查，服务器端会获取客户端 Cookie 信息，单点登录时进入移动模板，会产生 Cookie 不匹配的问题，需第三方 APP 在 WebView 端根据单点登录返回的信息设置 Cookie。

       第三方 APP 调用 Coremail 单点登录 API 成功后，需对 WebView 设置 Cookie。Cookie 信息如下（根据配置字节长度可能不一致）。

  • 举例：
    • Coremail=bbbb174e9c40cabdb380fdf306fc0ca8
    • Coremail.sid=BAyhCUJJGzlfGZXSXnJJErWZLLJCjDak
    • Coremail.sso=1

注意上面的例子，第一个Coremail的Cookie是要靠单点登录API主动设进去的，即cookiecheck参数对应传入的值（请参考API集成文档说明）， 第二个Cookie.sid则是服务器登录成功返回的值，注意2者不要混淆。

四、Session 过期

       因邮件系统较为敏感，若超过一定时间未有操作，再次对 Coremail 移动模板的内容进行操作时，会提示 Session（会话）过期。此时会跳出邮箱模块（需和第三方 App 沟通如何关闭当前 WebView 视图），若想再次使用移动模板，则第三方 App 重新单点进入。该问题出现概率较小。

五、新邮件到达提醒

       因移动模板无法直接进行消息推送，新邮件到达提醒需第三方 App 与 Coremail 共同处理。第三方 App 提供相关 API 提供至 Coremail，Coremail 根据该接口 API，在收到新邮件时，将相关消息格式及内容通过接口传递至第三方 App，具体的消息提示或到达提醒由第三方 App 进行展示。

       当第三方 App 收到新邮件到达提醒后，可单点登录跳转至移动模板的读信页面。

六、文件上传处理

Android 文件上传处理

       Android 端，默认情况下，使用 Android 的 WebView 不支持文件上传，需第三方 App 端重写原 WebView 附件上传的默认行为。

iOS 文件上传

       第三方 App 需在打包时针对 iOS 10中需要对 info.plist 文件（iOS App 配置文件）进行相关配置，获取相机权限和相册权限。iOS 10系统下如果没开启以下配置，选择文件时可能会导致 APP 闪退的问题。

  • 相机权限： Privacy - Camera Usage Description 是否允许此 App 使用你的相机？
  • 相册权限： Privacy - Photo Library Usage Description 是否允许此 App 访问你的媒体？

七、文件下载处理

       在第三方 App 内嵌 Coremail 移动模板时,由于 H5 前端无法控制文件下载的操作，文件下载处理如进度及文件的存储位置均有第三方 APP 自行处理，Coremail 移动模板只提供文件相关数据，如文件下载 url 地址以及文件大小等信息。

       判断 url 为下载地址，如：url 链接中包含 mode=download 字符串。

Android 下载

       WebView 默认不开启文件下载功能，若想实现下载功能，需第三方 App 设置 WebView 的 DownloadListener，通过实现自己的 DownloadListener 来实现文件的下载。

iOS 下载

       WebView 默认不会对下载链接进去处理。默认情况下 iOS WebView 对于图片、word、txt、pdf 文件的下载链接会直接显示；对于 apk、zip、rar 等文件点击下载会提示中断的信息。若需要实现下载文件并打开，则需要第三方 APP 开发对下载链接进去处理。

八、移动模板客户定制部分交互逻辑问题

       根据客户需求不同，可能部分客户在某些地方交互会和产品标准不一致，为满足客户部分需求，产品规定部分地方客户可实现定制。移动模板提供相关接口，第三方 APP 开发人员需根据文档描述，达到部分交互定制开发。（具体可定制的地方由我方规定）

相关接口对接处理：《移动模板Hook Api文档》

results matching ""

    No results matching ""