MW Logo

Android SDK接入文档

SDK 下载      常见问题(FAQ)      论坛

请选择需要集成的功能模块

mLink
魔窗位
完整集成


一、集成准备

1.1 获取魔窗Appkey(移动端AndroidManifest.xml内的MW_APPID)

登录魔窗后台管理(http://mgnt.magicwindow.cn),按照步骤提示注册应用。

点击右上角“账户(xxx@xxx.com)”->“App 管理” ,填写相应内容,创建应用。并获取魔窗App Key。

1.2 添加SDK资源文件

1.3 添加权限

1.4 添加activity信息

注意:有关shareSDK的AndroidManifest.xml的配置,如果之前的项目未填写,请参照shareSDK快速集成。


二、基本功能集成

2.1 初始化SDK

请在应用程序的入口Activity的OnCreate()方法中下添加以下代码:

如果希望获取SDK的版本,可以调用:

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正确。
② 如果写了BaseActivity(父类activity),则只在相应的BaseActivity内添加上面的代码即可,不要重复添加。
③ 如果需要混淆代码,为了保证sdk的正常使用,需要在proguard.cfg加上下面两行配置:
-keep class com.tencent.mm.sdk.** {*;}
-keep class cn.magicwindow.** {*;}
-dontwarn cn.magicwindow.**

三、创建活动

3.1 WEB端

登录魔窗后台管理(http://mgnt.magicwindow.cn/),按照步骤获取相应的魔窗位key。

3.2 移动端

移动端最简单的ImageView显示。除了这个方法,我们还提供了具体的后台API数据接口。各开发者如果想自定义布局,可以通过这些接口获取相应数据。下面首先介绍ImageView布局。

3.2.1 布局layout

在需要展示入口的xml文件,把ImageView替换为cn.magicwindow.MWImageView即可。

代码示例:

3.2.2 绑定魔窗位置ID

绑定魔窗位:

判断活动是否开启:

如果想判断此活动是否开启,请用此API。以此为依据,可以在没活动的时候隐藏窗体。

推荐用法:

3.2.3 自定义魔窗窗体

通过3.2.1和3.2.2已经完成魔窗的完整展示以及跳转等所有功能(但展示的仅仅是一张图片),如果你想自定义魔窗的展示布局,可以根据3.2.3或者3.2.4的API获取相应的活动内容,从而自定义布局,以及添加点击事件跳转到相应的webview。

首先明确一个概念,魔窗在后台可配置如下三项内容:活动展示图片、活动标题和活动内容。

我们可以根据这三个要素自定义魔窗的展示窗体。

代码示例:

3.2.4 魔窗位支持mLink或 Aba带返回(callback)等功能

ABA跳转解释:例如,通过“美人相机”的mLink跳转到“美人相机”的拍照页面。拍完后,“美人相机”可以根据callback scheme,携带相关信息返回本应用。

如果想让你的魔窗位支持mLink等功能。请调用带有WithParams字样的API。比如:

MWImageView内的bindEventWithParams(),他们与普通的魔窗API是一一对应

列表:

API 参数说明
MWImageView bindEventWithParams(clickParamsBuilder) 见3.2.5
MarketingHelper clickWithParams(clickParamsBuilder) 见3.2.5

3.2.5 ClickParamsBuilder说明

列表:

API 参数说明
ClickParamsBuilder mLinkParam() 魔窗位需要传递的mLink值:
支持JsonObject和Map格式
ClickParamsBuilder landingPageParam() App未安装,跳转到的HTML页面的Url值:
支持JsonObject和Map格式
ClickParamsBuilder AbaCallbackMLinkKey() ABA跳转时回跳的uri:
支持uri或者mLink的服务Key
ClickParamsBuilder AbaCallbackParam() ABA跳转,回跳时的动态参数值:
支持JsonObject格式
ClickParamsBuilder listener() 魔窗位更改点击事件时调用:
ClickParamsBuilder build() Builder模式的最后调用。

3.2.6 使用自己的Webview来展示魔窗内容

此功能为客户提供如下功能:用户用自己的webview来展示魔窗后台的“外部链接”活动的H5页面。

我们可以利用getWebviewURL来获取H5的URL。然后在bindEvent内的点击listener内处理跳转到客户自己的webview。

3.2.7 魔窗位曝光统计

此在需要的地方调用

3.2.8 活动其他API

1)、更新活动

活动默认更新策略是“随着session程序自动刷新活动”。

前提:准确集成2.2 session统计(每个activity的onResume以及onPause埋进相应代码。Fragment的仅仅是页面统计,如果不需要页面统计信息可忽略)

并且我们提供了相应的broadcast。你可以监听,从而相应刷新处理。

cn.magicwindow.marketing.update.MW_MESSAGE

例子在相应的Activity或者Fragment内:

当然,虽然不推荐,但是如果有需要,你依旧可以通过以下接口来实现单个活动或者全部活动(windowKey传值为null时更新全部活动)

2)、活动展示图片URL(参见3.2.4自定义魔窗位方式1)

3)、活动名称(参见3.2.4自定义魔窗位方式1)

4)、活动的相关描述(参见3.2.4自定义魔窗位方式1)

5)、点击响应(直接分享或者跳转到相应的webView,参见3.2.4自定义魔窗位方式1)

魔窗在APP中自定义展示,需要添加点击事件,点击响应事件

6)、活动的URL

7)、检测所有活动状态

如果你想一下子检测所有开启的活动,那么下面这个接口可以满足你的需求。并且它会把所有开启的活动的windowKey(魔窗位Key)以ArrayList的形式返回给你

8)、检测活动webview生命周期

如果你想要在活动的webview打开或者关闭的时候做一些特殊处理(比如说在webview关闭的时候顺便进入或者关闭某个页面),可用下面的方式

①首先在MWConfiguration打开setWebViewBroadcastOpen(true)
②在AndroidManifest.xml内注册receiver,或者在代码内动态注册(相关代码不再描述)

③自定义的MWBroadCastReceiver类似如下

3.3 移动端动态魔窗位

3.3.1 更新动态魔窗位

可以在程序启动时,或者进入具体页面时,调用此API,用来提前缓存动态魔窗位信息

3.3.2 动态魔窗位的点击事件

在MWDynamicCallback的回调成功时,可以处理动态魔窗的点击事件(为什么在回调内处理?此时可以确保数据的实时性与准确性)


        MWDynamic.click(Context context, final MWDynamicData dynamic)
    

3.3.3 动态魔窗位的绑定

魔窗可以通过MWDynamicCallback将动态魔窗位内的内容返回。开发者可以在此回调内处理相关数据。具体如下:



四、创建广告

4.1 接口说明

4.1.1 广告展示接口

4.1.2 RenderAd说明

4.1.3 广告点击接口

4.1.4 广告曝光统计接口

4.2 示例代码

4.3 其他

如果广告只展示一张图片,如同第三部分的魔窗位展示,可以用MWImageView内的bindEventWithAd(Activity act,String windowKey)直接展示。


五、事件统计

5.1 地理位置经纬度传递

如果需要,可通过下面这个API将经纬度传递过来。

5.2 页面统计

5.2.1 只由activity构成的页面

如果您已经完成2.3步骤的代码添加,那么SDK已默认统计了每个Activity的跳转路径。页面统计不需要再添加其他代码。

5.2.2 包含activity、Fragment或者View作为页面的应用

统计程序中包含Fragment的情况比较复杂,首先要明确一些概念。

① TrackAgent.currentEvent().onResume()和TrackAgent.currentEvent().onPause()方法是用来统计应用时长的(也就是Session时长,当然还包括一些其他功能);

② TrackAgent.currentEvent().onPageStart() 和 TrackAgent.currentEvent().onPageEnd() 方法是用来统计页面跳转的。

在仅有Activity的程序中,SDK 自动帮助开发者调用了②中的方法,并把Activity 类名作为页面名称统计。但是在包含fragment的程序中我们希望统计更详细的页面,所以需要自己调用方法做更详细的统计。首先,需要在程序入口处MWConfiguration,打开setPageTrackWithFragment(true) 页面统计方式,这样将不会再自动统计Activity。

然后需要做两步集成:

1、使用 onResume 和 onPause 方法统计时长, 这和基本统计中的情况一样(针对Activity);

2、使用 onPageStart 和 onPageEnd 方法统计页面(针对页面,页面可能是Activity也可能是Fragment或View)。

对于一些典型应用,比如页面是直接放在Activity里面的,统计代码大约是这样:

如果页面是使用FragmentActivity+Fragment实现的,需要在FragmentActivity中统计时长:

并在其包含的Fragment中统计页面:

需要注意的是这些方法的调用,需要保证线性不交叉,每个start都有一个end配对,如下:

onPageStart -> onPageEnd -> onPageStart -> onPageEnd -> onPageStart -> onPageEnd

这样才能保证每个页面统计的正确。

注意:如果开发者调用Process.kill或者System.exit之类的方法杀死进程,请务必在此之前调用TrackAgent.currentEvent().onKillProcess()方法,用来保存统计数据。

5.3 自定义事件类型

自定义事件分为2大类:

1、统计次数(时间点事件):统计指定行为被触发的次数。

2、统计时长(时间段事件):统计指定行为消耗的时间,单位为秒。需要begin接口与end接口成对使用才生效。

其中每类事件都有Key-Value参数类型和不定长字符串参数类型。

注意:
1、如果代码同时使用了这2种参数类型,event_id最好不一样。
2、event_id需要先在魔窗网站上面注册,才能参与正常的数据统计。event_id不能包含空格或转义字符。

5.3.1 注册自定义事件

自定义事件的注册(配置)包括事件id的注册和事件,id下参数信息的注册。

step1:登陆魔窗前台,选择左边选择“自定义事件”。

step2:选择“新增事件”,按照需求填写事件id、key、value等信息。

step3:可以在查看详情下的“参数”查看事件id下所有参数上报的明细。

5.3.2 统计场景举例

1、时间点事件

统计发生次数

统计带属性的行为触发次数

统计电商应用中“购买”事件发生的次数,以及购买的商品类型及数量,那么在购买的函数里调用。

代码示例:

2、时间段事件

代码示例:

5.4 错误统计

SDK从内建错误统计,不需要开发者再手动集成。SDK自动捕获程序崩溃日志,并在程序下次启动时发送到服务器。

如不需要错误统计功能,在初始化MWConfiguration时调用setCrashTrackOff关闭。

如果开发者自己捕获了错误,需要上传到友盟服务器可以调用下面方法:

5.5 渠道(channel)填写

<meta-data android:name="MW_CHANNEL" android:value="Channel ID"/>中的Channel ID替换为您应用的推广渠道名称。

例如在豌豆荚渠道推广此包,代码示例:

如不想在manifest里配置渠道(channel),可在Activity中配置,只需在MWConfiguratio初始化的时候指定即可。

注意:AndroidManife.xml里的优先级最高。如果此处定义了channel,则优先使用此定义。
命名规范例:

1、可以由英文字母、阿拉伯数字、下划线、中划线、空格、括号组成,可以含汉字以及其他明文字符,但是不推荐使用;

2、首尾字符不可以为空格;

3、最多256个字符;

4、"unknown" 及其各种大小写形式,作为魔窗保留的字段,不可以作为渠道名。

5.6 用户信息统计

如果需要将用户的一些信息,比如用户名或者手机号(注意隐私)储存到魔窗服务器,以便节省某些活动的再次输入。可利用以下接口传递。

在用户登录时,调用:

在用户注销登录时,调用:

其中UserProfile各接口如下:

5.7 区域定向

魔窗的区域定向,默认使用ip定位。调用以下API通过行政区划代码可手动定位。定位后会自动刷新活动

初始化时,可调用MWConfigration内的setCityCode()定位。或者在其他时候调用TrackAgent.currentEvent().TracksetCityCode(String cityCode);

注:活动区域仅支持到地级市。(比如只能定位到北京,北京下面的城区不能定位)。
中华人民共和国县以上行政区划代码参考链接:http://files2.mca.gov.cn/www/201510/20151027164514222.htm



6.1 名词约定

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

6.2 mLink集成步骤

mLink提供的功能是可以让其他App或链接直接跳转到你们的App具体页面。此时,你们的App便是服务提供方,其他App便是服务使用方。

6.2.1 配置app的URL Scheme

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

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

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

在公共Activity的onStart()方法中调用如下代码:

注意:①router()后记得调用finish()来结束当前activity。
②如果想按返回键返回首页,可以将router方法中的gotoHome()放在if判断外面,如下:

6.3 具体页面跳转

6.3.1 魔窗后台进行配置

登录魔窗后台(mgnt.magicwindow.cn)新建产品,并添加mLink服务。(具体见相关文档)
在后台添加相应的mLink服务,并配置该服务的唯一标识mLink key

6.3.2 代码内注册

在应用程序启动页SplashActivity中调用注册,如果跳转比较复杂,比如跳转前需要登录或者需要跳转Fragment等,可用3.6.1自定义register()

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

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

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

步骤3:其他具体页面:

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

6.3.3 场景还原

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

6.4 支持应用宝直跳

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

方式①

Android的应用宝跳转,checkYYB需要在初始化(耗时的)之后,调用startActivity进入首页的同时调用MLinkAPIFactory.createAPI(this).checkYYB();

方式②

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

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

6.5 系统相关代码

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

示例代码如下:

6.6 其他API

6.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默认跳转!

6.6.2 不带回调的应用宝接口

跟checkYYB(final Context ctx, final YYBCallback callback)相比,不带回调


        MLinkAPIFactory.createAPI(this).checkYYB();
    

如果使用此接口,可参照下面的写法,在启动页内

6.7 ABA跳转

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


        MLinkAPIFactory.createAPI(this). callbackEnable();
    

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


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

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


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

6.7.4 增加ABA返回浮层按钮

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

6.8 无码邀请

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


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

6.9 mLink API介绍

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

七、测试与调试

7.1 测试前的准备

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

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

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

确认所有的Activity中都调用了onResume和onPause方法;

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

7.2 普通测试流程

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

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

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

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

7.3 魔窗后台验证SDK对接

如何验证SDK已经对接成功,请参看http://documentation.magicwindow.cn/?mlink-integration-validation