MW Logo

mLink Android SDK集成文档

Google Play专属版SDK


一、集成准备

1.1 获取魔窗Appkey

登录魔窗后台管理(http://mgnt.magicwindow.cn)。进入“产品管理”菜单,填写相应内容创建应用,并获取魔窗App Key. (对应移动端AndroidManifest.xml内的MW_APPID)

1.2 添加SDK资源文件

方式①在Gradle依赖中添加:

方式②解压SDK压缩包,引入libs文件夹内的MagicWindowSDK.jar

1.3 添加权限(AndroidManifest.xml内)

1.4 添加魔窗AppId信息(AndroidManifest.xml内)


二、基本功能集成(必加项)

2.1 初始化SDK

在应用程序的启动activity中调用。

2.2 session功能

注:Session为基础功能,必须集成,否则后台无法获取正确报告数据。

方法1:(Android-14之后才起作用。)

在自定义 application 的 oncreate 内调用Session.setAutoSession(this);

如果需要兼容 Android-14 (4.0)之前的版本,请用以方法:

方法2:

在BaseActivity(父类activity)或者每个activity的相应函数里加入以下代码:

注意:
① 如果调用Process.kill或者System.exit之类的方法杀死进程,请务必在此之前调用Session.onKillProcess()方法,用来保证Session正确。
② 如果需要混淆代码,为保证sdk_的正常使用,需要在proguard.cfg_加上如下配置:
-keep class com.tencent.mm.sdk.** {*;}
-keep class cn.magicwindow.** {*;}
-dontwarn cn.magicwindow.**

3.1 名词约定

名称 解释 备注 魔窗后台位置
URL Scheme App之间相互调用的入口,且可传递参数。需要在 AndroidManifest.xml 内启动页activity内填写。 例如:mwsdk://,代码内只要填写 mwsdk 即可,
注意:首字母不能为数字,不支持大写字母,不支持下划线等特殊字符。
顶部导航
->“产品管理”
->“App信息”
->“URI Scheme”
mLink Key mLink 的唯一标识。移动端用此来获取 mLink 具体的 URL Scheme。后台配置 mLink 时填写 注意与代码内register()第一个参数保持一致。 菜单“mLink”
->“服务管理”
->“添加 mLink 服务”
->“mLink 服务 Key”
场景还原 通过 mLink 引导下载 App,第一次启动时自动打开具体页面。

3.2 scheme集成

实现效果:通过短链可以从手机浏览器打开App。

Android系统中App之前是相互隔离的,通过URI Scheme,App之间可以相互调用,并且可以传递参数。

3.3 具体页面跳转

实现效果:通过短链可以从手机浏览器打开App具体页面。

3.3.1 魔窗后台进行配置

登录魔窗后台(mgnt.magicwindow.cn)新建产品,从导航“mLink”菜单进入mLink服务。并配置该服务的唯一标识mLink key

注意:Android URI的编写规则为:scheme://host/path?query,具体编写规则请参考文档。如果需要传参,可按照文档配置。

3.3.2 代码内注册

将在后台配置的mLink key在代码内注册,实现跟App具体页面一一对应。

如果跳转逻辑比较复杂(比如跳转前需要登录或者需要跳转Fragment等),可用3.6.1自定义register()

步骤1:在程序的启动页面的 onCreate()内调用注解注册

MLinkAPIFactory.createAPI(this).registerWithAnnotation(this);

示例:

步骤2:在程序主页(默认页面)如下注册:

示例:

步骤3:其他具体页面:

示例:

注意:
如果有 Fragment 作为页面。①在 mLink 的动态参数添加type来区别是哪个 Fragment。②在它的 FragmentActivity 内添加注解,然后根据type判断具体跳转到哪个 Fragment。

3.3.3 在启动页SplashActivity中调用router()

根据不同的URL路由到不同的app展示页。

注意:①router()后记得调用finish()来结束当前activity。

3.4 场景还原

实现效果:App未安装时,通过短链跳转到下载页面,安装后,第一次打开实现场景还原。

在首页的onCreate()内调用MLinkAPIFactory.createAPI(this).deferredRouter(); 来实现场景还原。

3.5 支持微信内应用宝直跳

实现效果:通过此步骤,可以实现如下功能“借助应用宝,实现从微信内直接打开App具体页面。”

如果下载链接是应用宝,建议支持应用宝下载直跳。

方式:调用checkYYB(final Context ctx, final YYBCallback callback);

此接口有一个callback回调。如果未能跳转到具体页则进入回调,此时调用进入首页代码即可。

3.6 其他API

3.6.1 自定义register接口:

除了registerWithAnnotation(),我们还提供register()。方便客户在跳转前处理一些额外动作,比如登录等。

如跳转前需要登录等,可用下面的register方法替换registerWithAnnotation()注解方法

在程序的启动页面的 onCreate()内注册register() 和 registerDefault()

示例:

注意:在MlinkCallback的excute回调内。不用 MLinkIntentBuilder.buildIntent(),而要自定义跳转到其他的activity。需要给Intent增加Intent.FLAG_ACTIVITY_NEW_TASK | Intent.FLAG_ACTIVITY_CLEAR_TOP两个flag。

示例:

注意:
不管用方式1还是2.都不要忘了default默认跳转!

3.7 系统相关代码

当启动页Activity为singleTop或singleTask的启动模式时,需要在系统回调方法onNewIntent()中将intent设置为新收到的intent,mLink需要根据启动intent判断程序是否是通过Scheme启动,新增如下处理。

示例代码如下:

3.8 mLink API介绍

接口所在类 接口名称 说明 使用方法
MLink registerDefault () 注册默认页面(首页)的回调。
参数:MLinkCallback
对应注解方法的@MLinkDefaultRouter
在启动页的 onCreate 内调用。此接口一定要在 router()接口前调用。
MLink register() 注册其他各页面的回调。通过此接口,用来实现具体页面的跳转逻辑。
参数:mLink Key
参数:MLinkCallback
对应注解方法的@MLinkRouter
在启动页的 onCreate 内调用。此接口一定要在 router()接口前调用。
MLink MLinkCallback () 回调函数。
参数:paramMap为页面的传递参数,可在具体页面通过 intent.getStringExtra(“具体Key”) 获取。
Uri也就是Scheme://host?query.通过外部跳转进来时的具体 uri
MLink router() 跳转的入口。
参数:
Context 上下文
Uri:通过getIntent().getData()获取
一般来说,在启动页的 onCreate()内调用。如果App 有启动动画,可以在动画结束后再调用此接口。
MLink getLastChannelForMLink() 获取mLink短链携带的渠道名称
MLink callbackEnable() 是否可返回其他应用
MLink parseCallBackUri() 返回其他应用的Scheme Uri
MLink returnOriginApp() 返回其他应用

四、高级选项

4.1 ABA跳转

ABA跳转提供的功能是可以让其他App或链接直接跳转到你们的App具体页面。完成相关操作后携带相关信息返回。此时,你们的App便是服务提供方,其他App便是服务使用方。

4.1.1 判断是否可返回其他应用

MLinkAPIFactory.createAPI(this). callbackEnable();

4.1.2 返回其他应用接口

// JSONObject是返回Uri需要的动态参数组成的json, 也就是你们可以返回给其他应用的参数
MLinkAPIFactory.createAPI(this).returnOriginApp (Activity activity, JSONObject dt);
或
//String 返回Uri需要的动态参数,如果只提供一个参数时可用此
MLinkAPIFactory.createAPI(this).returnOriginApp (Activity activity, String dt);

4.1.3 获取返回其他应用的Uri Scheme

通过此接口可以获取其他应用返回时的Uri,可根据此Uri自己实现返回跳转。具体见下面示例。

// JSONObject是返回Uri需要的动态参数组成的json
MLinkAPIFactory.createAPI(this). parseCallBackUri(JSONObject dt);
或
//String 是返回Uri需要的动态参数,如果只提供一个参数时可用此
MLinkAPIFactory.createAPI(this). parseCallBackUri(String dt);

4.1.4 增加ABA返回浮层按钮

通过此API可以在通过mLink服务跳转过来时,显示一个返回的浮层button。支持两个App间互相跳转,用户可通过”返回浮层”随时从跳转方App返回来源方App
方法:在集成过的mLink服务页面相应的activity内调用MWFloatView(Context context)相关API即可。

示例:

注意:如果想让浮层的生命周期跟App相同。可将此代码放在BaseActivity相应位置即可。

4.2 无码邀请

用户A分享App内容给用户B,用户B通过用户A分享的H5页面安装App,则用户A可以累积相应积分,全程无需邀请码。

/**
* 获取无码邀请中传回的值
* @param param key,比如u_id
* @return 相应的值
*/
public String getParam(String param)

4.3 配置应用市场渠道号

方式① 在AndroidManifest.xml内填写

方式② 初始化魔窗mLink时调用setChannel()接口

在应用程序的启动activity中调用。

4.4 API介绍

接口所在类 接口名称 说明 使用方法
MWFloatView show() 显示
MWFloatView dismiss() 隐藏
MWFloatView setTitle() 设置标题
MWFloatView setPreAppParam() 设置带回发送方(A方)的参数

五、测试与调试

5.1 测试前的准备

确认所需的权限都已经添加:INTERNET, READPHONESTATE等

确认MW_APPID与WECHAT_APPID已经正确的写入Androidmanifest.xml

确认MWActivity在Androidmanifest.xml里正确声明

确认Session 正确集成

确认测试手机(或者模拟器)已成功连入网络

5.2 测试流程

使用普通测试流程,请先在程序入口初始化MWConfiguration添加以下代码打开调试模式:

打开调试模式后,您可以在logcat中查看您的数据是否成功发送到魔窗服务器,以及集成过程中的出错原因等。

Log的tag 用途 结果
SDKIntegrationTest 查看集成是否成成功 数据是否成功发送到魔窗服务器(the data has sent successfully)
SDKIntegrationDebug 集成遇到问题时的log 查看集成遇到的问题
SDKDebug 其他log 系统调试的一些其他log

注意:请使用普通测试流程,您的测试数据会与用户的真实使用数据同时处理,从而导致一定的数据污染。

5.3 FAQ

如果对接遇到问题,请参考以下地址:

https://github.com/magicwindow/mw-sdk-faq/blob/master/android-sdk-faq.md