{"id":13679247,"url":"https://github.com/suanmei/callapp-lib","last_synced_at":"2025-05-14T10:11:09.136Z","repository":{"id":37752126,"uuid":"141319058","full_name":"suanmei/callapp-lib","owner":"suanmei","description":"🔥call app from h5（H5唤起客户端 ）","archived":false,"fork":false,"pushed_at":"2024-05-06T09:23:36.000Z","size":1957,"stargazers_count":2511,"open_issues_count":27,"forks_count":347,"subscribers_count":30,"default_branch":"4.0","last_synced_at":"2025-04-09T10:02:39.722Z","etag":null,"topics":["callapp","callapp-lib","commitizen","eslint","githook","h5","intent","native","rollup","schema","scheme","universal","universallink","url-scheme"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/suanmei.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-07-17T16:58:55.000Z","updated_at":"2025-03-31T10:21:11.000Z","dependencies_parsed_at":"2024-06-16T12:09:38.006Z","dependency_job_id":null,"html_url":"https://github.com/suanmei/callapp-lib","commit_stats":{"total_commits":147,"total_committers":6,"mean_commits":24.5,"dds":"0.37414965986394555","last_synced_commit":"9cf1fad689e2a51eb50d467613bce4d6a7c7272d"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/suanmei%2Fcallapp-lib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/suanmei%2Fcallapp-lib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/suanmei%2Fcallapp-lib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/suanmei%2Fcallapp-lib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/suanmei","download_url":"https://codeload.github.com/suanmei/callapp-lib/tar.gz/refs/heads/4.0","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248338370,"owners_count":21087207,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["callapp","callapp-lib","commitizen","eslint","githook","h5","intent","native","rollup","schema","scheme","universal","universallink","url-scheme"],"created_at":"2024-08-02T13:01:03.525Z","updated_at":"2025-04-11T03:38:11.042Z","avatar_url":"https://github.com/suanmei.png","language":"TypeScript","funding_links":[],"categories":["目录","TypeScript"],"sub_categories":[],"readme":"# callapp-lib\n\ncallapp-lib 是一个 H5 唤起 APP 的解决方案，能够满足大部分唤起客户端的场景，也预留了扩展口，帮你实现一些定制化的功能。\n\n如果你想了解一些唤端的原理知识，或者阅读下面的文档有不理解的名词，可以访问这篇博客 [H5 唤起 APP 指南](https://suanmei.github.io/2018/08/23/h5_call_app/) 。\n\n如果你在使用 callapp-lib 的过程中，有好的想法或者发现了 bug，提 Issue 就行，作者会及时跟进。\n\n## Install\n\nInstall with [npm](https://www.npmjs.com/):\n\n```sh\nnpm install --save callapp-lib\n```\n\n## Usage\n\n```js\nconst CallApp = require('callapp-lib');\n\nor;\n\nimport CallApp from 'callapp-lib';\n```\n\ncallapp-lib 同样支持 `script` 加载，你可以使用下面的 **cdn 文件（地址在下面的示例中）**，也可以下载 `dist/index.umd.js` 到你的项目中，`index.umd.js` 会暴露一个全局变量 `CallApp` ，这个全局变量和上面 `commonjs` 导入的 `CallApp` 内容是一致的，使用方法也是一致的。\n\n```html\n\u003c!-- 及时下载未压缩的最新版本 Js --\u003e\n\u003cscript src=\"https://unpkg.com/callapp-lib\"\u003e\u003c/script\u003e\n\nor\n\n\u003c!-- 具体某一版本，本例中是 3.1.2 ，下载速度较上面快一些，因为上面的地址会有 302 --\u003e\n\u003cscript src=\"https://unpkg.com/callapp-lib@3.1.2/dist/index.umd.js\"\u003e\u003c/script\u003e\n```\n\ncallapp-lib 中传递出来的是一个类，你需要将它实例化，然后才能去调用实例对象的方法。\n\n```js\nconst options = {\n  key1: 'xxx',\n  key2: 'xxx',\n};\nconst callLib = new CallApp(options);\n\ncallLib.open({\n  param: {},\n  path: 'xxx',\n});\n```\n\n## 答疑\n\n对常见的一些问题进行了[汇总](https://www.yuque.com/egm961/nmf9nm/llbg79)，如果这些问答无法解决你的疑惑，加钉钉群，按照提问模板进行提问\n\n\u003cimg src=\"https://gw.alicdn.com/imgextra/i2/O1CN01lVbsJe1aFuAlli9Lw_!!6000000003301-2-tps-979-1280.png\" width=\"160\" /\u003e\n\n## Options\n\n实例化过程中，需要传递一个 options 对象给类，options 对象各属性需要严格按照下面的格式。\n\n下面所有不是必填的，如果你不需要传值，就不要写这个属性，而不是传递一个空字符串或者空对象，callapp-lib 并未对这种情况进行严格的检测。\n\n### scheme\n\n类型: `object`  \n必填: ✅\n\n用来配置 URL Scheme 所必须的那些 v 字段。\n\n- protocol\n\n  类型: `string`  \n  必填: ✅\n\n  APP 协议，URL Scheme 的 scheme 字段，就是你要打开的 APP 的标识。\n\n- host\n\n  类型: `string`  \n  必填: ❎\n\n  URL Scheme 的 host 字段。\n\n- port\n\n  类型: `string` | `number`  \n  必填: ❎\n\n  URL Scheme 的 port 字段。\n\n### protocol\n\ncallapp-lib 2.0.0 版本已移除，原先的 protocol 移入到新增的 scheme 属性中\n\n### outChain\n\n类型: `object`  \n必填: ❎\n\n外链。我们的 APP 的某些功能可能会集成到另一个 APP 中，为了区分它们的协议，会加上一个中间透明页来分发路由，这层中间页的 URL Scheme 对于我们来说就是外链。当然，这里的外链对 Intent 同样生效。\n\n例：`youku://ykshortvideo?url=xxx`\n\n- protocol (2.0.0 版本由原先的 protocal 修改为 protocol，原先的 protocal 是拼写错误)\n\n  同 URL Scheme 的 scheme 字段，在你的 APP 就和上面的 protocol 属性值相同，在其他 APP 打开就传该 APP 的 scheme 标识。\n\n- path\n\n  参考 URL Scheme 的 path 字段，它代表了该 APP 的具体的某个功页面（功能），这里的 path 就是对应的中间页。\n\n- key\n\n  既然只是中间页，它自然要打开我们真正要打开的页面，所以我们需要把要打开的页面的 URL Scheme 传递过去。就像前端从 URL 的 query 字符串里面取值一样，客户端也是从 URL Scheme 里面来取。至于参数 key 定成什么，大家自己去协商吧，上面的示例中 `url` 也只是一个示例。\n\n### intent\n\n类型: `object`  \n必填: ❎\n\n安卓原生谷歌浏览器必须传递 Intent 协议地址，才能唤起 APP。\n\n它支持以下五个属性，其中 scheme 和 上面的 protocal 一样，其他四个都是 apk 相关信息，其中 package 和 scheme 必传：\n\n- package\n- action\n- category\n- component\n- scheme\n\n### universal\n\n类型: `object`  \n必填: ❎\n\n如果你们的 ios 工程师没有做相应的配置来让 APP 支持 Universal Link，你可以不用传递， _callap-lib_ 将会使用 URL Scheme 来替代它。\n\n- host\n\n  你的 Universal Link 的域名，`apple-app-site-association` 文件就放在这个域名对应的服务器上。\n\n- pathKey\n\n  `3.5.0` 版本以后 `pathKey` 非必填项，`pathkey` 填写与不填写代表了 Universal Link 拼接的两种方式。不建议使用 `pathKey` ，因为使用它拼接的 Universal Link 不贴合 URL 设计思想。\n\n  - 不使用 pathKey：客户端提起 path 信息将会从 url 中获取，而不是从 queryString 中获取\n\n    Universal Link 拼接规则:\n\n    ```js\n    const universalLink = `https://${host}/${open方法中的path}?${open方法中param转换的queryString}`;\n    ```\n\n  - 使用 pathKey：pathKey 就和前面 Intent 的 key 属性一样，只是这里的 pathKey 是客户端用来提取 path 信息的，以便知道调用的是 APP 的哪个页面。这个值也是需要你和 ios 童鞋协商定下来的。\n\n    Universal Link 拼接规则:\n\n    ```js\n    const universalLink = `https://${host}?${pathKey}=${open方法中的path}\u0026${open方法中param转换的queryString}`;\n    ```\n\n### appstore\n\n类型: `string`  \n必填: ✅\n\nAPP 的 App Store 地址，例： `https://itunes.apple.com/cn/app/id1383186862`。\n\n### yingyongbao\n\n类型: `string`  \n必填: ❎\n\nAPP 的应用宝地址，例：`'//a.app.qq.com/o/simple.jsp?pkgname=com.youku.shortvideo'`。如果不填写，则安卓微信中会直接跳转 fallback\n\n### isSupportWeibo\n\n类型: `boolean`  \n必填: ❎\n默认值: false\n是否支持微博，默认不支持\n\n### timeout\n\n类型: `number`  \n必填: ❎  \n默认值: 2000\n\n等待唤端的时间（单位: ms），超时则判断为唤端失败。\n\n### fallback\n\n类型: `string`  \n必填: ✅\n\n唤端失败后跳转的地址。\n\n### logFunc\n\n类型: `function`  \n必填: ❎\n\n```js\n(status: 'pending' | 'failure') =\u003e void;\n```\n\n埋点入口函数。运营同学可能会希望我们在唤端的时候做埋点，将你的埋点函数传递进来，不管唤端成功与否，它都会被执行。当然，你也可以将这个函数另作他用。\n\n这个回调函数会回执行两次，第一次是触发 open 方法，第二次是唤端失败，它有一个入参 status ，它有两个值 `pending` 和 `failure`，分别代表函数触发及唤端失败。\n\n### buildScheme\n\n类型: `function`  \n必填: ❎\n\nurl scheme 自定义拼接函数，内置的 buildScheme 函数是按照 uri 规范来拼接的，如果你们的 app 对 url scheme 有特殊需求，可以自定义这个函数，此函数有两个入参，`(config, options)`, config 是你调用 open 方法是传入的对象，options 是你初始化 callapp-lib 时传入的对象。\n\n## Method\n\n### open\n\n唤端功能。接收一个对象作为参数，该对象支持以下属性：\n\n- path\n\n  类型: `string`\n  必填: ✅\n\n  需要打开的页面对应的值，URL Scheme 中的 path 部分，参照 [H5 唤起 APP 指南](https://suanmei.github.io/2018/08/23/h5_call_app/) 一文中的解释。\n\n  只想要直接打开 app ，不需要打开特定页面，path 传空字符串 `''` 就可以。\n\n- param\n\n  类型: `object`  \n  必填: ❎\n\n  打开 APP 某个页面，它需要接收的参数。\n\n- callback\n  必填: ❎\n\n  类型: `function`\n\n  自定义唤端失败回调函数。传递 `callback` 会覆盖 _callapp-lib_ 库中默认的唤端失败处理逻辑。\n\n### generateScheme\n\n接收一个对象作为参数，该对象包含以下属性：\n\n- path\n- param\n\n属性含义和 `open` 方法参数的属性一致。\n\n返回 URL Scheme。如果你觉得 _callapp-lib_ 的唤端处理方式不符合你的需求，但你又不想费心费力的自己去拼凑 URL Scheme，可以利用这个方法直接生成。\n\n### generateIntent\n\n生成 Intent 地址，接收参数同 `generateScheme` 方法参数。\n\n### generateUniversalLink\n\n生成 Universal Link，接收参数同 `generateScheme` 方法参数。\n\n## 打赏\n\n如果刚好解决了你的问题，如果你心情还不错，如果尚有余粮，可以给作者打赏一杯咖啡哦，爱宁~\n\n\u003cimg src=\"https://gw.alicdn.com/imgextra/i3/O1CN01Mqk09Q1HOAWBMvUt2_!!6000000000747-0-tps-1152-1152.jpg\" width=\"240\" /\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuanmei%2Fcallapp-lib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsuanmei%2Fcallapp-lib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsuanmei%2Fcallapp-lib/lists"}