MW Logo

魔窗mLink JS集成文档



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({
    mlink:'https://a.mlinks.cc/ABCD',//短链地址
    button:document.querySelector('a#btnOpenApp')
});
/* ------ 或 -------- */
var link='https://a.mlinks.cc/ABCD';//短链地址
var btn_1=document.querySelector('a#btnOpenApp1');
var btn_2=document.querySelector('a#btnOpenApp2');
var btn_3=document.querySelector('a#btnOpenApp3');

var options = [
    {
        mlink: link+'?name=1',
        button: btn_1
    }, {
        mlink:link+'?name=2',
        button: btn_2
    }, {
        mlink: link+'?name=3',
        button: btn_3
    }
];

new Mlink(options);

5. 在H5页面中使用默认短链接进行动态传参

短链接可以从外部直接唤起App指定页面,那么就可以应用在H5页面中,从而实现在H5中看到什么内容,在App中看到对应的内容。

而且当有很多同类的H5内容时,可以只使用一个默认短链接做到动态传递参数,在App对应打开该参数的对应内容。

实现方法:

这里,给出用带有“打开app” banner链接的代码例子。H5页面里,请务必使用我们的mLink JS 代码加载按钮的点击事件,而不是直接使用短链,否则即使是iOS9 并且使用了Universal Link,也会出现一个中间页面才能唤醒App,而不是一键唤醒。

6. 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.autoRedirectToDownloadUrl

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

     

  5. 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来唤起指定页面。

     

  6. 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
  7. options.cparams

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

     

  8. options.tparams

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