MW Logo

mLink Javascript API 使用说明



1. 引用mLink JS文件.

警告: 请直接使用此链接, 不要将此文件下载到您项目中, 否则, 我们在更新数据结构或API接口后有可能会导致mLink失效。

<script src="https://static.mlinks.cc/scripts/dist/mlink.min.js"></script>

2. 在HTML页面中准备一个或多个用于打开APP的a元素

一般开发者会使用CSS样式重置这个链接的外观,使其看起来像一个按钮,建议使用“打开APP”、“在APP中购买”、“在APP中阅读”等对用户有实际引导意义的文案,请尽量避免使用“下载APP”,在以往的用户使用习惯中我们发现使用“下载APP”的链接对比使用“打开APP”的链接的点击率会低好几倍;

<a id="btnOpenApp">打开APP</a>

3. 魔窗后台配置好mLink必要参数并且生成一条短链

具体请参考 后台mLink配置帮助文档, 短链看上去是这样的: https://a.mlinks.cc/ABCD, 其中ABCD为短链KEY;

4. 初始化mLink



new Mlink({options});

/* ------ 或 -------- */

new Mlink([{options}, {options}, {options}]);

    

options 选项


{
    mlink: "短链KEY",
    button: document.querySelector('a#btnOpenApp'),
    autoLaunchApp : false,
    autoRedirectToDownloadUrl: true,
    downloadWhenUniversalLinkFailed: false,
    inapp : false,
    params: {}
}
    
  1. options.mlink

    类型: String
    必填
    描述: 短链地址或KEY,推荐使用短链KEY, 如您的短链是“https://a.mlinks.cc/ABCD”, 那么options.mlink的值就是ABCD

     

    注意: 旧版本的 mLink JS API 支持options.mlink直接传入一个短链的URL, 而在最新版本中已经不再推荐直接传短链的URL, 但是依然会兼容, 更好的做法是传短链KEY。

     

  2. options.button

    类型: HTMLAnchorElement (传说中的<a/>标签)
    必填
    描述: 打开APP的a标签, 一般会使用CSS定义a标签的外观, 使其看起来像一个按钮;

     

    注意: options.button 是必要参数并且只能是a标签, 不能是button、input或其他HTML元素, 否则Mlink无法初始化成功。为什么button是必要参数? 因为很多浏览器禁止通过JS直接打开APP, 必须通过用户手动点击才能打开应用;

     

  3. options.autoLaunchApp

    类型: Boolean
    选填
    默认: false
    描述: 此选项配置为true时, 用户打开您集成了mlink.js的页面时, 在支持自动打开APP的浏览器和设备中, 将自动唤起APP; 但遗憾的是有一些浏览器因为限制通过JS直接唤起APP, 即使此选项设为true也不能自动打开应用, 此时需要用户手动点击由options.button指定的链接才能打开APP;

     

    提示: 此选项设置为true此时会出现以下情况, 请您自行斟酌是否有必要设置为true;

     

    1. 在Android以及iOS低于9.0的系统中, 微信、QQ、QQ浏览器, 如果在魔窗后台的mLink高级设置中开启了"应用宝跳转", 可以自动唤起应用, 如果没有开启"应用宝跳转", 会重定向到一个"请在浏览器中打开"的引导页面;
    2. 在微博内, 无论是否安装过APP, 都会重定向到一个"请在浏览器中打开"的引导页面;
    3. 在当前设备未安装APP时, iOS 9+ 的Safari会提示: "Safari打不开该网页, 因为该网址无效。", 此提示无法通过JS代码阻止;
    4. 在魔窗后台开启了Universal Link开关时, 不能自动唤起APP, 因为Universal Link必须由用户点击链接才能唤起APP;
    5. Android系统的Chrome、QQ(不是QQ浏览器)和部分基于Chrome内核的浏览器, 不能自动唤起应用, 因为这些浏览器或Web容器需要用户手动点击才能唤起APP;
    6. 在已安装APP情况下, UC、QQ浏览器和iOS 9+的Safari内, 在您的页面加载完成后会自动弹出"是否打开APP"的对话框, 用户点击确认按钮后能打开APP, 点击取消按钮后会无效;
    7. 在一些不支持Scheme和Universal Link的浏览器或Web容器内, 都会因为无法打开APP而引导用户去往下载地址; 如何引导用户下载安装根据 options.autoRedirectToDownloadUrl 的选项走不同的流程;

     

  4. options.autoRedirect

    已废弃, 请使用 options.autoLaunchApp, 用法和功能完全一致;
  5. options.autoRedirectToDownloadUrl

    类型: Boolean
    选填
    默认: true
    描述: 此选项值默认为True, 在打开APP失败的情况下(包括未安装APP、APP没有实现Deeplink、浏览器不支持Deeplink等情况), 自动跳转到下载地址;
    如果为false, 在打开APP失败时, Android 和 iOS7、8会继续停留在您的页面并弹出一个包含下载按钮的Dialog; iOS 9 以上系统并且开启了Universal Link时, 如果打开APP失败, 系统仍然会跳转: 在微信内会显示"请在浏览器打开的提示"、在Safari中会跳转到下载页面;

     

  6. options.inapp

    类型: Boolean
    选填
    默认: false
    描述: 当您的HTML页面被嵌入在APP中的Webview时, 因为APP中调用的Webv View与常规浏览器的功能有差异, mLink所依赖的Universal Link在Webview中会有缺陷, 但是mLink又无法准确检测当前打开的环境是Web iew还是APP, 所以,如果在APP中的Web View使用Mlink时, 为了确保mLink能在iOS 9.0 以上系统中的APP也能正确唤起指定的APP界面, 请将此选项设置为true, 设为true时, mLink会优先使用Custom URI Scheme来唤起指定页面。

     

  7. options.params

    类型: Object
    选填
    描述: 传给APP的参数, 这些参数必须是您在魔窗后台的mLink服务配置中设置好的参数占位符, 否则会被过滤掉; 如果APP已安装, 那么唤起应用时从打开APP的URI Scheme或Universal Link中就能获得参数, 如果是第一次安装, 这些参数可以通过魔窗SDK的API从我们的服务器取回; 关于SDK如何实现mLink请参考:

     

     

    示例:    您在后台的mLink服务配置中填的URI Scheme:    myapp://path/acticle?articleId=:id
    options.params:    { id: '123456' }
    最终的URI Scheme是这样的:    myapp://path/acticle?articleId=123456
  8. options.cparams

    类型: Object
    选填
    描述: 传给APP的参数,用户可以通过这个参数从H5页面传递一些参数到APP内进行使用。这些参数不是魔窗后台的mLink服务配置中设置的参数占位符。
    注意:SDK V3.9.20161010 之后的版本支持。

     

  9. options.tparams

    类型: Object
    选填
    描述:使用这个参数追踪来源,现在支持的参数如下(非下面的参数无效)
    u_id: 来源用户ID
    示例:tparams: {"u_id": "uid-123456"}
    注意:SDK V3.9.20161010 之后的版本支持。

     

5. 代码示例

5.1 如果页面只有一个打开APP的按钮:

代码:


<a id="btnOpenApp" href="javascript:void(0);">打开App</a>

<script>
    new Mlink({
        mlink : "短链KEY",
        button : document.querySelector("a#btnOpenApp")
    });
</script>
    

5.2 如果页面有多个打开APP的按钮:

mlink支持您在页面中同时配置多个打开App的按钮,目标App既可以为同一个,也可以设置为不同的App

实例一:

页面中有两个按钮,点击其中任意一个按钮后打开同一个App。

代码:


<a id="btnOpenApp">打开App 1</a>
<a id="btnOpenApp">打开App 1</a>

<script>

    var buttons = document.querySelectorAll("a#btnOpenApp"); // id"btnOpenApp"的所有a元素

    new Mlink({
        mlink: "短链KEY",
        button: buttons,
    });
</script>

    

 

请注意document.querySelector("xxx")和document.querySelectorAll("xxx")的区别, 前者只返回唯一的一个DOM元素, 后者会返回一个与CSS选择器"xxx"匹配的所有元素的NodeList;

 

实例二:

页面中有多个按钮,每个按钮链接到不同的APP或不同的APP内页。

代码:


<a id="btnOpenApp1">打开App 1</a>
<a id="btnOpenApp2">打开App 2</a>
<a id="btnOpenApp3">打开App 3</a>
<a id="btnOpenApp4">打开App 4</a>

<script>

    var btn_1 = document.querySelector("a#btnOpenApp1");
    var btn_2 = document.querySelector("a#btnOpenApp2");
    var btn_3 = document.querySelector("a#btnOpenApp3");
    var btn_4 = document.querySelector("a#btnOpenApp4");

    var options = [
        {
            mlink: "短链KEY_1",
            button: btn_1
        }, {
            mlink: "短链KEY_2",
            button: btn_2
        }, {
            mlink: "短链KEY_3",
            button: btn_3
        }, {
            mlink: "短链KEY_4",
            button: btn_4
        }
    ];

    new Mlink(options);

</script>