githubmann / callapp-lib

callapp-lib

callapp-lib 是一个 H5 唤起 APP 的解决方案，能够满足大部分唤起客户端的场景，也预留了扩展�?�，帮你实现一些定制化的功能。

如果你想了解一些唤端的原�?�知识，或者阅读下�?�的文档有�?�?�解的�??�?，�?�以访问这篇�?�客 H5唤起APP指�?� 。

如果你在使用 callapp-lib 的过程中，有好的想法或者�?�现了bug，�?? Issue 就行，作者会�?�时跟进。

Install

Install with npm:

$ npm install --save callapp-lib

Usage

const CallApp = require('callapp-lib');

or

import CallApp from 'callapp-lib';

callapp-lib �?�样支�? script 加载，你�?�以使用下�?�的 cdn文件（地�?�在下�?�的示例中），也�?�以下载 dist/index.umd.js 到你的项目中，index.umd.js 会暴露一个全局�?��? CallApp ，这个全局�?��?和上�?� commonjs 导入的 CallApp 内容是一致的，使用方法也是一致的。

<!-- �?�时下载未压缩的最新版本 Js -->
<script src="https://unpkg.com/callapp-lib"></script>

or

<!-- 具体�?一版本，本例中是 2.1.5 ，下载速度较上�?�快一些，因为上�?�的地�?�会有 302 -->
<script src="https://unpkg.com/callapp-lib@2.1.5/dist/index.umd.js"></script>

or

<!-- 这是压缩版本，文件体积会�? 1/2 左�?�，下载速度最快，生产环境建议使用这个 -->
<script src="https://unpkg.com/callapp-lib@2.1.5/dist/index.umd.min.js"></script>

callapp-lib 中传递出�?�的是一个类，你需�?将它实例化，然�?��?能去调用实例对象的方法。

const options = {
  key1: 'xxx',
  key2: 'xxx'
};
const callLib = new CallApp(options);

callLib.open({
  param: {},
  path: 'xxx'
});

Demo

请访问demo页�?�，或访问demo文件

如果你在使用移动端，�?�以扫�??下方二维�?:

Options

实例化过程中，需�?传递一个 options 对象给类，options 对象�?�属性需�?严格按照下�?�的格�?。

下�?�所有�?是必填的，如果你�?需�?传值，就�?�?写这个属性，而�?是传递一个空字符串或者空对象，callapp-lib 并未对这�?情况进行严格的检测。

scheme

类型: object
必填: ✅

用�?��?置 URL Scheme 所必须的那些v字段。

• protocol

  类型: string
  必填: ✅

  APP �??议，URL Scheme 的 scheme 字段，就是你�?打开的 APP 的标识。

• host

  类型: string
  必填: �?�

  URL Scheme 的 host 字段。

• port

  类型: string | number
  必填: �?�

  URL Scheme 的 port 字段。

protocol

callapp-lib 2.0.0 版本已移除，原先的 protocol 移入到新增的 scheme 属性中

outChain

类型: object
必填: �?�

外链。我们的 APP 的�?些功能�?�能会集�?到�?�一个 APP 中，为了区分它们的�??议，会加上一个中间�?明页�?�分�?�路由，这层中间页的 URL Scheme 对于我们�?�说就是外链。当然，这里的外链对 Intent �?�样生效。

例：youku://ykshortvideo?url=xxx

• protocol (2.0.0 版本由原先的 protocal 修改为 protocol，原先的 protocal 是拼写错误)

  �?� URL Scheme 的 scheme 字段，在你的 APP 就和上�?�的 protocol 属性值相�?�，在其他 APP 打开就传该 APP 的 scheme 标识。

• path

  �?�考 URL Scheme 的 path 字段，它代表了该 APP 的具体的�?个功页�?�（功能），这里的 path 就是对应的中间页。

• key

  既然�?�是中间页，它自然�?打开我们真正�?打开的页�?�，所以我们需�?把�?打开的页�?�的 URL Scheme 传递过去。就�?�?端从 URL 的 query 字符串里�?��?�值一样，客户端也是从 URL Scheme 里�?��?��?�。至于�?�数 key 定�?什么，大家自己去�??商�?�，上�?�的示例中 url 也�?�是一个示例。

intent

类型: object
必填: �?�

安�?�原生谷歌�?览器必须传递 Intent �??议地�?�，�?能唤起 APP。

它支�?以下五个属性，其中 scheme 和 上�?�的 protocal 一样，其他四个都是 apk 相关信�?�，其中 package 和 scheme 必传：

• package
• action
• category
• component
• scheme

universal

类型: object
必填: �?�

如果你们的 ios 工程师没有�?�相应的�?置�?�让 APP 支�? Universal Link，你�?�以�?用传递， callap-lib 将会使用 URL Scheme �?�替代它。

• host

  你的 Universal Link 的域�??，apple-app-site-association 文件就放在这个域�??对应的�?务器上。

• pathKey

  pathKey 就和�?�?� Intent 的 key 属性一样，�?�是这里的 pathKey 是客户端用�?��??�?� path 信�?�的，以便知�?�调用的是 APP 的哪个页�?�。这个值也是需�?你和 ios 童鞋�??商定下�?�的。

appstore

类型: string
必填: ✅

APP 的 App Store 地�?�，例： https://itunes.apple.com/cn/app/id1383186862。

yingyongbao

类型: string
必填: ✅

APP 的应用�?地�?�，例：'//a.app.qq.com/o/simple.jsp?pkgname=com.youku.shortvideo'。

timeout

类型: number
必填: �?�
默认值: 2000

等待唤端的时间（�?��?: ms），超时则判断为唤端失败。

fallback

类型: string
必填: ✅

唤端失败�?�跳转的地�?�。

logFunc

类型: function
必填: �?�

埋点入�?�函数。�?�?��?�学�?�能会希望我们在唤端的时候�?�埋点，将你的埋点函数传递进�?�，�?管唤端�?功与�?�，它都会被执行。当然，你也�?�以将这个函数�?�作他用。

buildScheme

类型: function
必填: �?�

url scheme 自定义拼接函数，内置的 buildScheme 函数是按照 uri 规范�?�拼接的，如果你们的 app 对 url scheme 有特殊需求，�?�以自定义这个函数，此函数有两个入�?�，(config, options), config 是你调用 open 方法是传入的对象，options 是你�?始化 callapp-lib 时传入的对象。

Method

open

唤端功能。接收一个对象作为�?�数，该对象支�?以下属性：

• path

  类型: string 必填: ✅

  需�?打开的页�?�对应的值，URL Scheme 中的 path 部分，�?�照 H5唤起APP指�?� 一文中的解释。

  �?�想�?直接打开 app ，�?需�?打开特定页�?�，path 传空字符串 '' 就�?�以。

• param

  类型: object
  必填: �?�

  打开 APP �?个页�?�，它需�?接收的�?�数。

• callback 必填: �?�

  类型: function

  自定义唤端失败回调函数。传递 callback 会覆盖 callapp-lib 库中默认的唤端失败处�?�逻辑。

generateScheme

接收一个对象作为�?�数，该对象包�?�以下属性：

• path
• param

属性�?�义和 open 方法�?�数的属性一致。

返回 URL Scheme。如果你觉得 callapp-lib 的唤端处�?�方�?�?符�?�你的需求，但你�?��?想费心费力的自己去拼凑 URL Scheme，�?�以利用这个方法直接生�?。

generateIntent

生�? Intent 地�?�，接收�?�数�?� generateScheme 方法�?�数。

generateUniversalLink

生�? Universal Link，接收�?�数�?� generateScheme 方法�?�数。